Command reference

Deep Agents Code (dcode) accepts command-line flags at launch and exposes management subcommands for tools, agents, sessions, skills, credentials, and configuration. Use this page as a reference when you need to override defaults from the shell, run non-interactive tasks in scripts, or automate administration without opening a session. For installation and daily interactive use, see Quickstart. For how CLI flags fit into the broader configuration model, see Configuration.

Example usage

# Use a specific agent configuration
dcode --agent mybot

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

# Auto-approve tool usage (skip human-in-the-loop prompts)
dcode -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
dcode --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
dcode --startup-cmd "git diff --stat" -n "Review these changes"

Choose a model

Launch with --model (-M) to pin a model for one session. Use the provider:model format (for example, openai:gpt-5.5) or pass a bare model name when the provider is unambiguous:

dcode --model anthropic:claude-opus-4-8
dcode --model openai:gpt-5.5
dcode --model fireworks:accounts/fireworks/models/deepseek-v4-pro

When Deep Agents Code starts without --model, it resolves the model in this order:

1. --model flag when provided.
2. [models].default in ~/.deepagents/config.toml.
3. [models].recent in ~/.deepagents/config.toml (written automatically when you switch models in a session).
4. Environment auto-detection: the first available credential among OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, and GOOGLE_CLOUD_PROJECT (Gemini Enterprise Agent Platform).

Other providers (for example, Groq or Fireworks) are still available via --model or saved defaults even though they are not part of the startup auto-detection list. See Model providers for the full provider list and credential setup.

Set or clear a default model

Persist a default model for all future launches:

# Set the default
dcode --default-model anthropic:claude-opus-4-8

# View the current default
dcode --default-model

# Clear the default
dcode --clear-default-model

You can also pin a default from the interactive /model switcher (Ctrl+S) or set [models].default in config.toml. See Set a default model.

Set reasoning effort

/effort controls reasoning effort for the current model. Open the picker to see the levels supported by that model, or pass a level directly with /effort <level>.

Deep Agents Code saves the selection per provider:model in ~/.deepagents/config.toml for future sessions. Run /effort clear to remove the current model's saved preference and session override. Configured model parameters can still supply an effort value.

You can open /effort or click the footer's effort label while the agent works. A selection waits until the current task completes; it does not change the model request already in progress. If the model changes before the selection applies, reopen the picker for the new model.

For Anthropic models with thinking.type set to between_tools, the available levels are the model-supported subset of low, medium, and high.

Choose a summarization model

Use a separate model for automatic context compaction, /offload, and /compact without changing the main agent model:

# Set the summarization model for this launch
dcode --summarization-model openai:gpt-5.6-sol

In an interactive session, run /offload model to open the model picker, pass a model spec to switch directly, or pass clear to reuse the main agent model:

/offload model
/offload model openai:gpt-5.6-sol
/offload model clear

The summarization model resolves from --summarization-model, then [models].summarization_default in config.toml, then the main agent model. See Set a summarization model.

Model parameters and profile overrides

Pass extra constructor kwargs to the model with --model-params as a JSON string. These apply for the current session only and override config.toml provider params:

dcode --model openai:gpt-5.5 --model-params '{"reasoning": {"effort": "high"}}'
dcode --model anthropic:claude-opus-4-8 --model-params '{"thinking": {"type": "enabled", "budget_tokens": 10000}, "max_tokens": 16000}'

Override model profile fields (for example, max_input_tokens) with --profile-override. Values merge on top of config file overrides and persist across mid-session /model hot-swaps:

dcode --profile-override '{"max_input_tokens": 4096}'
dcode --model google_genai:gemini-3.6-flash --profile-override '{"max_input_tokens": 4096}'

For retry counts on transient errors, use --max-retries or the [retries] section in config.toml. See Model parameters and Profile overrides.

Install provider extras

Optional provider and sandbox packages ship as extras. Install from the shell without launching a session:

dcode --install groq
dcode --install fireworks
dcode --install ollama

Add --package to install an arbitrary provider package via uv --with (see Arbitrary providers), and --yes to skip confirmation prompts. To preinstall extras during the initial CLI install, set DEEPAGENTS_CODE_EXTRAS (for example, DEEPAGENTS_CODE_EXTRAS="groq,fireworks").

