Skip to content

Update cli config #1271

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Nov 4, 2025
Merged

Update cli config #1271

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0c020f4
Update cli config
hinthornw Nov 4, 2025
4ca9684
Update src/langsmith/cli.mdx
hinthornw Nov 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 37 additions & 12 deletions src/langsmith/cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,6 @@ sidebarTitle: LangGraph CLI
```bash [Python (pip)]
pip install langgraph-cli
```
```bash Homebrew
brew install langgraph-cli
```
```bash JavaScript
# Use latest on demand
npx @langchain/langgraph-cli
Expand Down Expand Up @@ -50,9 +47,9 @@ For JS, use `npx @langchain/langgraph-cli <command>` (or `langgraphjs` if instal

## Configuration file

The LangGraph CLI requires a JSON configuration file that follows this [schema](https://raw.githubusercontent.com/langchain-ai/langgraph/refs/heads/main/libs/cli/schemas/schema.json). It contains the following properties:
To build and run a valid application, the LangGraph CLI requires a JSON configuration file that follows this [schema](https://raw.githubusercontent.com/langchain-ai/langgraph/refs/heads/main/libs/cli/schemas/schema.json). It contains the following properties:

<Note>The LangGraph CLI defaults to using the configuration file <strong>langgraph.json</strong> in the current directory.</Note>
<Note>The LangGraph CLI defaults to using the configuration file named <strong>langgraph.json</strong> in the current directory.</Note>

<Tabs>
<Tab title="Python">
Expand All @@ -72,8 +69,8 @@ The LangGraph CLI requires a JSON configuration file that follows this [schema](
| <span style={{ whiteSpace: "nowrap" }}>`pip_installer`</span> | _(Added in v0.3)_ Optional. Python package installer selector. It can be set to `"auto"`, `"pip"`, or `"uv"`. From version 0.3 onward the default strategy is to run `uv pip`, which typically delivers faster builds while remaining a drop-in replacement. In the uncommon situation where `uv` cannot handle your dependency graph or the structure of your `pyproject.toml`, specify `"pip"` here to revert to the earlier behaviour. |
| <span style={{ whiteSpace: "nowrap" }}>`keep_pkg_tools`</span> | _(Added in v0.3.4)_ Optional. Control whether to retain Python packaging tools (`pip`, `setuptools`, `wheel`) in the final image. Accepted values: <ul><li><code>true</code> : Keep all three tools (skip uninstall).</li><li><code>false</code> / omitted : Uninstall all three tools (default behaviour).</li><li><code>list[str]</code> : Names of tools <strong>to retain</strong>. Each value must be one of "pip", "setuptools", "wheel".</li></ul>. By default, all three tools are uninstalled. |
| <span style={{ whiteSpace: "nowrap" }}>`dockerfile_lines`</span> | Array of additional lines to add to Dockerfile following the import from parent image. |
| <span style={{ whiteSpace: "nowrap" }}>`checkpointer`</span> | Configuration for the checkpointer. Contains a `ttl` field which is an object with the following keys: <ul><li>`strategy`: How to handle expired checkpoints (e.g., `"delete"`).</li><li>`sweep_interval_minutes`: How often to check for expired checkpoints (integer).</li><li>`default_ttl`: Default time-to-live for checkpoints in **minutes** (integer); applied to newly created checkpoints/threads only (existing data is unchanged). Defines how long checkpoints are kept before the specified strategy is applied.</li></ul> |
| <span style={{ whiteSpace: "nowrap" }}>`http`</span> | HTTP server configuration with the following fields: <ul><li>`app`: Path to custom Starlette/FastAPI app (e.g., `"./src/agent/webapp.py:app"`). See [custom routes guide](/langsmith/custom-routes).</li><li>`cors`: CORS configuration with fields for `allow_origins`, `allow_methods`, `allow_headers`, etc.</li><li>`configurable_headers`: Define which request headers to exclude or include as a run's configurable values.</li><li>`disable_assistants`: Disable `/assistants` routes</li><li>`disable_mcp`: Disable `/mcp` routes</li><li>`disable_meta`: Disable `/ok`, `/info`, `/metrics`, and `/docs` routes</li><li>`disable_runs`: Disable `/runs` routes</li><li>`disable_store`: Disable `/store` routes</li><li>`disable_threads`: Disable `/threads` routes</li><li>`disable_ui`: Disable `/ui` routes</li><li>`disable_webhooks`: Disable webhooks calls on run completion in all routes</li><li>`mount_prefix`: Prefix for mounted routes (e.g., "/my-deployment/api")</li></ul> |
| <span style={{ whiteSpace: "nowrap" }}>`checkpointer`</span> | Configuration for the checkpointer. Supports: <ul><li>`ttl` (optional): Object with `strategy`, `sweep_interval_minutes`, `default_ttl` controlling checkpoint expiry.</li><li>`serde` (optional, 0.5+): Object with `allowed_json_modules` and `pickle_fallback` to tune deserialization behavior.</li></ul> |
Copy link

Copilot AI Nov 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The checkpointer configuration descriptions are identical for both Python and JavaScript tabs, but they should clarify whether serde.pickle_fallback applies to both languages or only Python, since pickle is Python-specific.

Copilot uses AI. Check for mistakes.
| <span style={{ whiteSpace: "nowrap" }}>`http`</span> | HTTP server configuration with the following fields: <ul><li>`app`: Path to custom Starlette/FastAPI app (e.g., `"./src/agent/webapp.py:app"`). See [custom routes guide](/langsmith/custom-routes).</li><li>`cors`: CORS configuration with fields such as `allow_origins`, `allow_methods`, `allow_headers`, `allow_credentials`, `allow_origin_regex`, `expose_headers`, and `max_age`.</li><li>`configurable_headers`: Define which request headers to expose as configurable values via `includes` / `excludes` patterns.</li><li>`logging_headers`: Mirror of `configurable_headers` for excluding sensitive headers from logs.</li><li>`middleware_order`: Choose how custom middleware and auth interact. `auth_first` runs authentication hooks before custom middleware, while `middleware_first` (default) runs your middleware first.</li><li>`enable_custom_route_auth`: Apply auth checks to routes added through `app`.</li><li>`disable_assistants`, `disable_mcp`, `disable_meta`, `disable_runs`, `disable_store`, `disable_threads`, `disable_ui`, `disable_webhooks`: Disable built-in routes or hooks.</li><li>`mount_prefix`: Prefix for mounted routes (e.g., "/my-deployment/api").</li></ul> |
Copy link

Copilot AI Nov 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nitpick] The table cell contains an extensive list of nested fields that makes it difficult to read. Consider breaking this into a separate subsection with proper formatting or linking to a dedicated page for HTTP configuration details, especially since a new 'Customizing HTTP middleware and headers' section was added below at line 295.

Copilot uses AI. Check for mistakes.
| <span style={{ whiteSpace: "nowrap" }}>`api_version`</span> | _(Added in v0.3.7)_ Which semantic version of the LangGraph API server to use (e.g., `"0.3"`). Defaults to latest. Check the server [changelog](/langsmith/langgraph-server-changelog) for details on each release. |
</Tab>
<Tab title="JS">
Expand All @@ -84,7 +81,8 @@ The LangGraph CLI requires a JSON configuration file that follows this [schema](
| <span style={{ whiteSpace: "nowrap" }}>`store`</span> | Configuration for adding semantic search and/or time-to-live (TTL) to the BaseStore. Contains the following fields: <ul><li>`index` (optional): Configuration for semantic search indexing with fields `embed`, `dims`, and optional `fields`.</li><li>`ttl` (optional): Configuration for item expiration. An object with optional fields: `refresh_on_read` (boolean, defaults to `true`), `default_ttl` (float, lifespan in **minutes**; applied to newly created items only; existing items are unchanged; defaults to no expiration), and `sweep_interval_minutes` (integer, how often to check for expired items, defaults to no sweeping).</li></ul> |
| <span style={{ whiteSpace: "nowrap" }}>`node_version`</span> | Specify `node_version: 20` to use LangGraph.js. |
| <span style={{ whiteSpace: "nowrap" }}>`dockerfile_lines`</span> | Array of additional lines to add to Dockerfile following the import from parent image. |
| <span style={{ whiteSpace: "nowrap" }}>`checkpointer`</span> | Configuration for the checkpointer. Contains a `ttl` field which is an object with the following keys: <ul><li>`strategy`: How to handle expired checkpoints (e.g., `"delete"`).</li><li>`sweep_interval_minutes`: How often to check for expired checkpoints (integer).</li><li>`default_ttl`: Default time-to-live for checkpoints in **minutes** (integer); applied to newly created checkpoints/threads only (existing data is unchanged). Defines how long checkpoints are kept before the specified strategy is applied.</li></ul> |
| <span style={{ whiteSpace: "nowrap" }}>`checkpointer`</span> | Configuration for the checkpointer. Supports: <ul><li>`ttl` (optional): Object with `strategy`, `sweep_interval_minutes`, `default_ttl` controlling checkpoint expiry.</li><li>`serde` (optional, 0.5+): Object with `allowed_json_modules` and `pickle_fallback` to tune deserialization behavior.</li></ul> |
Copy link

Copilot AI Nov 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The checkpointer configuration descriptions are identical for both Python and JavaScript tabs, but they should clarify whether serde.pickle_fallback applies to both languages or only Python, since pickle is Python-specific.

Suggested change
| <span style={{ whiteSpace: "nowrap" }}>`checkpointer`</span> | Configuration for the checkpointer. Supports: <ul><li>`ttl` (optional): Object with `strategy`, `sweep_interval_minutes`, `default_ttl` controlling checkpoint expiry.</li><li>`serde` (optional, 0.5+): Object with `allowed_json_modules` and `pickle_fallback` to tune deserialization behavior.</li></ul> |
| <span style={{ whiteSpace: "nowrap" }}>`checkpointer`</span> | Configuration for the checkpointer. Supports: <ul><li>`ttl` (optional): Object with `strategy`, `sweep_interval_minutes`, `default_ttl` controlling checkpoint expiry.</li><li>`serde` (optional, 0.5+): Object with `allowed_json_modules` and <strong>`pickle_fallback` (Python only)</strong> to tune deserialization behavior. <em>Note: <code>pickle_fallback</code> is only available in Python and is ignored in JavaScript.</em></li></ul> |

Copilot uses AI. Check for mistakes.
| <span style={{ whiteSpace: "nowrap" }}>`http`</span> | HTTP server configuration mirroring the Python options: <ul><li>`cors` with `allow_origins`, `allow_methods`, `allow_headers`, `allow_credentials`, `allow_origin_regex`, `expose_headers`, `max_age`.</li><li>`configurable_headers` and `logging_headers` pattern lists.</li><li>`middleware_order` (`auth_first` or `middleware_first`).</li><li>`enable_custom_route_auth` plus the same boolean route toggles as above.</li></ul> |
| <span style={{ whiteSpace: "nowrap" }}>`api_version`</span> | _(Added in v0.3.7)_ Which semantic version of the LangGraph API server to use (e.g., `"0.3"`). Defaults to latest. Check the server [changelog](/langsmith/langgraph-server-changelog) for details on each release. |
</Tab>
</Tabs>
Expand Down Expand Up @@ -249,11 +247,10 @@ The LangGraph CLI requires a JSON configuration file that follows this [schema](
<a id="ttl"></a>
#### Configuring checkpoint Time-to-Live

You can configure the time-to-live (TTL) for checkpoints using the `checkpointer` key. This determines how long checkpoint data is retained before being automatically handled according to the specified strategy (e.g., deletion). The `ttl` configuration is an object containing:
You can configure the time-to-live (TTL) for checkpoints using the `checkpointer` key. This determines how long checkpoint data is retained before being automatically handled according to the specified strategy (e.g., deletion). Two optional sub-objects are supported:

* `strategy`: The action to take on expired checkpoints (currently `"delete"` is the only accepted option).
* `sweep_interval_minutes`: How frequently (in minutes) the system checks for expired checkpoints.
* `default_ttl`: The default lifespan of a checkpoint in **minutes**. Applies only to checkpoints/threads created after deployment; existing data is not modified.
* `ttl`: Includes `strategy`, `sweep_interval_minutes`, and `default_ttl`, which collectively set how checkpoints expire.
* `serde` _(LangGraph server 0.5+)_ : Lets you control deserialization behavior for checkpoint payloads.

Here's an example setting a default TTL of 30 days (43200 minutes):

Expand All @@ -276,6 +273,34 @@ The LangGraph CLI requires a JSON configuration file that follows this [schema](

In this example, checkpoints older than 30 days will be deleted, and the check runs every 10 minutes.

#### Configuring checkpointer serde

The `checkpointer.serde` object shapes deserialization:

* `allowed_json_modules` defines an allow list for custom Python objects you want the server to be able to deserialize from payloads saved in "json" mode. This is a list of `[path, to, module, file, symbol]` sequences. If omitted, only LangChain-safe defaults are allowed. You can unsafely set to `true` to allow any module to be deserialized.
* `pickle_fallback`: Whether to fall back to pickle deserialization when JSON decoding fails.

```json
{
"checkpointer": {
"serde": {
"allowed_json_modules": [
["my_agent", "auth", "SessionState"]
]
}
}
}
```

#### Customizing HTTP middleware and headers

The `http` block lets you fine-tune request handling:

* `middleware_order`: Choose `"auth_first"` to run authentication before your middleware, or `"middleware_first"` (default) to invert that order.
* `enable_custom_route_auth`: Extend authentication to routes you mount through `http.app`.
* `configurable_headers` / `logging_headers`: Each accepts an object with optional `includes` and `excludes` arrays; wildcards are supported and exclusions run before inclusions.
Copy link

Copilot AI Nov 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The statement 'exclusions run before inclusions' describes processing order but doesn't clarify the practical implication for users. Consider adding an example or note such as: 'Exclusions are processed first, meaning headers matching an exclude pattern will not be included even if they match an include pattern.'

Suggested change
* `configurable_headers` / `logging_headers`: Each accepts an object with optional `includes` and `excludes` arrays; wildcards are supported and exclusions run before inclusions.
* `configurable_headers` / `logging_headers`: Each accepts an object with optional `includes` and `excludes` arrays; wildcards are supported and exclusions run before inclusions.
Exclusions are processed first, meaning headers matching an exclude pattern will not be included even if they match an include pattern.

Copilot uses AI. Check for mistakes.
* `cors`: In addition to `allow_origins`, `allow_methods`, and `allow_headers`, you can set `allow_credentials`, `allow_origin_regex`, `expose_headers`, and `max_age` for detailed browser control.

<a id="api-version"></a>
#### Pinning API version

Expand Down