langgraph-cli

<overview> L'interface CLI langgraph gère le cycle de vie complet des applications LangGraph — du scaffolding d'un nouveau projet jusqu'au déploiement sur LangGraph Platform (LangSmith Deployments).

Commandes clés :

• langgraph new — Scaffolder un projet à partir d'un template
• langgraph dev — Exécuter localement avec hot reload (sans Docker)
• langgraph build — Construire une image Docker
• langgraph up — Lancer localement via Docker Compose
• langgraph deploy — Déployer sur LangGraph Platform
• langgraph dockerfile — Générer un Dockerfile

Toutes les commandes (sauf new) lisent depuis un fichier de configuration langgraph.json à la racine du projet. </overview>

Quand l'utiliser

Utilisez cette skill quand l'utilisateur souhaite :

• Scaffolder un nouveau projet LangGraph
• Exécuter un serveur de développement local ou en pré-production
• Construire ou déployer une application LangGraph
• Comprendre ou éditer la configuration langgraph.json
• Gérer les LangSmith Deployments (lister, supprimer, afficher les 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)

Commandes

langgraph new [PATH]

Scaffolder un nouveau projet à partir d'un template.

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

Templates disponibles : deep-agent-python, deep-agent-js, agent-python, new-langgraph-project-python, new-langgraph-project-js

langgraph dev

Exécuter un serveur de développement local avec hot reloading. Aucun Docker requis.

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

Construire une image Docker pour le serveur API LangGraph.

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

Lancer le serveur API LangGraph via Docker Compose (incluant 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

Construire et déployer sur LangGraph Platform (LangSmith Deployments). Nécessite Docker. Sur Apple Silicon (M1/M2/M3), Docker Buildx est également requis pour la cross-compilation vers 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

Prérequis : LANGSMITH_API_KEY dans l'environnement ou .env.

langgraph deploy accepte aussi les flags de build : --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>

Générer un Dockerfile (et optionnellement des fichiers Docker Compose) sans construire.

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

Référence langgraph.json

Le fichier de configuration utilisé par toutes les commandes CLI (dev, build, up, deploy). Par défaut langgraph.json dans le répertoire courant.

Configuration minimale (Python)

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

Configuration minimale (JavaScript)

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

Configuration complète avec toutes les clés

{
    "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"
    ]
}

Référence des clés

Flux de travail typique

1. Scaffolder — langgraph new pour créer un projet à partir d'un template.
2. Configurer — Éditer langgraph.json : définir les dépendances, pointer graphs sur votre(vos) graphe(s) compilé(s), ajouter .env.
3. Développer — langgraph dev pour l'itération locale rapide avec hot reload (pas de Docker, port 2024).
4. Valider — langgraph up --recreate pour tester dans une stack Docker de pré-production (port 8123, inclut Postgres).
5. Déployer — langgraph deploy pour envoyer sur LangGraph Platform (LangSmith Deployments).
6. Monitorer — langgraph deploy logs -f pour suivre les logs runtime ; --type build pour les logs de build.

langgraph dev vs langgraph up

Pièges

• langgraph deploy nécessite Docker — Sur Apple Silicon (M1/M2/M3), Docker Buildx est aussi requis pour la cross-compilation vers linux/amd64.
• langgraph deploy ne peut mettre à jour que ses propres déploiements — Les déploiements créés via l'UI LangSmith ou l'intégration GitHub ne peuvent pas être mis à jour avec langgraph deploy. Utilisez l'UI pour ceux-là.
• dependencies doit inclure tous les packages — Le tableau dependencies dans langgraph.json doit pointer où votre configuration de package se trouve (par ex., "." pour la racine). Les packages réels sont résolus depuis pyproject.toml, requirements.txt, ou package.json à cet emplacement.
• langgraph dev s'exécute sans Docker — Il s'exécute directement dans votre environnement. Si votre code dépend de packages système (par ex., ffmpeg), ils doivent être installés localement. Utilisez langgraph up pour valider les builds Docker.
• CLI JavaScript — Utilisez npx @langchain/langgraph-cli <command> (ou langgraphjs si installé globalement via npm install -g @langchain/langgraph-cli).
• Clé API — LANGSMITH_API_KEY est requis pour langgraph deploy. Pour langgraph dev, c'est optionnel — le serveur s'exécute sans, mais vous n'obtiendrez pas de traces dans LangSmith. Peut aussi être défini via LANGGRAPH_HOST_API_KEY ou LANGCHAIN_API_KEY.