Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.langchain.com/llms.txt

Use this file to discover all available pages before exploring further.

The Deep Agents CLI is an open source coding agent built on the Deep Agents SDK. The CLI works with any LLM that supports tool calling and allows you to switch LLMs between inputs. It retains persistent memory of learnings from conversations, maintains context across sessions, uses customizable skills, and executes code with approval controls.

​
Quickstart

Install and launch

OpenAI, Anthropic, and Google are installed by default. Other providers (Ollama, Groq, xAI, etc.) are available as optional extras—see Providers for details.
curl -LsSf https://langch.in/gh-da-cli | bash

deepagents
Deep Agents CLI

Add provider credentials

The CLI works with any LLM that supports tool calling. Use the /auth command to set an API key for your chosen providers — see Provider credentials for the full flow and storage details.For additional providers and headless runs, see Providers.

Give the agent a task

Create a Python script that prints "Hello, World!"
The agent interprets the query and proposes changes with diffs for your approval before modifying files. If needed, it can run shell commands to test the code, check documentation, or search the web for up-to-date information.

Enable tracing (optional)

To log agent operations, tool calls, and decisions in LangSmith, add the following to ~/.deepagents/.env or export the variables in your shell:
~/.deepagents/.env
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=lsv2_...
LANGSMITH_PROJECT=optional-project-name  # Specify a project name or default to "deepagents-cli"
For more details and usage, see Trace with LangSmith.
The Deep Agents CLI is not officially supported on Windows. Windows users can try running it under Windows Subsystem for Linux (WSL).

​
Capabilities

The Deep Agents CLI has the following built-in capabilities:
  • File operations - read, write, and edit files with tools that enable agents to manage and modify code and documentation.
  • Shell execution - execute commands to run tests, build projects, manage dependencies, and interact with version control.
  • Remote sandboxes - run agent tools in LangSmith, Daytona, Modal, Runloop, or AgentCore instead of your local machine. The linked page covers provider installation, credentials, sandbox flags (--sandbox, --sandbox-id, --sandbox-setup), and setup scripts.
  • Web search - search the web for up-to-date information and documentation (requires Tavily API key).
  • HTTP requests - make HTTP requests to APIs and external services for data fetching and integration tasks.
  • Task planning and tracking - break down complex tasks into discrete steps and track progress.
  • Subagents - delegate work with the task tool. In the CLI, define custom subagents as AGENTS.md files; the linked page covers paths, frontmatter, and examples.
  • Memory storage and retrieval - store and retrieve information across sessions, enabling agents to remember project conventions and learned patterns.
  • Context compaction & offloading - summarize older conversation messages and offload originals to storage, freeing context window space during long sessions.
  • Human-in-the-loop - require human approval for sensitive tool operations.
  • Skills - extend agent capabilities with custom expertise and instructions.
  • MCP tools - load external tools from Model Context Protocol servers.
  • Tracing - trace agent operations in LangSmith for observability and debugging.

​
Built-in tools

The agent comes with the following built-in tools which are available without configuration:
ToolDescriptionHuman-in-the-Loop
lsList files and directories-
read_fileRead contents of a file; multimodal content for select models-
write_fileCreate or overwrite a fileRequired1
edit_fileMake targeted edits to existing filesRequired1
globFind files matching a pattern-
grepSearch for text patterns across files-
executeExecute shell commands locally or in a remote sandboxRequired1
web_searchSearch the web using TavilyRequired1
fetch_urlFetch and convert web pages to markdownRequired1
taskDelegate work to subagents for parallel executionRequired1
ask_userAsk the user free-form or multiple-choice questions-
compact_conversationSummarize older messages, offload originals to backend storage, and replace them in context with the summaryMixed2
write_todosCreate and manage task lists for complex work-
1: Potentially destructive operations require user approval before execution. To bypass human approval, you can toggle auto-approve (shift+tab) or start with the option:
deepagents -y
# or
deepagents --auto-approve
When running the CLI non-interactively (via -n or piped stdin), shell execution is disabled by default even with -y/--auto-approve. Use -S/--shell-allow-list to allowlist specific commands (e.g., -S "pytest,git,make"), recommended for safe defaults, or all to permit any command. The DEEPAGENTS_CLI_SHELL_ALLOW_LIST environment variable is also supported. See Non-interactive mode and piping for more details.
2: The CLI automatically offloads the conversation in the background when token usage exceeds a model-aware threshold. Offloading summarizes older messages via the LLM, and ejects originals to storage (/conversation_history/{thread_id}.md), replacing them in context with the summary. The agent can still retrieve the full history from the offloaded file if needed. The compact_conversation tool lets the agent (or you) trigger offloading on demand. When called as a tool, it requires user approval by default.
Watch the demo video to see how the Deep Agents CLI works.