Remove an optional extra

Remove one installed extra while preserving the rest of the Deep Agents Code installation:

dcode uninstall groq
dcode --uninstall groq

/uninstall groq

Removal rebuilds a uv tool installation without the selected extra while preserving the interpreter, release channel, other extras, and packages installed with --package.

Agents and sessions

Use -a/--agent to launch with a named agent that has its own memory, skills, and AGENTS.md under ~/.deepagents/<agent_name>/. The flag overrides both [agents].default and [agents].recent in config.toml:

dcode --agent backend-dev

Resume a previous conversation with -r/--resume. Pass no ID to open the most recent thread, or pass a thread ID to resume a specific session. Resuming bypasses agent selection flags and restores the thread's original agent:

dcode -r
dcode -r abc123-thread-id

List and delete sessions with dcode threads list and dcode threads delete. See Memory and skills for how per-agent memory works.

Name a thread

Deep Agents Code automatically generates names for conversations so they are easier to find.

After the first model call, Deep Agents Code makes a separate LLM call to generate a name for the thread. Generation uses [threads].rename_model when set, otherwise the selected conversation model. Set [threads].auto_rename = false to disable automatic naming. See Name threads automatically.

In an interactive session:

• /rename <name>: Set a name of 1 to 50 printable characters.
• /rename: Generate a suggestion and edit it if needed.

Non-interactive mode and piping

Use -n/--non-interactive to run a single task without the interactive UI. Each non-interactive run starts a fresh thread; file-based state (memory, skills, configuration) persists across invocations:

dcode -n "Write a Python script that prints hello world"

When stdin is piped, Deep Agents Code runs non-interactively automatically:

echo "Explain this code" | dcode
cat error.log | dcode -n "What's causing this error?"
git diff | dcode -n "Review these changes"

When you combine piped input with -n or -m, the piped content appears first, followed by the flag text. The maximum piped input size is 10 MiB. Use --stdin to read from stdin explicitly instead of auto-detection.

Output, limits, and shell access

Use -q/--quiet to emit only the agent's response on stdout (for piping into other commands). Add --no-stream to buffer the full response before writing:

dcode -n "Generate a .gitignore for Python" -q > .gitignore
dcode -n "List dependencies" -q --no-stream | sort

Provider-visible reasoning is shown by default in interactive sessions, where it streams into a separate row that collapses when the phase ends; press Ctrl+O to reopen it. Non-interactive mode hides reasoning by default. When enabled there, reasoning goes to stderr so the final answer on stdout remains pipeable. Set DEEPAGENTS_CODE_SHOW_REASONING=0 to hide it in both modes, or pass --show-reasoning to show it for one launch. This setting applies for the full session. See Show provider-visible reasoning for persistent configuration.

Cap agent runs in CI with --max-turns or --timeout. Both exit with code 124 when the budget is exceeded. Requires -n or piped stdin:

dcode -n "fix the failing tests" --max-turns 10
dcode -n "run the test suite and summarise failures" --timeout 120

Shell execution is disabled by default in non-interactive mode. Enable it with -S/--shell-allow-list:

dcode -n "Run the tests and fix failures" -S "pytest,git,make"
dcode -n "Build the project" -S recommended
dcode -n "Fix the build" -S all

For more examples and tracing setup, see Non-interactive mode and piping.

Skills at launch

The --skill flag invokes a skill immediately on launch in interactive or non-interactive mode:

dcode --skill code-review
dcode --skill code-review -m 'review the auth module'
cat diff.txt | dcode --skill code-review -n 'review this patch'
dcode --skill code-review -n 'review this patch' -q

--skill with --quiet or --no-stream requires -n. Manage skills with dcode skills list, create, info, and delete. See Memory and skills.

Rubrics in scripts

Non-interactive runs cannot pause for interactive goal review. Pass acceptance criteria with --rubric when criteria are already known:

dcode -n "implement OAuth refresh handling" --rubric "tests pass; no unrelated files changed"
dcode -n "implement OAuth refresh handling" --rubric @acceptance.md

Set the grader model and iteration limit separately:

