langgraph-cli

A LangGraph app is an agent wired together as a flowchart of steps; this is the command-line tool that starts one from a template, runs it on your own machine, and ships it to LangChain's hosted platform.

WHEN TO USE

SCOPE

USE FOR

Scaffold a new LangGraph project from a template with langgraph new.
Run a local development server with hot reload and no Docker required.
Build a Docker image and validate it in a production-like stack before shipping.
Deploy a LangGraph app to LangGraph Platform and tail its runtime logs.
Configure langgraph.json to point at your compiled graph and dependencies.

NOT FOR

Cannot update a deployment created through the LangSmith UI or GitHub integration — use the UI for those.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (7)

The langgraph CLI manages the full lifecycle of LangGraph applications — from scaffolding a new project to deploying it to LangGraph Platform (LangSmith Deployments).

Key commands:

langgraph new — Scaffold a project from a template
langgraph dev — Run locally with hot reload (no Docker)
langgraph build — Build a Docker image
langgraph up — Launch locally via Docker Compose
langgraph deploy — Ship to LangGraph Platform
langgraph dockerfile — Generate a Dockerfile

All commands (except new) read from a langgraph.json config file in the project root.

When to use

Use this skill when the user wants to:

Scaffold a new LangGraph project
Run a local development or production-like server
Build or deploy a LangGraph application
Understand or edit langgraph.json configuration
Manage LangSmith Deployments (list, delete, view logs)

Installation

# Python
pip install 'langgraph-cli[inmem]'   # includes langgraph dev support
pip install langgraph-cli             # without dev server (build/up/deploy only)

# if using UV as package manager
uv add "langgraph-cli[inmem]"       # includes langgraph dev support
uv add langgraph-cli                # without dev server (build/up/deploy only)

# JavaScript
npx @langchain/langgraph-cli         # use on demand
npm install -g @langchain/langgraph-cli  # install globally (available as langgraphjs)

Commands

`langgraph new [PATH]`

Scaffold a new project from a template.

langgraph new                          # interactive template selection
langgraph new ./my-agent               # create in specific directory
langgraph new --template agent-python  # skip prompt, use template directly

Available templates: deep-agent-python, deep-agent-js, agent-python, new-langgraph-project-python, new-langgraph-project-js

`langgraph dev`

Run a local development server with hot reloading. No Docker required.

langgraph dev                              # default: localhost:2024
langgraph dev --port 8000                  # custom port
langgraph dev --config ./langgraph.json    # explicit config path
langgraph dev --no-reload                  # disable hot reload
langgraph dev --no-browser                 # don't auto-open LangGraph Studio
langgraph dev --host 0.0.0.0              # bind to all interfaces (trusted networks only)
langgraph dev --tunnel                     # expose via Cloudflare tunnel for remote access
langgraph dev --debug-port 5678            # enable remote debugger (requires debugpy)
langgraph dev --n-jobs-per-worker 20       # max concurrent jobs per worker (default: 10)

`langgraph build`

Build a Docker image for the LangGraph API server.

langgraph build -t my-image                # required: tag the image
langgraph build -t my-image --no-pull      # use locally-built base images
langgraph build -t my-image -c langgraph.json  # explicit config
langgraph build -t my-image --base-image langchain/langgraph-server:0.2.18  # pin base version

`langgraph up`

Launch the LangGraph API server via Docker Compose (includes Postgres).

langgraph up                               # default port 8123
langgraph up --port 8000                   # custom port
langgraph up --watch                       # restart on file changes
langgraph up --recreate                    # force fresh build (useful for pre-deploy validation)
langgraph up --postgres-uri postgresql://...  # external Postgres
langgraph up --no-pull                     # use local images (after langgraph build)
langgraph up --image my-image              # skip build, use pre-built image
langgraph up -d docker-compose.yml         # add extra Docker services
langgraph up --debugger-port 8124          # serve debugger UI
langgraph up --wait                        # block until services are healthy

`langgraph deploy`

Build and deploy to LangGraph Platform (LangSmith Deployments). Requires Docker. On Apple Silicon (M1/M2/M3), Docker Buildx is also required for cross-compiling to linux/amd64.

