> ## Documentation Index > Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-change-1791323909-75c753a.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # LangGraph CLI **LangGraph CLI** is a command-line tool for building and running the [Agent Server](/langsmith/agent-server) locally. The resulting server exposes all API endpoints for runs, threads, assistants, etc., and includes supporting services such as a managed database for checkpointing and storage. ## Installation 1. Ensure Docker is installed (e.g., `docker --version`). 2. Install the CLI: ```bash [Python (pip)] theme={null} pip install langgraph-cli ``` ```bash JavaScript theme={null} # Use latest on demand npx @langchain/langgraph-cli # Or install globally (available as `langgraphjs`) npm install -g @langchain/langgraph-cli ``` 3. Verify the install ```bash [Python (pip)] theme={null} langgraph --help ``` ```bash JavaScript theme={null} npx @langchain/langgraph-cli --help ``` ### Quick commands | Command | What it does | | - | - | | [`langgraph dev`](#dev) | Starts a lightweight local dev server (no Docker required), ideal for rapid testing. | | [`langgraph build`](#build) | Builds a Docker image of your LangGraph API server for deployment. | | [`langgraph deploy`](#deploy) | Builds and deploys a LangGraph image directly to LangSmith Deployments in a single step. | | [`langgraph dockerfile`](#dockerfile) | Emits a Dockerfile derived from your config for custom builds. | | [`langgraph up`](#up) | Starts the LangGraph API server locally in Docker. Requires Docker running; LangSmith API key for local dev; license for production. | For JS, use `npx @langchain/langgraph-cli ` (or `langgraphjs` if installed globally). ## Configuration file 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: The LangGraph CLI defaults to using the configuration file named langgraph.json in the current directory. | Key | Description | | - | - | | `dependencies` | **Required**. Array of dependencies for LangSmith API server. Dependencies can be one of the following:
  • A single period (`"."`), which will look for local Python packages.
  • The directory path where `pyproject.toml`, `setup.py` or `requirements.txt` is located.
    For example, if `requirements.txt` is located in the root of the project directory, specify `"./"`. If it's located in a subdirectory called `local_package`, specify `"./local_package"`. Do not specify the string `"requirements.txt"` itself.
  • A Python package name.
| | `graphs` | **Required**. Mapping from graph ID to path where the compiled graph or a function that makes a graph is defined. Example:
  • `./your_package/your_file.py:variable`, where `variable` is an instance of `langgraph.graph.state.CompiledStateGraph`
  • `./your_package/your_file.py:make_graph`, where `make_graph` is a function that takes a config dictionary (`langchain_core.runnables.RunnableConfig`) and returns an instance of `langgraph.graph.state.StateGraph` or `langgraph.graph.state.CompiledStateGraph`. See [how to rebuild a graph at runtime](/langsmith/graph-rebuild) for more details.
| | `auth` | *(Added in v0.0.11)* Authentication and authorization configuration. Contains:
  • `path` (required): Path to your authentication handler (e.g., `./your_package/auth.py:auth`), where `auth` is an instance of `langgraph_sdk.Auth`. See [authentication guide](/langsmith/auth).
  • `disable_studio_auth` (optional): If `true`, Studio cannot use LangSmith auth as a fallback. Defaults to `false`.
  • `allow_langsmith_api_keys` (optional, Agent Server v0.14.0rc2+): If `true`, run LangSmith API-key auth alongside custom auth. Requests with an `Authorization` header go to custom auth; all others go to LangSmith (`x-api-key`). Custom `@auth.on` handlers still run. Defaults to `false`.
  • `openapi` (optional): Security schemes to document in OpenAPI. See [OpenAPI security](/langsmith/openapi-security).