dcode -n "implement OAuth refresh handling" \
  --rubric "tests pass; no unrelated files changed" \
  --rubric-model openai:gpt-5.5 \
  --rubric-max-iterations 3

All rubric flags require -n or piped stdin. See Goals and rubrics.

Human-in-the-loop and shell access

Potentially destructive tool calls require approval by default. There are three approval modes to choose from: the default Manual mode requires confirmation at all checkpoints, Auto mode (-y/--auto-approve) uses an LLM classifier, and YOLO (--yolo) runs gated actions without review. Toggle between Manual and Auto during an interactive session with Shift+Tab:

dcode -y
dcode --yolo

The -S/--shell-allow-list flag applies in both interactive and non-interactive modes. Pass a comma-separated list of command names, recommended for safe read-only defaults, or all to permit any command. You can also set DEEPAGENTS_CODE_SHELL_ALLOW_LIST in the environment.

Restrict filesystem tools

By default, Deep Agents Code exposes all filesystem tools. To expose only a subset, pass a comma-separated list:

dcode -n "Audit this repository" --allow-fs-tools ls,read_file,glob,grep

Valid names are ls, read_file, write_file, edit_file, delete, glob, grep, and execute. Explicit lists must include read_file. The allowlist applies to the main agent and synchronous subagents in every session mode, but not to async subagents or non-filesystem tools.

dcode -n "Fix the failing tests" --allow-fs-tools execute -S "pytest,git,make"

Run /tools in a session to inspect the active tool set. From the shell, place tool-shaping flags before the subcommand:

dcode tools list
dcode --allow-fs-tools ls,read_file tools list
dcode --allow-fs-tools ls,read_file tools list --json

Diagnose and audit a session

dcode exposes read-only slash commands for inspecting what a session loads and spends: /tools lists the active tool set, /extensions lists loaded Python extension registrations, /context-doctor audits the context injected before the conversation starts, and /cost reports the thread's estimated spend. Use them to confirm that a tool-shaping flag took effect or to find the source of unexpected context growth.

List loaded Python extensions

Run /extensions in a session to list each extension registration with its kind, name, scope, and source path. The report also shows load failures and whether graph-bound changes require /restart. This command and Python extension loading require DEEPAGENTS_CODE_EXPERIMENTAL=1. See Python extensions.

List available tools

Run /tools in a session to list the tools the current agent can call, grouped into built-in tools and tools from each MCP server:

/tools

**7 tools available**

### Built-in

| Tool | Description |
|---|---|
| read_file | Read a file from the filesystem |
| write_file | Write content to a file |
| execute | Run a shell command |
| web_search | Search the web |
| task | Launch a subagent |

### github

- create_issue
- search_repositories

MCP tool descriptions are available in /mcp.

### Unavailable MCP servers

| Server | Status |
|---|---|
| slack | needs login |

Unavailable MCP servers appear in a separate table. Run /reload after changing MCP configuration, then use /tools to verify the active tool set. For the non-interactive equivalent, see dcode tools list.

Audit injected context

Run /context-doctor in a session to audit what the session injects into every model request and its estimated token cost. The report breaks the injected context into the base system prompt, AGENTS.md memory files, the skills index, built-in tool schemas, and each MCP server's tool schemas, then totals what the agent carries before the conversation starts:

/context-doctor

Fresh-session context audit (estimated tokens)

System prompt (base)                      ~6
AGENTS.md memory (1 files)            ~1,286
Skills index (1 loaded)                 ~477  largest: code-review ~15
Built-in tool schemas (1 tools)          ~13  sent with every request
MCP: docs (1 tool)                       ~31
MCP: broken                               ~0  connection failed
TOTAL injected before conversation  ~     1,813
Conversation history             ~     4,200
Provider-reported context              9,000
Unattributed / estimation delta       +2,987

Approximate: section counts use about four characters per token.
Trim skills or disable an MCP server, then run /context-doctor again.

A large unattributed delta or injected total points to context you may want to trim. After changing skills or MCP configuration, run /context-doctor again to confirm.

/context-doctor complements two related commands:

• /context shows how full the context window is right now; /context-doctor shows why, by attributing tokens to each injected component.
• dcode doctor checks the health of the installation and configuration without launching a session; /context-doctor audits the context of a live session from inside it.

