Skip to content

overview.mdx

Latest commit

 

History

History
905 lines (702 loc) · 44.3 KB

overview.mdx

File metadata and controls

905 lines (702 loc) · 44.3 KB
title Deep Agents CLI
sidebarTitle Use the CLI
description Terminal coding agent built on the Deep Agents SDK

The Deep Agents CLI is an open source terminal coding agent built on the Deep Agents SDK. It retains persistent memory, maintains context across sessions, learns project conventions, uses customizable skills, and executes code with approval controls.

Deep Agents CLI

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.
  • 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.
  • 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:

| Tool | Description | Human-in-the-Loop |
|------|-------------|-------------------|
| `ls` | List files and directories | - |
| `read_file` | Read contents of a file; multimodal content for select models | - |
| `write_file` | Create or overwrite a file | Required<sup>1</sup> |
| `edit_file` | Make targeted edits to existing files | Required<sup>1</sup> |
| `glob` | Find files matching a pattern | - |
| `grep` | Search for text patterns across files | - |
| `execute` | Execute shell commands locally or in a remote sandbox | Required<sup>1</sup> |
| `web_search` | Search the web using Tavily | Required<sup>1</sup> |
| `fetch_url` | Fetch and convert web pages to markdown | Required<sup>1</sup> |
| `task` | Delegate work to subagents for parallel execution | Required<sup>1</sup> |
| `ask_user` | Ask the user free-form or multiple-choice questions | - |
| `compact_conversation` | Summarize older messages, offload originals to backend storage, and replace them in context with the summary | Mixed<sup>2</sup> |
| `write_todos` | Create and manage task lists for complex work | - |

<sup>1</sup>: Potentially destructive operations require user approval before execution. To bypass human approval, you can toggle auto-approve (shift+tab) or start with the option:

```bash
deepagents -y
# or
deepagents --auto-approve
```

