CLI reference

Command-line interface for running, managing, and deploying AI agents.

For agent configuration file syntax, see the Configuration file reference. For toolset capabilities, see the Toolsets reference.

Synopsis

$ docker agent [command] [flags]

Global flags

Work with all commands:

Debug logs write to ~/.cagent/cagent.debug.log by default. Override with --log-file.

Runtime flags

Work with most commands. Supported commands link to this section.

Set --models-gateway via CAGENT_MODELS_GATEWAY environment variable.

Commands

a2a

Expose agent via the Agent2Agent (A2A) protocol. Allows other A2A-compatible systems to discover and interact with your agent. Auto-selects an available port if not specified.

$ docker agent serve a2a agent-file|registry-ref

Note

A2A support is currently experimental and needs further work. Tool calls are handled internally and not exposed as separate ADK events. Some ADK features are not yet integrated.

Arguments:

• agent-file|registry-ref - Path to YAML or OCI registry reference (required)

Flags:

Supports runtime flags.

Examples:

$ docker agent serve a2a ./agent.yaml --port 8080
$ docker agent serve a2a agentcatalog/pirate --port 9000

acp

Start agent as ACP (Agent Client Protocol) server on stdio for editor integration. See ACP integration for setup guides.

$ docker agent serve acp agent-file|registry-ref

Arguments:

• agent-file|registry-ref - Path to YAML or OCI registry reference (required)

Supports runtime flags.

alias add

Create alias for agent.

$ docker agent alias add name target

Arguments:

• name - Alias name (required)
• target - Path to YAML or registry reference (required)

Examples:

$ docker agent alias add dev ./dev-agent.yaml
$ docker agent alias add prod docker.io/user/prod-agent:latest
$ docker agent alias add default ./agent.yaml

Setting alias name to "default" lets you run docker agent run without arguments.

alias list

List all aliases.

$ docker agent alias list
$ docker agent alias ls

alias remove

Remove alias.

$ docker agent alias remove name
$ docker agent alias rm name

Arguments:

• name - Alias name (required)

api

HTTP API server.

$ docker agent serve api agent-file|agents-dir

Arguments:

• agent-file|agents-dir - Path to YAML or directory with agents (required)

Flags:

Supports runtime flags.

Examples:

$ docker agent serve api ./agent.yaml
$ docker agent serve api ./agents/ --listen :9000
$ docker agent serve api docker.io/user/agent --pull-interval 10

The --pull-interval flag works only with OCI references. Automatically pulls and reloads at the specified interval.

build

Build Docker image for agent.

$ docker agent build agent-file|registry-ref [image-name]

Arguments:

• agent-file|registry-ref - Path to YAML or OCI registry reference (required)
• image-name - Docker image name (optional)

Flags:

Example:

$ docker agent build ./agent.yaml myagent:latest
$ docker agent build ./agent.yaml --dry-run

catalog list

List catalog agents.

$ docker agent catalog list [org]

Arguments:

• org - Organization name (optional, default: agentcatalog)

Queries Docker Hub for agent repositories.

debug config

Show resolved agent configuration.

$ docker agent debug config agent-file|registry-ref

Arguments:

• agent-file|registry-ref - Path to YAML or OCI registry reference (required)

Supports runtime flags.

Shows canonical configuration in YAML after all processing and defaults.

debug toolsets

List agent tools.

$ docker agent debug toolsets agent-file|registry-ref

Arguments:

• agent-file|registry-ref - Path to YAML or OCI registry reference (required)

Supports runtime flags.

Lists all tools for each agent in the configuration.

eval

Run evaluation tests.

$ docker agent eval agent-file|registry-ref [eval-dir]

Arguments:

• agent-file|registry-ref - Path to YAML or OCI registry reference (required)
• eval-dir - Evaluation files directory (optional, default: ./evals)

Supports runtime flags.

exec

Single message execution without TUI.

$ docker agent exec agent-file|registry-ref [message|-]

Arguments:

• agent-file|registry-ref - Path to YAML or OCI registry reference (required)
• message - Prompt, or - for stdin (optional)

Same flags as run.

Supports runtime flags.

Examples:

$ docker agent exec ./agent.yaml
$ docker agent exec ./agent.yaml "Check for security issues"
$ echo "Instructions" | docker agent exec ./agent.yaml -

feedback

Submit feedback.

$ docker agent feedback

Shows link to submit feedback.

mcp

MCP (Model Context Protocol) server on stdio. Exposes agents as tools to MCP clients. See MCP integration for setup guides.

$ docker agent serve mcp agent-file|registry-ref

Arguments:

• agent-file|registry-ref - Path to YAML or OCI registry reference (required)

Supports runtime flags.

Examples:

$ docker agent serve mcp ./agent.yaml
$ docker agent serve mcp docker.io/user/agent:latest

new

Create agent configuration interactively.

$ docker agent new [message...]

Flags:

Supports runtime flags.

Opens interactive TUI to configure and generate agent YAML.

pull

Pull agent from OCI registry.

$ docker agent pull registry-ref

Arguments:

• registry-ref - OCI registry reference (required)

Flags:

Example:

$ docker agent pull docker.io/user/agent:latest

Saves to local YAML file.

push

Push agent to OCI registry.

$ docker agent push agent-file registry-ref

Arguments:

• agent-file - Path to local YAML (required)
• registry-ref - OCI reference like docker.io/user/agent:latest (required)

Example:

$ docker agent push ./agent.yaml docker.io/myuser/myagent:latest

run

Interactive terminal UI for agent sessions.

$ docker agent run [agent-file|registry-ref] [message|-]

Arguments:

• agent-file|registry-ref - Path to YAML or OCI registry reference (optional)
• message - Initial prompt, or - for stdin (optional)

Flags:

Supports runtime flags.

Examples:

$ docker agent run ./agent.yaml
$ docker agent run ./agent.yaml "Analyze this codebase"
$ docker agent run ./agent.yaml --agent researcher
$ echo "Instructions" | docker agent run ./agent.yaml -
$ docker agent run

Running without arguments uses the default agent or a "default" alias if configured.

Shows interactive TUI in a terminal. Falls back to exec mode otherwise.

Interactive commands

TUI slash commands:

version

Print version information.

$ docker agent version

Shows Docker Agent version and commit hash.

Environment variables

Model overrides

Override models specified in your configuration file using the --model flag.

Format: [agent=]provider/model

Without an agent name, the model applies to all agents. With an agent name, it applies only to that specific agent.

Apply to all agents:

$ docker agent run ./agent.yaml --model gpt-5
$ docker agent run ./agent.yaml --model anthropic/claude-sonnet-4-5

Apply to specific agents only:

$ docker agent run ./agent.yaml --model researcher=gpt-5
$ docker agent run ./agent.yaml --model "agent1=gpt-5,agent2=claude-sonnet-4-5"

Providers: openai, anthropic, google, dmr

Omit provider for automatic selection based on model name.