> ## Documentation Index > Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-ccdata-1770345743-a5afa16.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Deep Agents CLI > Interactive command-line interface for building with Deep Agents The Deep Agents CLI is an open source coding assistant that runs in your terminal and retains persistent memory. Your CLI agents maintain context across sessions, learn project conventions, use customizable skills, and execute code with approval controls.

The Deep Agents CLI has the following built-in capabilities: * **File operations** - read, write, and edit files in your project with tools that enable agents to manage and modify code and documentation. * **Shell command execution** - execute shell commands to run tests, build projects, manage dependencies, and interact with version control systems. * **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 through the built-in todo system. * **Memory storage and retrieval** - store and retrieve information across sessions, enabling agents to remember project conventions and learned patterns. * **Human-in-the-loop** - require human approval for sensitive tool operations. * **Skills** - extend agent capabilities with custom expertise and instructions stored in skill directories. ## 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 | - | | `write_file` | Create or overwrite a file | Required¹ | | `edit_file` | Make targeted edits to existing files | Required¹ | | `glob` | Find files matching a pattern (e.g., `**/*.py`) | - | | `grep` | Search for text patterns across files | - | | `shell` | Execute shell commands (local mode) | Required¹ | | `execute` | Execute commands in remote sandbox (sandbox mode) | Required¹ | | `web_search` | Search the web using Tavily API | Required¹ | | `fetch_url` | Fetch and convert web pages to markdown | Required¹ | | `task` | Delegate work to subagents for parallel execution | Required¹ | | `write_todos` | Create and manage task lists for complex work | - | ¹: Potentially destructive operations require user approval before execution. To bypass human approval, you can toggle auto-approve or start the deep agent with the `auto-approve` option: ```bash theme={null} deepagents --auto-approve ``` [Watch the demo video](https://youtu.be/IrnacLa9PJc?si=3yUnPbxnm2yaqVQb) to see how the Deep Agents CLI works. ## Quickstart Export as an environment variable: ```bash theme={null} export OPENAI_API_KEY="your-api-key" ``` Or create a `.env` file in your project root: ```bash theme={null} OPENAI_API_KEY=your-api-key ``` Export as an environment variable: ```bash theme={null} export ANTHROPIC_API_KEY="your-api-key" ``` Or create a `.env` file in your project root: ```bash theme={null} ANTHROPIC_API_KEY=your-api-key ``` Export as an environment variable: ```bash theme={null} export GOOGLE_API_KEY="your-api-key" ``` Or create a `.env` file in your project root: ```bash theme={null} GOOGLE_API_KEY=your-api-key ``` If you have multiple API keys set, you can use the `--model` CLI option to specify which model to use, which will automatically use the corresponding API key. For more information see [Additional installation and configuration options](/oss/python/deepagents/cli#additional-installation-and-configuration-options). ```bash Install globally theme={null} uv tool install deepagents-cli deepagents ``` ```bash Run (without global install) theme={null} uvx deepagents-cli ``` ```txt theme={null} > Create a Python script that prints "Hello, World!" ``` The agent proposes changes with diffs for your approval before modifying files. Install locally if needed: ```bash pip theme={null} pip install deepagents-cli ``` ```bash uv theme={null} uv add deepagents-cli ``` The CLI automatically selects a provider based on which API keys are available. If multiple keys are set, it uses the first match in this order: | Priority | API key | Default model | | -------- | ------------------- | ---------------------------- | | 1st | `OPENAI_API_KEY` | `gpt-5.2` | | 2nd | `ANTHROPIC_API_KEY` | `claude-sonnet-4-5-20250929` | | 3rd | `GOOGLE_API_KEY` | `gemini-3-pro-preview` | To use a different model, pass the `--model` flag explicitly. The CLI auto-detects the provider from the model name and requires the corresponding API key. The active model is displayed at startup. For example, to use Claude Opus 4.5: ```bash theme={null} deepagents --model claude-opus-4-5-20251101 ``` Enable web search (optional): ```bash theme={null} export TAVILY_API_KEY="your-key" ``` API keys can be set as environment variables or in a `.env` file. ## Tracing with LangSmith Enable LangSmith tracing to see agent operations in your LangSmith dashboard: 1. Enable LangSmith tracing: ```bash theme={null} export LANGCHAIN_TRACING=true export LANGCHAIN_API_KEY="your-api-key" ``` 2. Configure agent tracing for deep agent operations such as tool calls and agent decisions: ```bash theme={null} export DEEPAGENTS_LANGSMITH_PROJECT="my-deep-agent-execution" ``` 3. If you are building a LangChain app with deep agents, and want to separate agent traces from your app's traces, also configure `LANGSMITH_PROJECT`: ```bash theme={null} export LANGSMITH_PROJECT="my-app-calls-to-langchain" ``` When configured, the CLI displays: ```sh theme={null} ✓ LangSmith tracing: 'my-project' ``` ## Configuration Each agent has its own configuration directory at `~/.deepagents//`. The default agent name is `agent`. As you start the agent if no folder for that agent name exists then it's created at that path `~/.deepagents//`. ```bash theme={null} # List all configured agents deepagents list # Use a specific agent configuration deepagents --agent mybot # Use a specific model (auto-detects provider) deepagents --model claude-sonnet-4-5-20250929 deepagents --model gpt-4o # Auto-approve tool usage (skip human-in-the-loop prompts) deepagents --auto-approve # Execute code in a remote sandbox deepagents --sandbox modal # or runloop, daytona deepagents --sandbox-id dbx_123 # reuse existing sandbox ``` | Option | Description | | ---------------------- | ------------------------------------------------------------------------------------ | | `--agent NAME` | Use named agent with separate memory | | `--auto-approve` | Skip tool confirmation prompts (toggle with `Ctrl+T`) | | `--resume`, `-r` | Resume most recent session | | `--sandbox TYPE` | Execute in [remote sandbox](#use-remote-sandboxes): `modal`, `daytona`, or `runloop` | | `--sandbox-id ID` | Reuse existing sandbox | | `--sandbox-setup PATH` | Run setup script in sandbox | | `--version` | Display version | | Command | Description | | ----------------------------------------------- | -------------------------------------------------------------- | | `deepagents list` | List all agents | | `deepagents skills` | Manage agent skills - create, list, and view skill information | | `deepagents help` | Show help | | `deepagents reset --agent NAME` | Clear agent memory and reset to default | | `deepagents reset --agent NAME --target SOURCE` | Copy memory from another agent | | `deepagents threads list` | List all sessions | | `deepagents threads delete ID` | Delete a session | ## 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: * `/remember` - Review conversation and update memory and skills * `/tokens` - Display token usage * `/clear` - Clear conversation history * `/quit` - Exit the CLI * `/help` - Show help * `/threads` - Show session info * `/version` - Show version Execute shell commands directly by prefixing with `!`: ```bash theme={null} !git status !npm test !ls -la ``` | Shortcut | Action | | --------------------------------------------------------- | -------------------------------------- | | `Enter` | Submit | | `Ctrl+J` or `Option+Enter` (Mac) or `Alt+Enter` (Windows) | Newline | | `Ctrl+E` | External editor | | `Shift+Tab` | Toggle auto-approve | | `@filename` | Auto-complete files and inject content | | `Ctrl+C` | Interrupt | | `Ctrl+D` | Exit | ## Teach your agent project conventions As you use the agent, it automatically stores information in `~/.deepagents//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: ```bash theme={null} uvx deepagents-cli --agent backend-dev > Our API uses snake_case and includes created_at/updated_at timestamps ``` It remembers for future sessions: ```bash theme={null} > Create a /users endpoint # Applies conventions without prompting ``` ## Customize your deep agent There are two primary ways to customize any agent: * **Memory**: Global and project-specific `AGENTS.md` files which are loaded in full at session start. Use memory for general coding style and preferences. * **Skills**: Global and project-specific context, conventions, guidelines, or instructions. Use skills for context that is only required when performing specific tasks. ### Provide project or user context [`AGENTS.md` files](https://agents.md/) files provide persistent memory that is always loaded at session start. You can provide global user memory for the agent in `~/.deepagents//AGENTS.md`. This file is always loaded when you start a new deep agent session. The agent may also read its memory files when answering project-specific questions or when you reference past work or patterns. For project-specific memory, you can add context to `.deepagents/AGENTS.md` in any project's root folder as long as the project uses git. 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. Both global and project-level `AGENTS.md` files are loaded together and appended to the system prompt at startup. The agent will update them as you use the agent and provide it with additional information on how it should behave, feedback on its work, or instructions to remember something. The agent will also update its memory if it identifies patterns or preferences from your interactions. If you would like to explicitly prompt your deep agent to update skills and memory based on the current context from the thread use the `/remember` command which loads a custom instruction to review the context and perform updates. To add more structured project knowledge in additional memory files, you can 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 these files. The additional files will not be read on startup but the agent can reference and update them when needed. **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 ## Use remote sandboxes Execute code in isolated remote environments for safety and flexibility. Remote sandboxes provide the following benefits: * **Safety**: Protect your local machine from potentially harmful code execution * **Clean environments**: Use specific dependencies or OS configurations without local setup * **Parallel execution**: Run multiple agents simultaneously in isolated environments * **Long-running tasks**: Execute time-intensive operations without blocking your machine * **Reproducibility**: Ensure consistent execution environments across teams To use a remote sandbox, follow these steps: 1. Configure your sandbox provider ([Runloop](https://www.runloop.ai/), [Daytona](https://www.daytona.io/), or [Modal](https://modal.com/)): ```bash theme={null} # Runloop export RUNLOOP_API_KEY="your-key" # Daytona export DAYTONA_API_KEY="your-key" # Modal modal setup ``` 2. Run the CLI with a sandbox: ```bash theme={null} uvx deepagents-cli --sandbox runloop --sandbox-setup ./setup.sh ``` The agent runs locally but executes all code operations in the remote sandbox. Optional setup scripts can configure environment variables, clone repositories, and prepare dependencies. 3. (Optional) Create a `setup.sh` file to configure your sandbox environment: ```bash theme={null} #!/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 ``` Store secrets in a local `.env` file for the setup script to access. 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. Note that sandbox APIs are evolving rapidly, and we expect more providers to support proxies that help mitigate prompt injection and secrets management concerns. ## Use skills Skills are reusable agent capabilities that provide specialized workflows and domain knowledge. You can use [skills](/oss/python/deepagents/skills) to provide your deep agent with new capabilities and expertise. Deep agent skills follow the [Agent Skills standard](https://agentskills.io/). 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. If you would like to explicitly prompt your deep agent to update skills and memory based on the current context from the thread use the `/remember` command which loads a custom instruction to review the context and perform updates. ### Add skills 1. Start by creating a skill: ```bash theme={null} deepagents skills create test-skill ``` This will generate the correct the following files in your `~/.deepagents/` folder: ```bash theme={null} deepagents skills create test-skill --project ``` This will generate the correct the following files in your `~/{project}/.deepagents/skills` folder: ```plaintext theme={null} skills/ └── test-skill └── SKILL.md ``` 2. Open the generated `SKILL.md` and edit the file to include your instructions. 3. Optionally add additional scripts or other resources to the `test-skill` folder. For more information, see [Examples](/oss/python/deepagents/skills#examples). If you already have a skills folder with containing skills files, you can also copy them directly to the agent's folder: ```bash theme={null} mkdir -p ~/.deepagents//skills cp -r examples/skills/web-research ~/.deepagents//skills/ ``` At startup, the CLI scans the `~/.deepagents//skills/` and `.deepagents/skills/` directories. 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. ### List skills To see the lists you have installed, run: ```bash theme={null} deepagents skills list ``` ```bash theme={null} deepagents skills list --project ``` To get more information for a specific skill, run: ```bash theme={null} deepagents skills info test-skill ``` ```bash theme={null} deepagents skills info test-skill --project ``` *** [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/deepagents/cli.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose). [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.