| | `base_image` | Optional. Base image to use for the LangGraph API server. Defaults to `langchain/langgraph-api` or `langchain/langgraphjs-api`. Use this to pin your builds to a particular version of the langgraph API, such as `"langchain/langgraph-server:0.2"`. See [https://hub.docker.com/r/langchain/langgraph-server/tags](https://hub.docker.com/r/langchain/langgraph-server/tags) for more details. (added in `langgraph-cli==0.2.8`) | | `image_distro` | Optional. Linux distribution for the base image. Must be one of `"debian"`, `"wolfi"`, `"bookworm"`, or `"bullseye"`. If omitted, defaults to `"debian"`. Available in `langgraph-cli>=0.2.11`. | | `env` | Path to `.env` file or a mapping from environment variable to its value. | | `store` | Configuration for adding semantic search and/or time-to-live (TTL) to the BaseStore. Contains the following fields:
  • `index` (optional): Configuration for semantic search indexing with fields `embed`, `dims`, and optional `fields`.
  • `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).
| | `ui` | Optional. Named definitions of UI components emitted by the agent, each pointing to a JS/TS file. (added in `langgraph-cli==0.1.84`) | | `python_version` | `3.11`, `3.12`, or `3.13`. Defaults to `3.11`. | | `node_version` | Specify `node_version: 20` to use LangGraph.js. | | `pip_config_file` | Path to `pip` config file. | | `pip_installer` | *(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. | | `keep_pkg_tools` | *(Added in v0.3.4)* Optional. Control whether to retain Python packaging tools (`pip`, `setuptools`, `wheel`) in the final image. Accepted values:
  • true : Keep all three tools (skip uninstall).
  • false / omitted : Uninstall all three tools (default behaviour).
  • list\[str] : Names of tools to retain. Each value must be one of "pip", "setuptools", "wheel".
. By default, all three tools are uninstalled. | | `dockerfile_lines` | Array of additional lines to add to Dockerfile following the import from parent image. | | `checkpointer` | Configuration for the checkpointer. Supports:
  • `backend` (optional): `"default"`, `"mongo"`, or `"custom"`. Defaults to `"default"` (PostgreSQL). See [Configure checkpointer backend](/langsmith/configure-checkpointer).
  • `path` (optional): Path to a custom checkpointer factory (when `backend` is `"custom"`). See [Custom checkpointer](/langsmith/custom-checkpointer).
  • `ttl` (optional): Object with `strategy`, `sweep_interval_minutes`, `default_ttl`, and `sweep_limit` (Agent server v0.8+) controlling checkpoint expiry.
  • `serde` (optional, Agent server v0.5+): Object with `allowed_json_modules` and `pickle_fallback` to tune deserialization behavior.
| | `http` | HTTP server configuration with the following fields:
  • `app`: Path to custom Starlette/FastAPI app (e.g., `"./src/agent/webapp.py:app"`). See [custom routes guide](/langsmith/custom-routes).
  • `cors`: CORS configuration with fields such as `allow_origins`, `allow_methods`, `allow_headers`, `allow_credentials`, `allow_origin_regex`, `expose_headers`, and `max_age`.
  • `configurable_headers`: Define which request headers to expose as configurable values via `includes` / `excludes` patterns.
  • `logging_headers`: Mirror of `configurable_headers` for excluding sensitive headers from logs.
  • `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.
  • `enable_custom_route_auth`: Apply auth checks to routes added through `app`.
  • Route disable flags, which selectively turn off groups of built-in endpoints:
    • `disable_meta`: Disables the `/` (root), `/info`, `/metrics`, `/docs`, and `/openapi.json` system routes. The `/ok` health check remains available.
    • `disable_assistants`: Disables all `/assistants/*` routes.
    • `disable_runs`: Disables all `/runs/*` routes.
    • `disable_threads`: Disables all `/threads/*` routes.
    • `disable_store`: Disables all `/store/*` routes.
    • `disable_ui`: Disables all `/ui/*` routes.
    • `disable_mcp`: Disables the `/mcp` endpoint. See [Disable MCP](/langsmith/server-mcp#disable-mcp).
    • `disable_a2a`: Disables the `/a2a/*` endpoint. See [Disable A2A](/langsmith/server-a2a#disable-a2a).
    • `disable_webhooks`: Disables webhook delivery on run completion (not a route toggle). See [Disable webhooks](/langsmith/use-webhooks#disable-webhooks).
  • `mount_prefix`: Prefix for mounted routes (e.g., "/my-deployment/api").
| | `webhooks` | *(Added in v0.5.36)* Configuration for outbound webhook delivery. Contains:
  • `env_prefix`: Required prefix for environment variables referenced in header templates (defaults to `LG_WEBHOOK_`).
  • `headers`: Static headers to include with webhook requests. Values may contain templates like `${{ env.VAR }}`.
  • `url`: URL validation policy with `allowed_domains`, `allowed_ports`, `require_https`, `disable_loopback`, and `max_url_length`.
| | `api_version` | *(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/agent-server-changelog) for details on each release. | | Key | Description | | - | - | | `graphs` | **Required**. Mapping from graph ID to path where the compiled graph or a function that makes a graph is defined. Example:
  • `./src/graph.ts:variable`, where `variable` is an instance of [`CompiledStateGraph`](https://reference.langchain.com/python/langgraph/graph/state/CompiledStateGraph)
  • `./src/graph.ts:makeGraph`, where `makeGraph` is a function that takes a config dictionary (`LangGraphRunnableConfig`) and returns an instance of [`StateGraph`](https://reference.langchain.com/python/langgraph/graph/state/StateGraph) or [`CompiledStateGraph`](https://reference.langchain.com/python/langgraph/graph/state/CompiledStateGraph). See [how to rebuild a graph at runtime](/langsmith/graph-rebuild) for more details.
| | `env` | Path to `.env` file or a mapping from environment variable to its value. | | `store` | Configuration for adding semantic search and/or time-to-live (TTL) to the BaseStore. Contains the following fields:
  • `index` (optional): Configuration for semantic search indexing with fields `embed`, `dims`, and optional `fields`.
  • `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).
| | `node_version` | Specify `node_version: 20` to use LangGraph.js. | | `dockerfile_lines` | Array of additional lines to add to Dockerfile following the import from parent image. | | `checkpointer` | Configuration for the checkpointer. Supports:
  • `backend` (optional): `"default"`, `"mongo"`, or `"custom"`. Defaults to `"default"` (PostgreSQL). See [Configure checkpointer backend](/langsmith/configure-checkpointer).
  • `path` (optional): Path to a custom checkpointer factory (when `backend` is `"custom"`). See [Custom checkpointer](/langsmith/custom-checkpointer).
  • `ttl` (optional): Object with `strategy`, `sweep_interval_minutes`, `default_ttl`, and `sweep_limit` (Agent server v0.8+) controlling checkpoint expiry.
  • `serde` (optional, Agent server v0.5+): Object with `allowed_json_modules` and `pickle_fallback` to tune deserialization behavior.
| | `http` | HTTP server configuration mirroring the Python options:
  • `cors` with `allow_origins`, `allow_methods`, `allow_headers`, `allow_credentials`, `allow_origin_regex`, `expose_headers`, `max_age`.
  • `configurable_headers` and `logging_headers` pattern lists.
  • `middleware_order` (`auth_first` or `middleware_first`).
  • `enable_custom_route_auth` plus the same boolean route toggles as above.
| | `webhooks` | *(Added in v0.5.36)* Configuration for outbound webhook delivery. Contains:
  • `env_prefix`: Required prefix for environment variables referenced in header templates (defaults to `LG_WEBHOOK_`).
  • `headers`: Static headers to include with webhook requests. Values may contain templates like `${{ env.VAR }}`.
  • `url`: URL validation policy with `allowed_domains`, `allowed_ports`, `require_https`, `disable_loopback`, and `max_url_length`.
| | `api_version` | *(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/agent-server-changelog) for details on each release. | ### Examples #### Basic configuration ```json theme={null} { "$schema": "https://langgra.ph/schema.json", "dependencies": ["."], "graphs": { "chat": "chat.graph:graph" } } ``` #### Using Wolfi base images You can specify the Linux distribution for your base image using the `image_distro` field. Valid options are `debian`, `wolfi`, `bookworm`, or `bullseye`. Wolfi is the recommended option as it provides smaller and more secure images. This is available in `langgraph-cli>=0.2.11`. ```json theme={null} { "$schema": "https://langgra.ph/schema.json", "dependencies": ["."], "graphs": { "chat": "chat.graph:graph" }, "image_distro": "wolfi" } ``` #### Adding semantic search to the store All deployments come with a DB-backed BaseStore. Adding an "index" configuration to your `langgraph.json` will enable [semantic search](/langsmith/semantic-search) within the BaseStore of your deployment. The `index.fields` configuration determines which parts of your documents to embed: * If omitted or set to `["$"]`, the entire document will be embedded * To embed specific fields, use JSON path notation: `["metadata.title", "content.text"]` * Documents missing specified fields will still be stored but won't have embeddings for those fields * You can still override which fields to embed on a specific item at `put` time using the `index` parameter ```json theme={null} { "dependencies": ["."], "graphs": { "memory_agent": "./agent/graph.py:graph" }, "store": { "index": { "embed": "openai:text-embedding-3-small", "dims": 1536, "fields": ["$"] } } } ``` **Common model dimensions** * `openai:text-embedding-3-large`: 3072 * `openai:text-embedding-3-small`: 1536 * `openai:text-embedding-ada-002`: 1536 * `cohere:embed-english-v3.0`: 1024 * `cohere:embed-english-light-v3.0`: 384 * `cohere:embed-multilingual-v3.0`: 1024 * `cohere:embed-multilingual-light-v3.0`: 384 #### Semantic search with a custom embedding function If you want to use semantic search with a custom embedding function, you can pass a path to a custom embedding function: ```json theme={null} { "dependencies": ["."], "graphs": { "memory_agent": "./agent/graph.py:graph" }, "store": { "index": { "embed": "./embeddings.py:embed_texts", "dims": 768, "fields": ["text", "summary"] } } } ``` The `embed` field in store configuration can reference a custom function that takes a list of strings and returns a list of embeddings. Example implementation: ```python theme={null} # embeddings.py def embed_texts(texts: list[str]) -> list[list[float]]: """Custom embedding function for semantic search.""" # Implementation using your preferred embedding model return [[0.1, 0.2, ...] for _ in texts] # dims-dimensional vectors ``` #### Adding custom authentication ```json theme={null} { "$schema": "https://langgra.ph/schema.json", "dependencies": ["."], "graphs": { "chat": "chat.graph:graph" }, "auth": { "path": "./auth.py:auth", "openapi": { "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "security": [{ "apiKeyAuth": [] }] }, "disable_studio_auth": false, "allow_langsmith_api_keys": false } } ``` See the [authentication conceptual guide](/langsmith/auth) for details, and the [setting up custom authentication](/langsmith/set-up-custom-auth) guide for a practical walk through of the process. #### Configuring store item Time-to-Live You can configure default data expiration for items/memories in the BaseStore using the `store.ttl` key. This determines how long items are retained after they are last accessed (with reads potentially refreshing the timer based on `refresh_on_read`). Note that these defaults can be overwritten on a per-call basis by modifying the corresponding arguments in `get`, `search`, etc. The `ttl` configuration is an object containing optional fields: * `refresh_on_read`: If `true` (the default), accessing an item via `get` or `search` resets its expiration timer. Set to `false` to only refresh TTL on writes (`put`). * `default_ttl`: The default lifespan of an item in **minutes**. Applies only to newly created items; existing items are not modified. If not set, items do not expire by default. * `sweep_interval_minutes`: How frequently (in minutes) the system should run a background process to delete expired items. If not set, sweeping does not occur automatically. Here is an example enabling a 7-day TTL (10080 minutes), refreshing on reads, and sweeping every hour: ```json theme={null} { "$schema": "https://langgra.ph/schema.json", "dependencies": ["."], "graphs": { "memory_agent": "./agent/graph.py:graph" }, "store": { "ttl": { "refresh_on_read": true, "sweep_interval_minutes": 60, "default_ttl": 10080 } } } ``` #### 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). Two optional sub-objects are supported: * `ttl`: Includes `strategy`, `sweep_interval_minutes`, `default_ttl`, and `sweep_limit` (Agent server v0.8+), which collectively set how checkpoints expire. * `serde` *(Agent server v0.5+)* : Lets you control deserialization behavior for checkpoint payloads. Here's an example setting a default TTL of 30 days (43200 minutes): ```json theme={null} { "$schema": "https://langgra.ph/schema.json", "dependencies": ["."], "graphs": { "chat": "chat.graph:graph" }, "checkpointer": { "ttl": { "strategy": "delete", "sweep_interval_minutes": 10, "default_ttl": 43200 } } } ``` 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 theme={null} { "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. * `cors`: Customize your server's CORS (Cross-Origin Resource Sharing) configuration. Example `langgraph.json` file for configuring CORS: ```json theme={null} { ... "http": { "cors": { "allow_origins": ["https://example.com", "https://app.example.com"], "allow_methods": ["GET", "POST"], "allow_headers": ["Authorization", "Content-Type"], "allow_credentials": true, "allow_origin_regex": "^https://.*\\.example\\.com$", "expose_headers": ["x-pagination-total", "x-pagination-next", "x-request-id"], "max_age": 600 } }, ... } ``` Customizing your server's CORS configuration will override the functionality of setting the [`CORS_ALLOW_ORIGINS` environment variable](/langsmith/env-var-cloud). #### Configuring webhooks You can configure custom headers and URL restrictions for outbound webhook requests: ```json theme={null} { "$schema": "https://langgra.ph/schema.json", "dependencies": ["."], "graphs": { "chat": "chat.graph:graph" }, "webhooks": { "headers": { "Authorization": "Bearer ${{ env.LG_WEBHOOK_TOKEN }}" }, "url": { "allowed_domains": ["*.mycompany.com"], "require_https": true } } } ``` See [Use webhooks](/langsmith/use-webhooks#add-headers-to-webhook-requests) for details on header configuration, environment variable templating, and URL restrictions. #### Pinning API version *(Added in v0.3.7)* You can pin the API version of the Agent Server by using the `api_version` key. This is useful if you want to ensure that your server uses a specific version of the API. By default, builds in Cloud deployments use the latest stable version of the server. This can be pinned by setting the `api_version` key to a specific version. ```json theme={null} { "$schema": "https://langgra.ph/schema.json", "dependencies": ["."], "graphs": { "chat": "chat.graph:graph" }, "api_version": "0.2" } ``` #### Disabling built-in routes You can selectively disable groups of built-in HTTP routes using boolean flags in the `http` configuration block. This is useful for production deployments where you want to minimize the server's exposed surface area. For example, to disable the system information and documentation routes: ```json theme={null} { "$schema": "https://langgra.ph/schema.json", "dependencies": ["."], "graphs": { "chat": "chat.graph:graph" }, "http": { "disable_meta": true } } ``` Setting `disable_meta` to `true` disables the following routes: * `/` — root health check * `/info` — server version and configuration info * `/metrics` — Prometheus and JSON metrics * `/docs` — API documentation UI * `/openapi.json` — OpenAPI specification The `/ok` health check endpoint remains available even when `disable_meta` is set, so orchestrators like Kubernetes can still perform liveness and readiness probes. Other route disable flags include `disable_assistants`, `disable_runs`, `disable_threads`, `disable_store`, and `disable_ui`. For MCP, A2A, and webhooks, see their respective guides: [Disable MCP](/langsmith/server-mcp#disable-mcp), [Disable A2A](/langsmith/server-a2a#disable-a2a), [Disable webhooks](/langsmith/use-webhooks#disable-webhooks). #### Basic configuration ```json theme={null} { "$schema": "https://langgra.ph/schema.json", "graphs": { "chat": "./src/graph.ts:graph" } } ``` #### Pinning API version *(Added in v0.3.7)* You can pin the API version of the Agent Server by using the `api_version` key. This is useful if you want to ensure that your server uses a specific version of the API. By default, builds in Cloud deployments use the latest stable version of the server. This can be pinned by setting the `api_version` key to a specific version. ```json theme={null} { "$schema": "https://langgra.ph/schema.json", "dependencies": ["."], "graphs": { "chat": "./src/chat/graph.ts:graph" }, "api_version": "0.2" } ``` #### Disabling built-in routes You can selectively disable groups of built-in HTTP routes using boolean flags in the `http` configuration block. This is useful for production deployments where you want to minimize the server's exposed surface area. For example, to disable the system information and documentation routes: ```json theme={null} { "$schema": "https://langgra.ph/schema.json", "graphs": { "chat": "./src/chat/graph.ts:graph" }, "http": { "disable_meta": true } } ``` Setting `disable_meta` to `true` disables the following routes: * `/` — root health check * `/info` — server version and configuration info * `/metrics` — Prometheus and JSON metrics * `/docs` — API documentation UI * `/openapi.json` — OpenAPI specification The `/ok` health check endpoint remains available even when `disable_meta` is set, so orchestrators like Kubernetes can still perform liveness and readiness probes. Other route disable flags include `disable_assistants`, `disable_runs`, `disable_threads`, `disable_store`, and `disable_ui`. For MCP, A2A, and webhooks, see their respective guides: [Disable MCP](/langsmith/server-mcp#disable-mcp), [Disable A2A](/langsmith/server-a2a#disable-a2a), [Disable webhooks](/langsmith/use-webhooks#disable-webhooks). ## Commands **Usage** The base command for the LangGraph CLI is `langgraph`. ``` langgraph [OPTIONS] COMMAND [ARGS] ``` The base command for the LangGraph.js CLI is `langgraphjs`. ``` npx @langchain/langgraph-cli [OPTIONS] COMMAND [ARGS] ``` We recommend using `npx` to always use the latest version of the CLI. ### `dev` Run LangGraph API server in development mode with hot reloading and debugging capabilities. This lightweight server requires no Docker installation and is suitable for development and testing. State is persisted to a local directory. Currently, the CLI only supports Python 3.11 or later If you need more information on when to use `langgraph dev` vs `langgraph up`, refer to the [Local development & testing guide](/langsmith/local-dev-testing) for a detailed comparison. **Installation** This command requires the "inmem" extra to be installed: ```bash theme={null} pip install -U "langgraph-cli[inmem]" ``` **Usage** ``` langgraph dev [OPTIONS] ``` **Options** | Option | Default | Description | | - | - | - | | `-c, --config FILE` | `langgraph.json` | Path to configuration file declaring dependencies, graphs and environment variables | | `--host TEXT` | `127.0.0.1` | Host to bind the server to | | `--port INTEGER` | `2024` | Port to bind the server to | | `--no-reload` | | Disable auto-reload | | `--n-jobs-per-worker INTEGER` | | Number of jobs per worker. Default is 10 | | `--debug-port INTEGER` | | Port for debugger to listen on | | `--wait-for-client` | `False` | Wait for a debugger client to connect to the debug port before starting the server | | `--no-browser` | | Skip automatically opening the browser when the server starts | | `--studio-url TEXT` | | URL of the Studio instance to connect to. Defaults to [https://smith.langchain.com](https://smith.langchain.com) | | `--allow-blocking` | `False` | Do not raise errors for synchronous I/O blocking operations in your code (added in `0.2.6`) | | `--tunnel` | `False` | Expose the local server via a public tunnel (Cloudflare) for remote frontend access. This avoids issues with browsers like Safari or networks blocking localhost connections | | `--help` | | Display command documentation | Run LangGraph API server in development mode with hot reloading capabilities. This lightweight server requires no Docker installation and is suitable for development and testing. State is persisted to a local directory. **Usage** ``` npx @langchain/langgraph-cli dev [OPTIONS] ``` **Options** | Option | Default | Description | | - | - | - | | `-c, --config FILE` | `langgraph.json` | Path to configuration file declaring dependencies, graphs and environment variables | | `--host TEXT` | `127.0.0.1` | Host to bind the server to | | `--port INTEGER` | `2024` | Port to bind the server to | | `--no-reload` | | Disable auto-reload | | `--n-jobs-per-worker INTEGER` | | Number of jobs per worker. Default is 10 | | `--debug-port INTEGER` | | Port for debugger to listen on | | `--wait-for-client` | `False` | Wait for a debugger client to connect to the debug port before starting the server | | `--no-browser` | | Skip automatically opening the browser when the server starts | | `--studio-url TEXT` | | URL of the Studio instance to connect to. Defaults to [https://smith.langchain.com](https://smith.langchain.com) | | `--allow-blocking` | `False` | Do not raise errors for synchronous I/O blocking operations in your code | | `--tunnel` | `False` | Expose the local server via a public tunnel (Cloudflare) for remote frontend access. This avoids issues with browsers or networks blocking localhost connections | | `--help` | | Display command documentation | ### `build` Build LangSmith API server Docker image. **Usage** ``` langgraph build [OPTIONS] ``` **Options** | Option | Default | Description | | - | - | - | | `--platform TEXT` | | Target platform(s) to build the Docker image for. Example: `langgraph build --platform linux/amd64,linux/arm64` | | `-t, --tag TEXT` | | **Required**. Tag for the Docker image. Example: `langgraph build -t my-image` | | `--pull / --no-pull` | `--pull` | Build with latest remote Docker image. Use `--no-pull` for running the LangSmith API server with locally built images. | | `-c, --config FILE` | `langgraph.json` | Path to configuration file declaring dependencies, graphs and environment variables. | | `--build-command TEXT`\* | | Build command to run. Runs from the directory where your `langgraph.json` file lives. Example: `langgraph build --build-command "yarn run turbo build"` | | `--install-command TEXT`\* | | Install command to run. Runs from the directory where you call `langgraph build` from. Example: `langgraph build --install-command "yarn install"` | | `--help` | | Display command documentation. | \*Only supported for JS deployments, will have no impact on Python deployments. Build LangSmith API server Docker image. **Usage** ``` npx @langchain/langgraph-cli build [OPTIONS] ``` **Options** | Option | Default | Description | | - | - | - | | `--platform TEXT` | | Target platform(s) to build the Docker image for. Example: `langgraph build --platform linux/amd64,linux/arm64` | | `-t, --tag TEXT` | | **Required**. Tag for the Docker image. Example: `langgraph build -t my-image` | | `--no-pull` | | Use locally built images. Defaults to `false` to build with latest remote Docker image. | | `-c, --config FILE` | `langgraph.json` | Path to configuration file declaring dependencies, graphs and environment variables. | | `--help` | | Display command documentation. | ### `deploy` This command is in [beta](/langsmith/release-stages) and under active development. Expect frequent updates and improvements. `langgraph deploy` is not yet supported on LangSmith Cloud (SaaS) in AWS. Build and deploy a LangGraph image directly to [LangSmith Deployments](/langsmith/deployment). This command builds a Docker image locally, pushes it to a managed registry, and creates or updates a deployment—all in a single step. If Docker is not installed, it triggers a remote build. **Prerequisites** * A [**LangSmith API key**](/langsmith/create-account-api-key) with access to Deployments. * (Optional) **Docker** must be installed and the Docker daemon must be running for local builds. Not required for remote builds. [Install Docker Desktop](https://docs.docker.com/get-docker/). On LangSmith Cloud, the CLI pushes to a managed registry. Self-hosted LangSmith, and Cloud workspaces that deploy through a [listener](/langsmith/control-plane#listeners) in your own cluster, push to a registry you manage with `--push-to`. See [Deploy from a registry you manage](#deploy-from-a-registry-you-manage). **Usage** ``` langgraph deploy [OPTIONS] [DOCKER_BUILD_ARGS] ``` This command also accepts all [`langgraph build`](#build) flags (`--platform`, `-t`, `--pull`, `--no-pull`, `-c`). For details, refer to `langgraph build --help`. **Options** | Option | Default | Description | | - | - | - | | `--api-key TEXT` | | API key for LangSmith Deployments. Can also be set via `LANGGRAPH_HOST_API_KEY`, `LANGSMITH_API_KEY`, or `LANGCHAIN_API_KEY` environment variable or `.env` file. | | `--name TEXT` | Current directory name | Deployment name. Can also be set via `LANGSMITH_DEPLOYMENT_NAME` environment variable or `.env` file. | | `--deployment-id TEXT` | | ID of an existing deployment to update. If omitted, `--name` is used to find or create the deployment. | | `--agent-id TEXT` | | Agent to deploy to in an agent-based workspace, by identifier. Requires `--agent-environment`, and cannot be combined with `--name` or `--deployment-id`. Can also be set via `LANGSMITH_AGENT_ID`. See [Deploy to an agent environment](/langsmith/deploy-to-agent-environment). Available in `langgraph-cli>=0.4.32`. | | `--agent-environment TEXT` | | Environment the deployment reports into: `development`, `staging`, or `production`. Requires `--agent-id`. Can also be set via `LANGSMITH_AGENT_ENVIRONMENT`. Available in `langgraph-cli>=0.4.32`. | | `--deployment-type TEXT` | `serverless` | Deployment type when creating a new deployment on Cloud: `serverless` or `dedicated` on the new usage-based pricing; `dev` or `prod` for organizations still on previous pricing. | | `--remote / --no-remote` | | Force remote or local build. By default, builds remotely if Docker is not available locally. | | `--push-to TEXT` | | Push the image to this repository in a registry you manage (for example `123456789.dkr.ecr.us-east-1.amazonaws.com/agents/my-agent`), then deploy from it. Required for self-hosted LangSmith and for workspaces that deploy through a listener. Uses your existing Docker credentials. Give the tag in the value or with `-t`. Cannot be combined with `--remote`. | | `--image TEXT` | | Use an existing local image (for example `my-agent:dev`) instead of building. The image must target `linux/amd64`. With `--push-to`, the image is retagged and pushed. | | `-t, --tag TEXT` | `latest` | Tag for the pushed image. | | `--listener-id TEXT` | | Listener that will run the deployment, for workspaces that deploy through a listener in your own cluster. Used only when creating a deployment with `--push-to`. On LangSmith Cloud, defaults to the workspace's only listener. | | `--k8s-namespace TEXT` | | Kubernetes namespace the listener deploys into. Used only when creating a deployment with `--push-to`. Defaults to the listener's only namespace. | | `--no-wait` | `False` | Skip waiting for deployment status after pushing. | | `--verbose` | `False` | Show detailed output including Docker build and push logs. | | `--help` | | Display command documentation. | On the new usage-based pricing, pass `--deployment-type serverless` or `--deployment-type dedicated`. Organizations still on previous pricing until October 1, 2026 pass `--deployment-type dev` or `--deployment-type prod` to create Development or Production deployments. For the transition timeline, see [Manage billing](/langsmith/billing#langsmith-deployment-billing). **Example** ```bash theme={null} # Deploy with API key from .env file langgraph deploy # Deploy with inline API key LANGSMITH_API_KEY=lsv2_... langgraph deploy # Update an existing deployment langgraph deploy --deployment-id abc123 # Deploy with inline deployment name LANGSMITH_DEPLOYMENT_NAME=my-agent langgraph deploy # Deploy to EU region LANGGRAPH_HOST_URL=https://eu.api.host.langchain.com langgraph deploy ``` Deployments created through other methods (e.g., the LangSmith UI or GitHub integration) can also be updated with the `langgraph deploy` command. #### Deploy from a registry you manage Self-hosted LangSmith, and LangSmith Cloud workspaces that deploy through a listener in your own cluster (the [legacy hybrid model](/langsmith/hybrid-legacy)), run images from a registry you manage. Pass `--push-to` with a repository in that registry. The CLI builds the image, pushes it with your existing Docker credentials, and creates or updates the deployment from the pushed image. ```bash theme={null} # Log in to your registry first, for example with AWS ECR aws ecr get-login-password | docker login --username AWS --password-stdin 123456789.dkr.ecr.us-east-1.amazonaws.com # Self-hosted: point the CLI at your LangSmith instance LANGSMITH_ENDPOINT=https://langsmith.example.com/api \ langgraph deploy --push-to 123456789.dkr.ecr.us-east-1.amazonaws.com/agents/my-agent # LangSmith Cloud workspace with a listener: only the image location changes langgraph deploy --push-to 123456789.dkr.ecr.us-east-1.amazonaws.com/agents/my-agent --tag v1.2.0 # Push an image you already built langgraph deploy --image my-agent:dev --push-to 123456789.dkr.ecr.us-east-1.amazonaws.com/agents/my-agent ``` The control plane URL is derived from `LANGSMITH_ENDPOINT`, read from the project `.env` file or the environment: `https:///api-host` for a self-hosted instance, and the matching LangSmith Cloud control plane for cloud endpoints. To override it, set the `LANGGRAPH_HOST_URL` environment variable to the full control plane URL, including `/api-host` on a self-hosted instance (for example `https://langsmith.example.com/api-host`). #### Choose a listener and namespace When a workspace deploys through a listener, the control plane needs to know which listener runs a new deployment and which Kubernetes namespace it deploys into. On LangSmith Cloud, you do not have to pass either when there is only one possible answer. If your workspace has a single listener that serves a single namespace, the CLI uses it: ```bash theme={null} langgraph deploy --push-to 123456789.dkr.ecr.us-east-1.amazonaws.com/agents/my-agent ``` When there is a choice, the CLI lists the listeners with their clusters and namespaces, and you pick one: ```bash theme={null} langgraph deploy --push-to 123456789.dkr.ecr.us-east-1.amazonaws.com/agents/my-agent \ --listener-id 2b1f0e9c-2d4a-4f1e-9a3b-2c7d8e5f4a10 --k8s-namespace agents ``` On a self-hosted instance, the CLI looks up listeners only when you pass `--listener-id` or `--k8s-namespace`. The listener and the namespace are fixed when the deployment is created and cannot be changed afterward, so both options are refused on an existing deployment. Later revisions need only `--push-to`. Deployments created with `--push-to` use the `external_docker` source. A deployment created without `--push-to` cannot be switched to it; use a new `--name` instead. #### `deploy list` List LangSmith Deployments. **Usage** ```bash theme={null} langgraph deploy list [OPTIONS] ``` **Options** | Option | Default | Description | | - | - | - | | `--name-contains TEXT` | | Only show deployments whose names contain this value. | | `--api-key TEXT` | | API key. Can also be set via `LANGGRAPH_HOST_API_KEY`, `LANGSMITH_API_KEY`, or `LANGCHAIN_API_KEY` environment variable or `.env` file. | | `--help` | | Show this message and exit. | #### `deploy revisions` \[Beta] Manage deployment revisions. **Usage** ```bash theme={null} langgraph deploy revisions [OPTIONS] COMMAND [ARGS]... ``` **Options** | Option | Default | Description | | - | - | - | | `--help` | | Show this message and exit. | **Commands** | Command | Description | | - | - | | `list` | \[Beta] List revisions for a LangSmith Deployment. | #### `deploy revisions list` \[Beta] List revisions for a LangSmith Deployment. Use [`deploy list`](#deploy-list) to list deployment IDs. **Usage** ```bash theme={null} langgraph deploy revisions list [OPTIONS] DEPLOYMENT_ID ``` **Options** | Option | Default | Description | | - | - | - | | `--limit INTEGER` | `10` | Maximum number of revisions to return. | | `--api-key TEXT` | | API key. Can also be set via `LANGGRAPH_HOST_API_KEY`, `LANGSMITH_API_KEY`, or `LANGCHAIN_API_KEY` environment variable or `.env` file. | | `--help` | | Show this message and exit. | #### `deploy delete` Delete a LangSmith Deployment. Use [`deploy list`](#deploy-list) to find the deployment ID to delete. **Usage** ```bash theme={null} langgraph deploy delete [OPTIONS] DEPLOYMENT_ID ``` **Options** | Option | Default | Description | | - | - | - | | `--force` | | Delete without prompting for confirmation. | | `--api-key TEXT` | | API key. Can also be set via `LANGGRAPH_HOST_API_KEY`, `LANGSMITH_API_KEY`, or `LANGCHAIN_API_KEY` environment variable or `.env` file. | | `--help` | | Show this message and exit. | #### `deploy logs` Fetch LangSmith Deployment logs. Use `deploy` for agent runtime logs, or `build` for remote build logs. **Usage** ```bash theme={null} langgraph deploy logs [OPTIONS] ``` **Options** | Option | Default | Description | | - | - | - | | `-f, --follow` | `False` | Continuously poll for new logs. | | `--end-time TEXT` | | ISO8601 end time. Example: `2026-03-08T00:00:00Z`. | | `--start-time TEXT` | | ISO8601 start time. Example: `2026-03-08T00:00:00Z`. | | `-q, --query TEXT` | | Search string filter. | | `--limit INTEGER` | `100` | Max log entries to fetch. | | `--level [DEBUG\|INFO\|WARNING\|ERROR\|CRITICAL]` | | Filter by log level. | | `--revision-id TEXT` | | Specific revision ID. For build logs, defaults to the latest revision. | | `--type [deploy\|build]` | `deploy` | Log stream to fetch. `deploy` shows agent server runtime logs. `build` shows remote build logs. | | `--deployment-id TEXT` | | Deployment ID. If omitted, `--name` is used to find the deployment. | | `--name TEXT` | Current directory name | Deployment name. Can also be set via `LANGSMITH_DEPLOYMENT_NAME` environment variable or `.env` file. Used when `--deployment-id` is not provided. | | `--api-key TEXT` | | API key. Can also be set via `LANGGRAPH_HOST_API_KEY`, `LANGSMITH_API_KEY`, or `LANGCHAIN_API_KEY` environment variable or `.env` file. | | `--help` | | Show this message and exit. | ### `up` Start LangGraph API server. For local testing, requires a LangSmith API key with access to LangSmith. Requires a license key for production use. If you need more information on when to use `langgraph dev` vs `langgraph up`, refer to the [Local development & testing guide](/langsmith/local-dev-testing) for a detailed comparison. **Usage** ``` langgraph up [OPTIONS] ``` **Options** | Option | Default | Description | | - | - | - | | `--wait` | | Wait for services to start before returning. Implies --detach | | `--base-image TEXT` | `langchain/langgraph-api` | Base image to use for the LangGraph API server. Pin to specific versions using version tags. | | `--image TEXT` | | Docker image to use for the langgraph-api service. If specified, skips building and uses this image directly. | | `--postgres-uri TEXT` | Local database | Postgres URI to use for the database. | | `--watch` | | Restart on file changes | | `--debugger-base-url TEXT` | `http://127.0.0.1:[PORT]` | URL used by the debugger to access LangGraph API. | | `--debugger-port INTEGER` | | Pull the debugger image locally and serve the UI on specified port | | `--verbose` | | Show more output from the server logs. | | `-c, --config FILE` | `langgraph.json` | Path to configuration file declaring dependencies, graphs and environment variables. | | `-d, --docker-compose FILE` | | Path to docker-compose.yml file with additional services to launch. | | `-p, --port INTEGER` | `8123` | Port to expose. Example: `langgraph up --port 8000` | | `--pull / --no-pull` | `pull` | Pull latest images. Use `--no-pull` for running the server with locally-built images. Example: `langgraph up --no-pull` | | `--recreate / --no-recreate` | `no-recreate` | Recreate containers even if their configuration and image haven't changed | | `--help` | | Display command documentation. | Start LangGraph API server. For local testing, requires a LangSmith API key with access to LangSmith. Requires a license key for production use. **Usage** ``` npx @langchain/langgraph-cli up [OPTIONS] ``` **Options** | Option | Default | Description | | - | - | - | | `--wait` | | Wait for services to start before returning. Implies --detach | | `--base-image TEXT` | `langchain/langgraph-api` | Base image to use for the LangGraph API server. Pin to specific versions using version tags. | | `--image TEXT` | | Docker image to use for the langgraph-api service. If specified, skips building and uses this image directly. | | `--postgres-uri TEXT` | Local database | Postgres URI to use for the database. | | `--watch` | | Restart on file changes | | `-c, --config FILE` | `langgraph.json` | Path to configuration file declaring dependencies, graphs and environment variables. | | `-d, --docker-compose FILE` | | Path to docker-compose.yml file with additional services to launch. | | `-p, --port INTEGER` | `8123` | Port to expose. Example: `langgraph up --port 8000` | | `--no-pull` | | Use locally built images. Defaults to `false` to build with latest remote Docker image. | | `--recreate` | | Recreate containers even if their configuration and image haven't changed | | `--help` | | Display command documentation. | ### `dockerfile` Generate a Dockerfile for building a LangSmith API server Docker image. **Usage** ``` langgraph dockerfile [OPTIONS] SAVE_PATH ``` **Options** | Option | Default | Description | | - | - | - | | `-c, --config FILE` | `langgraph.json` | Path to the [configuration file](#configuration-file) declaring dependencies, graphs and environment variables. | | `--help` | | Show this message and exit. | Example: ```bash theme={null} langgraph dockerfile -c langgraph.json Dockerfile ``` This generates a Dockerfile that looks similar to: ```dockerfile theme={null} FROM langchain/langgraph-api:3.11 ADD ./pipconf.txt /pipconfig.txt RUN PIP_CONFIG_FILE=/pipconfig.txt PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt langchain_anthropic langchain_openai wikipedia scikit-learn ADD ./graphs /deps/__outer_graphs/src RUN set -ex && \ for line in '[project]' \ 'name = "graphs"' \ 'version = "0.1"' \ '[tool.setuptools.package-data]' \ '"*" = ["**/*"]'; do \ echo "$line" >> /deps/__outer_graphs/pyproject.toml; \ done RUN PIP_CONFIG_FILE=/pipconfig.txt PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt -e /deps/* ENV LANGSERVE_GRAPHS='{"agent": "/deps/__outer_graphs/src/agent.py:graph", "storm": "/deps/__outer_graphs/src/storm.py:graph"}' ``` The `langgraph dockerfile` command translates all the configuration in your `langgraph.json` file into Dockerfile commands. When using this command, you will have to re-run it whenever you update your `langgraph.json` file. Otherwise, your changes will not be reflected when you build or run the dockerfile. Generate a Dockerfile for building a LangSmith API server Docker image. **Usage** ``` npx @langchain/langgraph-cli dockerfile [OPTIONS] SAVE_PATH ``` **Options** | Option | Default | Description | | - | - | - | | `-c, --config FILE` | `langgraph.json` | Path to the [configuration file](#configuration-file) declaring dependencies, graphs and environment variables. | | `--help` | | Show this message and exit. | Example: ```bash theme={null} npx @langchain/langgraph-cli dockerfile -c langgraph.json Dockerfile ``` This generates a Dockerfile that looks similar to: ```dockerfile theme={null} FROM langchain/langgraphjs-api:20 ADD . /deps/agent RUN cd /deps/agent && yarn install ENV LANGSERVE_GRAPHS='{"agent":"./src/react_agent/graph.ts:graph"}' WORKDIR /deps/agent RUN (test ! -f /api/langgraph_api/js/build.mts && echo "Prebuild script not found, skipping") || tsx /api/langgraph_api/js/build.mts ``` The `npx @langchain/langgraph-cli dockerfile` command translates all the configuration in your `langgraph.json` file into Dockerfile commands. When using this command, you will have to re-run it whenever you update your `langgraph.json` file. Otherwise, your changes will not be reflected when you build or run the dockerfile. ***
[Connect these docs](/use-these-docs) to your agent of choice via MCP for real-time answers. [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/langsmith/cli.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).