​
Command reference

# Use a specific agent configuration
deepagents --agent mybot

# Use a specific model (provider:model format or auto-detect)
deepagents --model anthropic:claude-opus-4-7
deepagents --model gpt-5.5

# Auto-approve tool usage (skip human-in-the-loop prompts)
deepagents -y

# list directory contents, then summarize directory as first prompt — the command runs first, then the prompt is submitted
# the prompt does NOT have access to the command output
deepagents --startup-cmd "ls -la" -m "Summarize what's in this directory"

# Non-interactive with startup command: show git status before the task runs
# the task does NOT have access to the command output
deepagents --startup-cmd "git diff --stat" -n "Review these changes"
OptionDescription
-a, --agent NAMEUse named agent with separate memory. Overrides [agents].recent in config.toml. Default: agent (or the most recently used agent if [agents].recent is set)
-M, --model MODELUse a specific model (provider:model)
--model-params JSONExtra kwargs to pass to the model as a JSON string (e.g., '{"temperature": 0.7}')
--default-model [MODEL]Set the default model
--clear-default-modelClear the default model
-r, --resume [ID]Resume a session: -r for most recent, -r <ID> for a specific thread
-m, --message TEXTInitial prompt to auto-submit when the session starts (interactive mode)
--skill NAMEInvoke a skill at startup
--startup-cmd CMDShell command to run at startup, before the first prompt. Output is rendered in the transcript for your reference but is not added to the agent’s message history. To hand command output to the agent, pipe it in via stdin instead (e.g., git diff | deepagents -n "Review these changes"). Non-zero exits and timeouts warn but do not abort; non-interactive mode applies a 60s timeout.
-n, --non-interactive TEXTRun a single task non-interactively and exit. Shell is disabled unless --shell-allow-list is set
--max-turns NCap agentic turns in non-interactive mode. Exits with code 124 when exceeded. Requires -n or piped stdin. See Cap turn count with --max-turns
-q, --quietClean output for piping—only the agent’s response goes to stdout. Requires -n or piped stdin
--no-streamBuffer the full response and write to stdout at once instead of streaming. Requires -n or piped stdin
--stdinRead input from stdin explicitly instead of auto-detection. Errors clearly when stdin is unavailable or is a TTY
-y, --auto-approveAuto-approve all tool calls without prompting (disables human-in-the-loop). Toggle with Shift+Tab during an interactive session
-S, --shell-allow-list LISTComma-separated shell commands to auto-approve, 'recommended' for safe defaults, or 'all' to allow any command. Applies to both -n and interactive modes
--jsonEmit machine-readable JSON from management subcommands (agents, threads, skills, update). Output envelope: {"schema_version": 1, "command": "...", "data": ...}
--sandbox TYPERemote sandbox for code execution: none (default), langsmith, agentcore, modal, daytona, runloop. LangSmith is included; AgentCore/Modal/Daytona/Runloop require extras
--sandbox-id IDReuse an existing sandbox (skips creation and cleanup)
--sandbox-setup PATHPath to setup script to run in sandbox after creation
--mcp-config PATHAdd an explicit MCP config as the highest-precedence source (merged with auto-discovered configs)
--no-mcpDisable all MCP tool loading
--trust-project-mcpTrust project-level MCP configs with stdio servers (skip approval prompt)
--profile-override JSONOverride model profile fields as a JSON string (e.g., '{"max_input_tokens": 4096}'). Merged on top of config file profile overrides
--acpRun as an ACP server over stdio instead of launching the interactive UI
-v, --versionDisplay version
-h, --helpShow help
CommandDescription
deepagents helpShow help
deepagents agents listList all agents (alias: ls)
deepagents agents reset --agent NAMEClear agent memory and reset to default. Supports --dry-run
deepagents agents reset --agent NAME --target SOURCECopy memory from another agent
deepagents updateCheck for and install CLI updates
deepagents skills list [--project]List all skills (alias: ls)
deepagents skills create NAME [--project]Create a new skill with template SKILL.md. Idempotent — re-creating an existing skill prints an informational message instead of an error
deepagents skills info NAME [--project]Show detailed information about a skill
deepagents skills delete NAME [--project] [-f]Delete a skill and its contents. Supports --dry-run
deepagents threads list [--agent NAME] [--limit N]List sessions (alias: ls). Default limit: 20. -n is a short flag for --limit. Additional flags: --sort {created,updated}, --branch TEXT (filter by git branch), -v/--verbose (show all columns including branch, created time, and initial prompt), -r/--relative (relative timestamps)
deepagents threads delete IDDelete a session. Supports --dry-run
deepagents mcp login NAME [--config PATH]Run the OAuth login flow for an MCP server marked auth: "oauth". See MCP tools
deepagents deployDeploy your agent to LangSmith. See Deploy with the CLI
All management subcommands support --json for machine-readable output. See command-line options for details.Destructive commands (agents reset, skills delete, threads delete) support --dry-run to preview what would happen without making changes. In JSON mode, --dry-run returns the same envelope with a dry_run: true field.