langgraph deploy                           # deploy, name defaults to directory name
langgraph deploy --name my-agent           # explicit deployment name
langgraph deploy --deployment-type prod    # production deployment (default: dev)
langgraph deploy --tag v1.2.0              # custom image tag (default: latest)
langgraph deploy --deployment-id <id>      # update an existing deployment by ID
langgraph deploy --config ./langgraph.json # explicit config path
langgraph deploy --no-wait                 # don't wait for deployment status
langgraph deploy --verbose                 # show detailed server logs

Prereq: LANGSMITH_API_KEY in environment or .env.

langgraph deploy also accepts build flags: --base-image, --pull/--no-pull.

`langgraph deploy list`

langgraph deploy list                      # list all deployments
langgraph deploy list --name-contains bot  # filter by name

`langgraph deploy delete`

langgraph deploy delete <deployment-id>          # interactive confirmation
langgraph deploy delete <deployment-id> --force  # skip confirmation

`langgraph deploy logs`

langgraph deploy logs                                  # runtime logs, last 100
langgraph deploy logs --name my-agent                  # by deployment name
langgraph deploy logs --deployment-id <id>             # by deployment ID
langgraph deploy logs --type build                     # build logs instead of runtime
langgraph deploy logs -f                               # follow/stream logs
langgraph deploy logs --level error                    # filter by level (debug|info|warning|error|critical)
langgraph deploy logs -q "timeout"                     # search filter
langgraph deploy logs --limit 500                      # more entries
langgraph deploy logs --start-time 2026-03-08T00:00:00Z  # time range

`langgraph dockerfile <SAVE_PATH>`

Generate a Dockerfile (and optionally Docker Compose files) without building.

langgraph dockerfile ./Dockerfile                      # generate Dockerfile
langgraph dockerfile ./Dockerfile --add-docker-compose # also generate compose + .env + .dockerignore

`langgraph.json` reference

The configuration file used by all CLI commands (dev, build, up, deploy). Defaults to langgraph.json in the current directory.

Minimal config (Python)

{
    "dependencies": ["."],
    "graphs": {
        "agent": "./my_agent/agent.py:graph"
    },
    "env": "./.env"
}

Minimal config (JavaScript)

{
    "dependencies": ["."],
    "graphs": {
        "agent": "./src/agent.js:graph"
    },
    "env": "./.env"
}

Full config with all keys

{
    "dependencies": [".", "langchain_openai", "./local_package"],
    "graphs": {
        "agent": "./my_agent/agent.py:graph",
        "retriever": "./my_agent/rag.py:rag_graph"
    },
    "env": "./.env",
    "python_version": "3.12",
    "pip_config_file": "./pip.conf",
    "dockerfile_lines": [
        "RUN apt-get update && apt-get install -y ffmpeg"
    ]
}

Key reference

Key	Required	Description
`dependencies`	Yes	Array of dependencies. `"."` looks for local packages via `pyproject.toml`, `setup.py`, `requirements.txt`, or `package.json`. Can also be paths to subdirectories (`"./my_pkg"`) or package names (`"langchain_openai"`).
`graphs`	Yes	Mapping of graph ID to path. Format: `./path/to/file.py:variable` (Python) or `./path/to/file.js:function` (JS). The variable must be a `CompiledGraph` or a function returning one. Multiple graphs supported.
`env`	No	Path to a `.env` file (string) OR an inline mapping of env var names to values (object). Used by `langgraph dev` and `langgraph up` locally. `langgraph deploy` reads from this file and adds the variables as deployment secrets.
`python_version`	No	`"3.11"`, `"3.12"`, or `"3.13"`. Defaults to `"3.11"`.
`node_version`	No	Node.js version for JS projects.
`pip_config_file`	No	Path to a pip config file for custom package indexes.
`dockerfile_lines`	No	Array of additional Dockerfile lines appended after the base image import. Use for system packages, binaries, or custom setup.

Typical workflow

