Command reference

Deep Agents Code command-line flags and management subcommands

Deep Agents Code (dcode) accepts command-line flags at launch and exposes management subcommands for 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 (Vertex AI).

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.

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.5-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").

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.

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

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

-S all lets the agent execute arbitrary shell commands with no human confirmation.

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. Skip prompts for a session with -y/--auto-approve, or toggle auto-approve with Shift+Tab during an interactive session:

dcode -y

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.

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

Because --sandbox accepts an optional value, keep the bare form last on the command line. Otherwise a following argument (for example, dcode --sandbox agents) is consumed as the flag’s value.

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:

Flag	Behavior
--mcp-config PATH	Add an explicit config as the highest-precedence source (merged on top of auto-discovered configs)
--no-mcp	Disable MCP entirely
--trust-project-mcp	Trust project-level stdio servers without prompting (for CI and automation)

--mcp-config and --no-mcp are mutually exclusive. In non-interactive mode, project-level stdio servers are silently skipped unless --trust-project-mcp is passed:

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

Run OAuth login for MCP servers marked auth: "oauth" with dcode mcp login <server>. See MCP tools.

Command-line options

Option	Description
-a, --agent NAME	Use named agent with separate memory. Overrides [agents].recent and [agents].default 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}')
--max-retries N	Override the max retries for transient model errors
--default-model [MODEL]	Set the default model (omit MODEL to view the current default)
--clear-default-model	Clear the default model
-r, --resume [ID]	Resume a session: -r for most recent, -r <ID> 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. To hand command output to the agent, pipe it in via stdin instead (e.g., git diff | dcode -n "Review these changes"). Non-zero exits and timeouts warn but do not abort; non-interactive mode applies a 60s timeout.
--rubric TEXT|@PATH	Acceptance criteria for rubric grading. Accepts literal text or @path to read a file. Requires -n or piped stdin
--rubric-model MODEL	Model the rubric grader uses. Defaults to the main agent model. Requires -n or piped stdin
--rubric-max-iterations N	Grader iterations per rubric attempt before stopping. Requires -n or piped stdin
-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 Non-interactive mode and piping
--timeout SECONDS	Hard wall-clock timeout for non-interactive mode. Exits with code 124 when exceeded. Requires -n or piped stdin. See 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, daytona, modal, runloop, vercel, and third-party providers. LangSmith is included; other built-ins require extras. Pass --sandbox with no value to use [sandboxes].default from config
--sandbox-id ID	Reuse an existing sandbox (skips creation and cleanup)
--sandbox-snapshot-name NAME	Sandbox snapshot name to use or create (langsmith, runloop, and providers that advertise snapshot support)
--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)
--interpreter	Enable the JS interpreter (js_eval) middleware on the main agent when it has been disabled in config. js_eval is enabled by default.
--interpreter-tools VALUE	PTC allowlist for js_eval: safe, all, or a comma-separated list of tool names. Default: no PTC (pure REPL)
--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
--update	Check for and install updates, then exit
--auto-update	Toggle automatic updates on or off, then exit
--install NAME	Install an optional extra (e.g., quickjs, daytona, fireworks), then exit. Add --package to treat NAME as a custom provider package installed via uv --with rather than an extra (see arbitrary providers), and --yes to skip confirmation prompts
-v, --version	Display version
-h, --help	Show help

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

Command	Description
dcode help	Show help
dcode agents list	List all agents (alias: ls)
dcode agents reset --agent NAME	Clear agent memory and reset to default. Supports --dry-run
dcode agents reset --agent NAME --target SOURCE	Copy memory from another agent
dcode update	Check for and install Deep Agents Code updates
dcode doctor	Run diagnostics without launching a session
dcode skills list [--project]	List all skills (alias: ls)
dcode 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
dcode skills info NAME [--project]	Show detailed information about a skill
dcode skills delete NAME [--project] [-f]	Delete a skill and its contents. Supports --dry-run
dcode 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), --cwd [PATH] (filter by working directory; bare flag uses current directory), -v/--verbose (show all columns including branch, created time, and initial prompt), -r/--relative (relative timestamps)
dcode threads delete ID	Delete a session. Supports --dry-run
dcode mcp login NAME [--mcp-config PATH]	Run the OAuth login flow for an MCP server marked auth: "oauth". See MCP tools
dcode mcp config	Show MCP config discovery paths
dcode config show	Show every config option’s effective value and the source it resolves from. See Inspect configuration
dcode config list	List all available config options with their type, default, and where each can be set (alias: ls)
dcode config get KEY	Show the effective value and source for one option (e.g. interpreter.memory_limit_mb)
dcode config path	Show config file locations and whether each exists
dcode auth list	List known providers and where each credential resolves from
dcode auth status <provider>	Show the credential source for one provider
dcode auth set <provider>	Store a provider credential from stdin or --from-env
dcode auth remove <provider>	Remove a stored provider credential
dcode auth path	Show the credential store path

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

---

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.