​
Configuration

For the full reference — including config.toml schema, provider parameters, profile overrides, and hook configuration — see Configuration. The CLI stores all configuration under ~/.deepagents/. Within that directory, each agent gets its own subdirectory (default: agent):
PathPurpose
~/.deepagents/config.tomlModel and agent defaults, provider settings, constructor params, profile overrides, themes, update settings, MCP trust store
~/.deepagents/.envGlobal API keys and secrets. See configuration
~/.deepagents/hooks.jsonLifecycle event hooks (session start/end, task complete, etc.)
~/.deepagents/<agent_name>/Per-agent memory, skills, and conversation threads
.deepagents/ (project root)Project-specific memory and skills, loaded when running inside a git repo
# List all configured agents
deepagents agents list

​
Interactive mode

Type naturally as you would in a chat interface. The agent will use its built-in tools, skills, and memory to help you with tasks.
Use these commands within the CLI session:
  • /model - Switch models or open the interactive model selector.
  • /agents - Hot-swap between pre-configured agents without relaunching. See Command reference for details
  • /auth - Manage stored API keys for model providers. See Provider credentials for details
  • /remember [context] - Review conversation and update memory and skills. Optionally pass additional context
  • /skill:<name> [args] - Directly invoke a skill by name. The skill’s SKILL.md instructions are injected into the prompt along with any arguments you provide
  • /skill-creator [args] - Guide for creating effective agent skills
  • /offload (alias /compact) - Free up context window space by offloading messages to storage with a summary placeholder. The agent can retrieve the full history from the offloaded file if needed
  • /tokens - Display current context window token usage breakdown
  • /clear - Clear conversation history and start a new thread
  • /threads - Browse and resume previous conversation threads
  • /mcp - Show active MCP servers and tools
  • /reload - Re-read .env files, refresh configuration, and re-discover skills without restarting. Conversation state is preserved. See DEEPAGENTS_CLI_ prefix for override behavior
  • /theme - Open the interactive theme selector to switch color themes. Built-in themes are available plus any user-defined themes
  • /update - Check for and install CLI updates inline. Detects your install method (uv, Homebrew, pip) and runs the appropriate upgrade command
  • /auto-update - Toggle automatic updates on or off
  • /trace - Open the current thread in LangSmith (requires LANGSMITH_API_KEY)
  • /editor - Open the current prompt in your external editor ($VISUAL / $EDITOR). See External editor
  • /changelog - Open the CLI changelog in your browser
  • /docs - Open the documentation in your browser
  • /feedback - Open the GitHub issues page to file a bug report or feature request
  • /version - Show installed deepagents-cli and SDK versions
  • /help - Show help and available commands
  • /quit - Exit the CLI