Track thread cost

Run /cost in a session to show the thread's estimated cost in USD:

/cost

Estimated thread cost: $1.03

By type since this thread was loaded:
- Assistant: $0.87
- Subagents: $0.16

By model since this thread was loaded:
- anthropic:claude-sonnet-4-5: $1.03

The total includes model calls from the assistant, subagents, offloading, Auto classification, and rubric grading. It persists when you resume or switch threads. Estimates use the genai-prices catalog; requests without pricing are excluded.

Use /tokens for the token counts behind the estimate. For uncovered models, add a custom pricing override.

Ask a side question

/btw lets you ask a question about the conversation while the agent keeps working. Type /btw <question>, or enter /btw to open a question field. The answer appears in a temporary dialog, not in the main conversation. Press Esc to dismiss it.

Startup commands and initial prompts

Use -m/--message to auto-submit an initial prompt when an interactive session starts. Combine with --startup-cmd to run a shell command first:

dcode --startup-cmd "git diff --stat" -m "Summarize these changes"

--startup-cmd 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 via stdin instead:

git diff | dcode -n "Review these changes"

Non-zero exits and timeouts from --startup-cmd warn but do not abort the session. Non-interactive mode applies a 60-second timeout to the startup command.

Remote sandboxes

Route code execution to a remote sandbox with --sandbox. Built-in providers include langsmith, agentcore, daytona, modal, runloop, and vercel. Third-party and config-declared providers are also accepted. Pass --sandbox with no value to use [sandboxes].default from config.toml:

dcode --sandbox langsmith
dcode --sandbox runloop --sandbox-id dbx_abc123
dcode --sandbox modal --sandbox-setup ./setup.sh
dcode --sandbox

Install sandbox extras with dcode --install (for example, dcode --install daytona or dcode --install all-sandboxes). See Remote sandboxes for provider setup, working directories, and third-party providers.

MCP flags

Control MCP server loading at launch:

--mcp-config and --no-mcp are mutually exclusive. In non-interactive mode, project servers without a matching saved or environment approval are silently skipped unless --trust-project-mcp is passed:

dcode --trust-project-mcp
dcode -n "run tests" --trust-project-mcp

Run OAuth login for an MCP server marked auth: "oauth" with dcode mcp login <server>. Run dcode mcp login without a server name to list configured OAuth servers that need login. See MCP tools.

Command-line options

Manage credentials (dcode auth)

The dcode auth command group is the scriptable equivalent of the /auth credential manager. It reads and writes the same auth.json store without launching the TUI:

# Pipe the key in (stdin)—never lands in shell history
echo "$ANTHROPIC_API_KEY" | dcode auth set anthropic

# Copy from an existing environment variable
dcode auth set openai --from-env OPENAI_API_KEY

# Inspect and remove
dcode auth list
dcode auth status openai
dcode auth remove anthropic
dcode auth path

set refuses to run in an interactive terminal unless you pipe the key via stdin or use --from-env. dcode auth set manages API keys only; the openai_codex provider uses ChatGPT browser sign-in via /auth instead. See Provider credentials.

Inspect configuration (dcode config)

The dcode config command group reports effective configuration without starting a session. Use it to confirm that an environment variable or config.toml setting is picked up, or to share a redacted snapshot in a bug report:

dcode config show
dcode config get interpreter.memory_limit_mb
dcode config list
dcode config path

Provider credentials are reported as configured or not configured only; values are not printed. All four commands accept --json. See Inspect configuration.

Run diagnostics (dcode doctor)

Use dcode doctor when Deep Agents Code is not starting correctly, a provider or MCP server does not connect, tracing is misconfigured, or an install or update looks wrong. It summarizes install method, dependency versions, update status, tracing configuration, and data directory health without launching a session.

Pair dcode doctor with dcode config show when you need both a high-level health check and the exact source of a specific setting. See Run diagnostics with dcode doctor.

CLI commands

All management subcommands support --json for machine-readable output. See command-line options for more information.

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.

See also

• Quickstart
• Configuration
• Config file
• Provider credentials
• MCP tools
• Python extensions