<Note>
    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](#non-interactive-mode-and-piping) for more details.
</Note>

<sup>2</sup>: 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](https://youtu.be/IrnacLa9PJc?si=3yUnPbxnm2yaqVQb) to see how the Deep Agents CLI works. The Deep Agents CLI is not officially supported on Windows. Windows users can try running it under [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install).

Quickstart

Export your provider's API key as an environment variable or add it to `~/.deepagents/.env`: 
    <Tabs>
        <Tab title="OpenAI">
            ```bash
            export OPENAI_API_KEY="your-api-key"
            ```
        </Tab>
        <Tab title="Anthropic">
            ```bash
            export ANTHROPIC_API_KEY="your-api-key"
            ```
        </Tab>
        <Tab title="Google">
            ```bash
            export GOOGLE_API_KEY="your-api-key"
            ```
        </Tab>
        <Tab title="Other">
            See [Providers](#providers) for the full list of supported providers and their required environment variables.
        </Tab>
    </Tabs>

    <Tip>
        To avoid setting keys in every terminal session, add them to `~/.deepagents/.env`. See [environment variables](/oss/deepagents/cli/configuration#environment-variables).
    </Tip>

    The CLI works with any LLM that supports tool calling. OpenAI, Anthropic, and Google are installed by default. For other providers (Ollama, Groq, xAI, etc.), see [Providers](#providers).
</Step>

<Step title="Install and run" icon="terminal">
    OpenAI, Anthropic, and Google are installed by default. Other providers (Ollama, Groq, xAI, etc.) are available as optional extras — see [Providers](#providers) for details.

    <CodeGroup>
        ```bash Script
        curl -LsSf https://raw.githubusercontent.com/langchain-ai/deepagents/refs/heads/main/libs/cli/scripts/install.sh | bash
        ```

        ```bash Optional extras
        # OpenAI, Anthropic, and Gemini are included by default
        DEEPAGENTS_EXTRAS="ollama,groq" curl -LsSf https://raw.githubusercontent.com/langchain-ai/deepagents/refs/heads/main/libs/cli/scripts/install.sh | bash
        ```

        ```bash uv
        uv tool install 'deepagents-cli[ollama,groq]'
        ```
    </CodeGroup>

    ```bash
    deepagents
    ```
</Step>

<Step title="Give the agent a task" icon="message">
    ```txt
    Create a Python script that prints "Hello, World!"
    ```

    The agent proposes changes with diffs for your approval before modifying files.
</Step>

<Step title="Enable tracing (optional)" icon="chart-dots">
    To view agent operations, tool calls, and decisions in LangSmith, add the following to `~/.deepagents/.env` or export the variables in your shell:

    ```bash title="~/.deepagents/.env"
    LANGSMITH_TRACING=true
    LANGSMITH_API_KEY=lsv2_...
    LANGSMITH_PROJECT=optional-project-name  # Specify a project name or default to "deepagents-cli"
    ```

    For setup details and usage, see [Tracing with LangSmith](#tracing-with-langsmith).
</Step>

Providers

OpenAI, Anthropic, and Google are included out of the box. Other providers are installed separately so you only pull in what you need.

# Add extra providers to an existing install
uv tool install deepagents-cli --with langchain-xai

For the full list of supported providers, see Model providers.

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. See [Switch models](#switch-models) for details
    - `/agents` - Hot-swap between pre-configured agents without relaunching. See [Switch agents](#switch-agents) 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](/oss/deepagents/cli/configuration#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](/oss/deepagents/cli/configuration#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](/oss/deepagents/cli/configuration#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
</Accordion>

<Accordion title="Shell commands" icon="prompt">
    Type `!` to enter shell mode, then type your command.

    ```bash
    git status
    npm test
    ls -la
    ```
</Accordion>

<Accordion title="Keyboard shortcuts" icon="keyboard">
    **General**

    | Shortcut | Action |
    |-|-|
    | `Enter` | Submit prompt |
    | `Shift+Enter`, `Ctrl+J`, `Alt+Enter`, or `Ctrl+Enter` | Insert newline |
    | `Ctrl+A` | Select all text in input |
    | `@filename` | Auto-complete files and inject content |
    | `Shift+Tab` or `Ctrl+T` | Toggle auto-approve |
    | `Ctrl+U` | Delete to start of line |
    | `Ctrl+X` | Open prompt in external editor |
    | `Ctrl+O` | Expand/collapse the most recent tool output |
    | `Escape` | Interrupt current operation |
    | `Ctrl+C` | Interrupt or quit |
    | `Ctrl+D` | Exit |
</Accordion>

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: 
    ```bash
    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.
</Accordion>

<Accordion title="Clean output and buffering" icon="buffer">
    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:

    ```bash
    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`).
</Accordion>

<Accordion title="Shell execution examples" icon="shield-check">
    ```bash
    # 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
    ```
</Accordion>
**Use with caution.** 
`-S all` (or `--shell-allow-list all`) lets the agent execute arbitrary shell commands with no human confirmation.

Run a command at startup

Use --startup-cmd to run a shell command once before the session accepts its first prompt. The output is shown to you at the top of the session, which is handy for checking git status, listing files, or verifying environment setup before typing the first prompt.

# Interactive: show git status before the first prompt
deepagents --startup-cmd "git status"

# Combine with an initial prompt — the command runs first, then the prompt is submitted
deepagents --startup-cmd "ls -la" -m "Summarize what's in this directory"

# Non-interactive: see env state before the task runs
deepagents --startup-cmd "git diff --stat" -n "Review these changes"

The command runs before any -m prompt or --skill invocation is dispatched and respects your shell environment. Non-zero exits and timeouts emit a warning but do not abort the session. In non-interactive mode, the command has a 60-second timeout.

The output is **not** injected into the agent's message history — the LLM does not see it. To hand command output to the agent, pipe it in via stdin instead (e.g., `git diff | deepagents -n "Review these changes"`).

Switch models

You can switch models during a session without restarting the CLI using the /model command, or at launch with the --model flag:

> /model anthropic:claude-opus-4-6
> /model openai:gpt-5.4
deepagents --model openai:gpt-5.4

Run /model to open an interactive model selector that displays available models grouped by provider.

For full details on switching models, setting a default, and adding custom model providers, see Model providers.

The selector shows a detail footer for the highlighted model with context window size, input modalities (text, image, audio, PDF, video), and capabilities (reasoning, tool calling, structured output). 
    Values overridden by `--profile-override` or `config.toml` are marked with a yellow `*` prefix.
</Accordion>

<Accordion title="Model parameters" icon="adjustments">
    Pass extra model constructor parameters when switching mid-session using `--model-params`:

    ```txt
    > /model --model-params '{"temperature": 0.7}' anthropic:claude-sonnet-4-5
    > /model --model-params '{"temperature": 0.7}'  # opens selector, applies params to chosen model
    ```

    These are session-only overrides and take the highest priority, overriding values from config file `params`. `--model-params` cannot be combined with `--default`.
</Accordion>

Switch agents

Run /agents to open the agent selector and hot-swap between agents in ~/.deepagents/ without relaunching. Switching resets the conversation thread and refreshes skill discovery. The choice is persisted, so the next bare deepagents launch resumes the same agent. -a/--agent always overrides; -r/--resume restores the thread's original agent.

Configuration

The CLI stores all configuration under ~/.deepagents/. Within that directory, each agent gets its own subdirectory (default: agent):

Path Purpose
~/.deepagents/config.toml Model defaults, provider settings, constructor params, profile overrides, themes, update settings, MCP trust store
~/.deepagents/.env Global API keys and secrets. See configuration
~/.deepagents/hooks.json Lifecycle 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

For the full reference — including config.toml schema, provider parameters, profile overrides, and hook configuration — see Configuration.

Memory

There are two primary ways to customize any agent:

  • Memory: AGENTS.md files and auto-saved memories that persist across sessions. Use memory for general coding style, preferences, and learned conventions.

  • Skills: Global and project-specific context, conventions, guidelines, or instructions. Use skills for context that is only required when performing specific tasks.

Use /remember to explicitly prompt the agent to update its memory and skills from the current conversation.

Building a custom agent with the SDK? See [Memory](/oss/deepagents/memory) for programmatic memory backends.

Automatic memory

As you use the agent, it automatically stores information in ~/.deepagents/<agent_name>/memories/ as markdown files using a memory-first protocol:

  1. Research: Searches memory for relevant context before starting tasks
  2. Response: Checks memory when uncertain during execution
  3. Learning: Automatically saves new information for future sessions

The agent organizes its memories by topic with descriptive filenames:

~/.deepagents/backend-dev/memories/
├── api-conventions.md
├── database-schema.md
└── deployment-process.md

When you teach the agent conventions:

deepagents --agent backend-dev
> Our API uses snake_case and includes created_at/updated_at timestamps

It remembers for future sessions:

> Create a /users endpoint
# Applies conventions without prompting

AGENTS.md files

AGENTS.md files provide persistent context that is always loaded at session start:

  • Global: ~/.deepagents/<agent_name>/AGENTS.md — loaded every session.
  • Project: .deepagents/AGENTS.md in any git project root — loaded when the CLI is run from within that project.

Both files are appended to the system prompt at startup.

The agent may also read its memory files when answering project-specific questions or when you reference past work or patterns. 
    The agent will update `AGENTS.md` as you provide information on how it should behave, feedback on its work, or instructions to remember something.
    It will also update its memory if it identifies patterns or preferences from your interactions.

    To add more structured project knowledge in additional memory files, add them in `.deepagents/` and reference them in the `AGENTS.md` file.
    You must reference additional files in the `AGENTS.md` file for the agent to be aware of them.
    The additional files will not be read on startup but the agent can reference and update them when needed.
</Accordion>

<Accordion title="When to use global vs. project AGENTS.md" icon="arrows-split">
    **Global `AGENTS.md`** (`~/.deepagents/agent/AGENTS.md`)

    - Your personality, style, and universal coding preferences
    - General tone and communication style
    - Universal coding preferences (formatting, type hints, etc.)
    - Tool usage patterns that apply everywhere
    - Workflows and methodologies that don't change per-project

    **Project `AGENTS.md`** (`.deepagents/AGENTS.md` in project root)

    - Project-specific context and conventions
    - Project architecture and design patterns
    - Coding conventions specific to this codebase
    - Testing strategies and deployment processes
    - Team guidelines and project structure
</Accordion>

Use skills

Skills are reusable agent capabilities that provide specialized workflows and domain knowledge. You can use skills to provide your deep agent with new capabilities and expertise. Deep agent skills follow the Agent Skills standard. Once you have added skills your deep agent will automatically make use of them and update them as you use the agent and provide it with additional information.

Use /remember to explicitly prompt the agent to update skills and memory from the current conversation.

1. Create a skill: 
        ```bash
        # User skill (stored in ~/.deepagents/<agent_name>/skills/)
        deepagents skills create test-skill

        # Project skill (stored in .deepagents/skills/)
        deepagents skills create test-skill --project
        ```

        This generates:

        ```plaintext
        skills/
        └── test-skill
            └── SKILL.md
        ```

    1. Open the generated `SKILL.md` and edit the file to include your instructions.

    1. Optionally add additional scripts or other resources to the `test-skill` folder. For more information, see [Examples](/oss/deepagents/skills#example).

    You can also copy existing skills directly to the agent's folder:

    ```bash
    mkdir -p ~/.deepagents/<agent_name>/skills
    cp -r examples/skills/web-research ~/.deepagents/<agent_name>/skills/
    ```
</Accordion>

<Accordion title="Install community skills" icon="download">
    You can use tools like Vercel's [Skills CLI](https://github.com/vercel-labs/skills) to install community [Agent Skills](https://agentskills.io/) in your environment and make them available to your deep agents:

    ```bash
    # Install a skill globally
    npx skills add vercel-labs/agent-skills --skill web-design-guidelines -a deepagents -g -y

    # List installed skills
    npx skills ls -a deepagents -g
    ```

    Global installs (`-g`) symlink skills into `~/.deepagents/agent/skills/` — the default agent's user-level skills directory. Project-level installs (omit `-g`) place skills in `.deepagents/skills/` relative to the current directory, making them available to any agent running in that project regardless of agent name.

    <Note>
        Global installs target the default `agent` directory only. If you use a custom-named agent, either use project-level installs or manually symlink the skill into `~/.deepagents/{your-agent}/skills/`.
    </Note>
</Accordion>

<Accordion title="Skill discovery" icon="radar">
    At startup, the CLI discovers skills from both Deep Agents and shared alias directories:

    ```text
    ~/.deepagents/<agent_name>/skills/
    ~/.agents/skills/
    .deepagents/skills/
    .agents/skills/
    ~/.claude/skills/          (experimental)
    .claude/skills/            (experimental)
    ```

    When duplicate skill names exist, later-precedence directories override earlier ones (see [App data](/oss/deepagents/data-locations#skills)).

    For project-specific skills, the project's root folder must have a `.git` folder.
    When you start the CLI from anywhere within the project's folder, the CLI will find the project's root folder by checking for a containing `.git` folder.

    For each skill, the CLI reads the name and the description from the `SKILL.md` file's frontmatter.
    As you use the CLI, if a task matches the skill's description, the agent will read the skill file and follow its instructions.

    You can also invoke a skill directly with `/skill:<name> [args]`. Skill discovery runs at startup and again on `/reload`.
</Accordion>

<Accordion title="Invoke a skill from the command line" icon="player-play">
    Use `--skill` to invoke a skill at launch without typing a slash command interactively:

    ```bash
    # Open the TUI and immediately run a skill
    deepagents --skill code-review

    # Pass a request to the skill with -m
    deepagents --skill code-review -m 'review the auth module'

    # Pipe content into a skill
    cat diff.txt | deepagents --skill code-review

    # Pipe content and add a request
    cat diff.txt | deepagents --skill code-review -m 'focus on security'
    ```

    `--skill` also works in non-interactive mode:

    ```bash
    # Run a skill headlessly
    deepagents --skill code-review -n 'review this patch'

    # Quiet mode (only agent output on stdout)
    deepagents --skill code-review -n 'review this patch' -q
    ```

    <Note>
        `--skill` with `--quiet` or `--no-stream` requires `-n` (non-interactive mode).
    </Note>
</Accordion>

<Accordion title="List skills" icon="list">
    ```bash
    # List all user skills
    deepagents skills list

    # List project skills
    deepagents skills list --project

    # Get detailed info about a specific skill
    deepagents skills info test-skill
    deepagents skills info test-skill --project
    ```
</Accordion>

Subagents

Define custom subagents as markdown files so the CLI agent can delegate specialized tasks to them. Each subagent lives in its own folder with an AGENTS.md file:

.deepagents/agents/{subagent-name}/AGENTS.md   # Project-level
~/.deepagents/{agent}/agents/{subagent-name}/AGENTS.md  # User-level

Project subagents override user subagents with the same name (see precedence rules).

The frontmatter requires name and description (same as the SubAgent dictionary spec). The markdown body becomes the subagent's system_prompt. In addition to the base spec, AGENTS.md files support an optional model frontmatter field that overrides the main agent's model for this subagent. Uses the provider:model-name format (e.g., anthropic:claude-opus-4-6, openai:gpt-5.4). Omit to inherit the main agent's model.

Other `SubAgent` fields (`tools`, `middleware`, `interrupt_on`, `skills`) are currently not configurable via `AGENTS.md` frontmatter — custom subagents defined this way inherit the main agent's tools. Use the SDK directly for full control. Subagent `AGENTS.md` files use YAML frontmatter followed by a markdown body: 
    ```markdown
    ---
    name: researcher
    description: Research topics on the web before writing content
    model: anthropic:claude-haiku-4-5-20251001
    ---

    You are a research assistant with access to web search.

    ## Your Process
    1. Search for relevant information
    2. Summarize findings clearly
    ```
</Accordion>

<Accordion title="Example: cost-efficient subagents">
    Use a cheaper, faster model for simple delegation tasks while keeping the main agent on a more capable model:

    ```markdown
    ---
    name: general-purpose
    description: General-purpose agent for research and multi-step tasks
    model: anthropic:claude-haiku-4-5-20251001
    ---

    You are a general-purpose assistant. Complete the task efficiently and return a concise summary.
    ```

    This overrides the built-in general-purpose subagent, routing all delegated tasks to a cheaper model. See [Override the general-purpose subagent](/oss/deepagents/subagents#override-the-general-purpose-subagent) for more.
</Accordion>

Use MCP tools

Extend the CLI with tools from external MCP (Model Context Protocol) servers. Place a .mcp.json at your project root and the CLI discovers it automatically. See the MCP tools guide for configuration format, auto-discovery, and troubleshooting.

Use remote sandboxes

The CLI uses the sandbox as tool pattern: the CLI process (LLM loop, memory, tool dispatch) runs on your machine, but agent tool calls (read_file, write_file, execute, etc.) target the remote sandbox, not your local filesystem. To get files into the sandbox, use a setup script or the provider's file transfer APIs (see Working with files).

For a deeper look at sandbox architecture, integration patterns, and security best practices, see Sandboxes.

LangSmith sandbox support is included with the CLI by default. AgentCore, Modal, Daytona, and Runloop require installing extras. Included by default when installing `deepagents-cli`. No extra installation needed. ```bash uv tool install deepagents-cli --with langchain-daytona ``` ```bash uv tool install deepagents-cli --with langchain-modal ``` ```bash uv tool install deepagents-cli --with langchain-runloop ``` ```bash uv tool install deepagents-cli --with langchain-agentcore-codeinterpreter ``` 
<Step title="Set provider credentials" icon="key">
    <Tabs>
        <Tab title="LangSmith">
            ```bash
            export LANGSMITH_API_KEY="your-key"
            ```
        </Tab>
        <Tab title="Daytona">
            ```bash
            export DAYTONA_API_KEY="your-key"
            ```
        </Tab>
        <Tab title="Modal">
            ```bash
            modal setup
            ```
        </Tab>
        <Tab title="Runloop">
            ```bash
            export RUNLOOP_API_KEY="your-key"
            ```
        </Tab>
        <Tab title="AgentCore">
            ```bash
            export AWS_ACCESS_KEY_ID="your-key"
            export AWS_SECRET_ACCESS_KEY="your-secret"
            export AWS_SESSION_TOKEN="session-token"
            export AWS_REGION="us-west-2"
            ```
        </Tab>
    </Tabs>
</Step>

<Step title="Run the CLI with a sandbox" icon="player-play">
    <Tabs>
        <Tab title="LangSmith">
            ```bash
            deepagents --sandbox langsmith
            ```
        </Tab>
        <Tab title="Daytona">
            ```bash
            deepagents --sandbox daytona
            ```
        </Tab>
        <Tab title="Modal">
            ```bash
            deepagents --sandbox modal
            ```
        </Tab>
        <Tab title="Runloop">
            ```bash
            deepagents --sandbox runloop
            ```
        </Tab>
        <Tab title="AgentCore">
            ```bash
            deepagents --sandbox agentcore
            ```
        </Tab>
    </Tabs>
</Step>
| Flag | Description | |------|-------------| | `--sandbox TYPE` | Sandbox provider to use: `langsmith`, `agentcore`, `modal`, `daytona`, or `runloop` (default: `none`) | | `--sandbox-id ID` | Reuse an existing sandbox by ID instead of creating a new one. Skips creation and cleanup. Refer to your sandbox documentation for more | | `--sandbox-setup PATH` | Path to a setup script to run inside the sandbox upon creation | 
    Examples:

    ```bash
    # Create a new Daytona sandbox
    deepagents --sandbox daytona

    # Reuse an existing sandbox (skips creation and cleanup)
    deepagents --sandbox runloop --sandbox-id dbx_abc123

    # Run a setup script after sandbox creation
    deepagents --sandbox modal --sandbox-setup ./setup.sh
    ```
</Accordion>

<Accordion title="Setup scripts" icon="file-code">
    Use `--sandbox-setup` to run a shell script inside the sandbox after creation. This is useful for cloning repos, installing dependencies, and configuring environment variables.

    ```bash title="setup.sh"
    #!/bin/bash
    set -e

    # Clone repository using GitHub token
    git clone https://x-access-token:${GITHUB_TOKEN}@github.com/username/repo.git $HOME/workspace
    cd $HOME/workspace

    # Make environment variables persistent
    cat >> ~/.bashrc <<'EOF'
    export GITHUB_TOKEN="${GITHUB_TOKEN}"
    export OPENAI_API_KEY="${OPENAI_API_KEY}"
    cd $HOME/workspace
    EOF
    source ~/.bashrc
    ```

    The CLI expands `${VAR}` references in setup scripts using your local environment variables. Store secrets in a local `.env` file for the setup script to access.
</Accordion>
Sandboxes isolate code execution, but agents remain vulnerable to prompt injection with untrusted inputs. Use human-in-the-loop approval, short-lived secrets, and trusted setup scripts only. See [Security considerations](/oss/deepagents/sandboxes#security-considerations) for details.

Tracing 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:

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](#non-interactive-mode-and-piping)), 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`:

```bash title="~/.deepagents/.env"
DEEPAGENTS_CLI_LANGSMITH_PROJECT=my-deep-agent-execution
```

Then configure `LANGSMITH_PROJECT` for your parent application's traces:

```bash title="~/.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](/oss/deepagents/cli/configuration#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'

Command reference

# Use a specific agent configuration
deepagents --agent mybot

# Use a specific model (provider:model format or auto-detect)
deepagents --model anthropic:claude-sonnet-4-5
deepagents --model gpt-4o

# Auto-approve tool usage (skip human-in-the-loop prompts)
deepagents -y
| Option | Description | |------------------------|-------------------------------------------------------------| | `-a`, `--agent NAME` | Use 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 MODEL` | Use a specific model (`provider:model`) | | `--model-params JSON` | Extra kwargs to pass to the model as a JSON string (e.g., `'{"temperature": 0.7}'`) | | `--default-model [MODEL]` | Set the default model | | `--clear-default-model` | Clear the default model | | `-r`, `--resume [ID]` | Resume a session: `-r` for most recent, `-r ` for a specific thread | | `-m`, `--message TEXT` | Initial prompt to auto-submit when the session starts (interactive mode) | | `--skill NAME` | Invoke a skill at startup | | `--startup-cmd CMD` | Shell 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. Non-zero exits and timeouts warn but do not abort; non-interactive mode applies a 60s timeout. See [Run a command at startup](#run-a-command-at-startup) | | `-n`, `--non-interactive TEXT` | Run a single task non-interactively and exit. Shell is disabled unless `--shell-allow-list` is set | | `--max-turns N` | Cap agentic turns in non-interactive mode. Exits with code 124 when exceeded. Requires `-n` or piped stdin. See [Cap turn count with `--max-turns`](#non-interactive-mode-and-piping) | | `-q`, `--quiet` | Clean output for piping—only the agent's response goes to stdout. Requires `-n` or piped stdin | | `--no-stream` | Buffer the full response and write to stdout at once instead of streaming. Requires `-n` or piped stdin | | `--stdin` | Read input from stdin explicitly instead of auto-detection. Errors clearly when stdin is unavailable or is a TTY | | `-y`, `--auto-approve` | Auto-approve all tool calls without prompting (disables human-in-the-loop). Toggle with `Shift+Tab` during an interactive session | | `-S`, `--shell-allow-list LIST` | Comma-separated shell commands to auto-approve, `'recommended'` for safe defaults, or `'all'` to allow any command. Applies to both `-n` and interactive modes | | `--json` | Emit machine-readable JSON from management subcommands (`agents`, `threads`, `skills`, `update`). Output envelope: `{"schema_version": 1, "command": "...", "data": ...}` | | `--sandbox TYPE` | Remote sandbox for code execution: `none` (default), `langsmith`, `agentcore`, `modal`, `daytona`, `runloop`. LangSmith is included; AgentCore/Modal/Daytona/Runloop require extras | | `--sandbox-id ID` | Reuse an existing sandbox (skips creation and cleanup) | | `--sandbox-setup PATH` | Path to setup script to run in sandbox after creation | | `--mcp-config PATH` | Add an explicit MCP config as the highest-precedence source (merged with auto-discovered configs) | | `--no-mcp` | Disable all MCP tool loading | | `--trust-project-mcp` | Trust project-level MCP configs with stdio servers (skip approval prompt) | | `--profile-override JSON` | Override model profile fields as a JSON string (e.g., `'{"max_input_tokens": 4096}'`). Merged on top of config file profile overrides | | `--acp` | Run as an ACP server over stdio instead of launching the interactive UI | | `-v`, `--version` | Display version | | `-h`, `--help` | Show help | 
<Accordion title="CLI commands" icon="terminal">
    | Command                              | Description                            |
    |--------------------------------------|----------------------------------------|
    | `deepagents help`                    | Show help                              |
    | `deepagents agents list`             | List all agents (alias: `ls`)          |
    | `deepagents agents reset --agent NAME` | Clear agent memory and reset to default. Supports `--dry-run` |
    | `deepagents agents reset --agent NAME --target SOURCE` | Copy memory from another agent |
    | `deepagents update`                  | Check 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 ID`       | Delete a session. Supports `--dry-run` |
    | `deepagents deploy`                  | Deploy your agent to LangSmith. See [Deploy with the CLI](/oss/deepagents/deploy) |

    All management subcommands support `--json` for machine-readable output. See [command-line options](#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.
</Accordion>