Type ! to enter shell mode, then type your command.
git status
npm test
ls -la
General
ShortcutAction
EnterSubmit prompt
Shift+Enter, Ctrl+J, Alt+Enter, or Ctrl+EnterInsert newline
Ctrl+ASelect all text in input
@filenameAuto-complete files and inject content
Shift+Tab or Ctrl+TToggle auto-approve
Ctrl+UDelete to start of line
Ctrl+XOpen prompt in external editor
Ctrl+OExpand/collapse the most recent tool output
EscapeInterrupt current operation
Ctrl+CInterrupt or quit
Ctrl+DExit

​
Non-interactive mode and piping

Use -n to run a single task without launching the interactive UI: 
deepagents -n "Write a Python script that prints hello world"
You can also pipe input via stdin. When input is piped, the CLI automatically runs non-interactively: 
echo "Explain this code" | deepagents
cat error.log | deepagents -n "What's causing this error?"
git diff | deepagents -n "Review these changes"
git diff | deepagents --skill code-review -n 'summarize changes'
When you combine piped input with -n or -m, the piped content appears first, followed by the text you pass to the flag.
The maximum piped input size is 10 MiB.
Shell execution is disabled by default in non-interactive mode. Use -S/--shell-allow-list to enable specific commands (e.g., -S "pytest,git,make"), recommended for safe defaults, or all to permit any command.
Long-running or misbehaving agents in CI/CD pipelines can loop indefinitely. --max-turns N gives operators a hard upper bound without having to touch SDK internals:
deepagents -n "fix the failing tests" --max-turns 10
N must be a positive integer, and overrides the internal safety default that otherwise caps runaway loops. Exits with code 124 (matching GNU timeout) when the budget is exceeded, so CI can distinguish a budget hit from a generic failure. Requires -n or piped stdin; otherwise exits with code 2.
Use -q for clean output suitable for piping into other commands, and --no-stream to buffer the full response (instead of streaming) before writing to stdout:
deepagents -n "Generate a .gitignore for Python" -q > .gitignore
deepagents -n "List dependencies" -q --no-stream | sort
In non-interactive mode, the agent is instructed to make reasonable assumptions and proceed autonomously rather than ask clarifying questions. It also favors non-interactive command variants (e.g., npm init -y, apt-get install -y).
# Allow specific commands (validated against the list)
deepagents -n "Run the tests and fix failures" -S "pytest,git,make"

# Use the curated safe-command list
deepagents -n "Build the project" -S recommended

# Allow any shell command
deepagents -n "Fix the build" -S all
Use with caution.-S all (or --shell-allow-list all) lets the agent execute arbitrary shell commands with no human confirmation.

​
Trace with LangSmith

Enable LangSmith tracing to see agent operations, tool calls, and decisions in a LangSmith project. Add your tracing keys to ~/.deepagents/.env so tracing is enabled in every session without per-shell exports:
~/.deepagents/.env
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=lsv2_...
LANGSMITH_PROJECT=optional-project-name  # Specify a project name or default to "deepagents-cli"
To override for a specific project, add the same keys to a .env in the project directory. See environment variables for the full loading order. You can also set these as shell environment variables if you prefer. Shell exports always take precedence over .env values, so this is a good option for temporary overrides or testing: 
export LANGSMITH_TRACING=false
When invoking the CLI programmatically from a LangChain application (e.g., as a subprocess in non-interactive mode), both your app and the CLI produce LangSmith traces. By default, these all land in the same project.To send CLI traces to a dedicated project, set DEEPAGENTS_CLI_LANGSMITH_PROJECT:
~/.deepagents/.env
DEEPAGENTS_CLI_LANGSMITH_PROJECT=my-deep-agent-execution
Then configure LANGSMITH_PROJECT for your parent application’s traces:
~/.deepagents/.env
LANGSMITH_PROJECT=my-app-traces
This keeps your app-level observability clean while still capturing the agent’s internal execution in a separate project.You can also scope LangSmith credentials to the CLI using the DEEPAGENTS_CLI_ prefix (e.g., DEEPAGENTS_CLI_LANGSMITH_API_KEY).
When configured, the CLI displays a status line with a link to the LangSmith project. In supported terminals, click the link to open it directly. You can also use /trace to print the URL and open it in your browser. 
✓ LangSmith tracing: 'my-project'
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.
Edit this page on GitHub or file an issue.