Scaffold — langgraph new to create a project from a template.
Configure — Edit langgraph.json: set dependencies, point graphs at your compiled graph(s), add .env.
Develop — langgraph dev for rapid local iteration with hot reload (no Docker, port 2024).
Validate — langgraph up --recreate to test in a production-like Docker stack (port 8123, includes Postgres).
Deploy — langgraph deploy to ship to LangGraph Platform (LangSmith Deployments).
Monitor — langgraph deploy logs -f to tail runtime logs; --type build for build logs.

`langgraph dev` vs `langgraph up`

Feature	`langgraph dev`	`langgraph up`
Docker required	No	Yes
Install	`pip install 'langgraph-cli[inmem]'`	`pip install langgraph-cli`
Primary use	Rapid development & testing	Production-like validation
State persistence	In-memory / pickled to local dir	PostgreSQL
Hot reloading	Yes (default)	Optional (`--watch`)
Default port	2024	8123
Resource usage	Lightweight	Heavier (Docker containers for server, Postgres, Redis)
IDE debugging	Built-in DAP support (`--debug-port`)	Container debugging

Gotchas

langgraph deploy requires Docker — On Apple Silicon (M1/M2/M3), Docker Buildx is also required for cross-compiling to linux/amd64.
langgraph deploy can only update its own deployments — Deployments created through the LangSmith UI or GitHub integration cannot be updated with langgraph deploy. Use the UI for those.
dependencies must include all packages — The dependencies array in langgraph.json must point to where your package config lives (e.g., "." for root). The actual packages are resolved from pyproject.toml, requirements.txt, or package.json at that location.
langgraph dev runs without Docker — It runs directly in your environment. If your code depends on system packages (e.g., ffmpeg), they must be installed locally. Use langgraph up to validate Docker builds.
JavaScript CLI — Use npx @langchain/langgraph-cli <command> (or langgraphjs if installed globally via npm install -g @langchain/langgraph-cli).
API key — LANGSMITH_API_KEY is required for langgraph deploy. For langgraph dev, it is optional — the server runs without it, but you won't get traces in LangSmith. Can also be set via LANGGRAPH_HOST_API_KEY or LANGCHAIN_API_KEY.

Account or credentials required

3 FOR YOU

Items without a tag are required.

01
Install the langgraph CLI
Install langgraph-cli (pip install 'langgraph-cli[inmem]' for local dev, or npx/npm install -g @langchain/langgraph-cli for JavaScript).
02
Optional Get a LangSmith API key to deploy
Set LANGSMITH_API_KEY (or LANGGRAPH_HOST_API_KEY / LANGCHAIN_API_KEY) in your environment or .env file before running langgraph deploy.
Set one: LANGSMITH_API_KEY, LANGGRAPH_HOST_API_KEY or LANGCHAIN_API_KEY
03
Optional Install Docker for build, up, or deploy
Install Docker before using langgraph build, up, or deploy; on Apple Silicon, Docker Buildx is also required for cross-compiling to linux/amd64.

This skill ships inside the LangChain Agent-Building Skills plugin.

Install just this skill

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add langchain-ai/langchain-skills --skill "langgraph-cli" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

Install the whole plugin

This route installs the LangChain Agent-Building Skills plugin package selected for your AI tool.

Claude Code

Add LangChain's marketplace, then install the plugin

Type both lines inside a Claude Code session, not at your shell prompt. The first adds LangChain's marketplace, which is this repository; the second opens the details of the langchain-skills plugin, and Claude Code installs it once you pick one of the install options shown. Afterwards, LangChain's README asks you to set OPENAI_API_KEY or ANTHROPIC_API_KEY, for whichever of those model providers you build with.

/plugin marketplace add langchain-ai/langchain-skills

/plugin install langchain-skills@langchain-skills

Open plugin page ↗

View on GitHub

When to use

Installation

Commands

langgraph new [PATH]

langgraph dev

langgraph build

langgraph up

langgraph deploy

langgraph deploy list

langgraph deploy delete

langgraph deploy logs

langgraph dockerfile <SAVE_PATH>

langgraph.json reference