id = "docker-agent"
name = "Docker Agent"
homepage = "https://docs.docker.com/ai/docker-agent/"
description = "Agent Builder and Runtime by Docker Engineering"
executables = ["docker-agent"]

[dotfiles]

# Docker Agent's official configuration reference identifies
# ~/.config/cagent/config.yaml as the user-wide configuration file for global
# permissions. Provider API keys are documented as environment variables, so
# this settings file is not itself secret.
# https://github.com/docker/docker-agent/blob/main/docs/configuration/overview/index.md
paths = ["[configHome]/cagent/config.yaml"]
secret = []

[commands]
format = 1
label = "Run an agent"
description = "Run a Docker Agent configuration interactively or headless. Sandbox, worktree, hook, remote and recording options are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = false, short_bundles = false }


[[commands.subcommand]]
path = ["run"]
label = "Run an agent"

[[commands.subcommand.source]]
id = "cli"
kind = "help"
url = "https://docker.github.io/docker-agent/features/cli/"
evidence = """
$ docker agent run [config] [message...] [flags]
-a, --agent <name>
Run a specific agent from the config
--yolo
Auto-approve tool calls (unless explicitly denied). Legacy alias for --safety autonomous.
--safety <mode>
Safety mode for tool approval: strict (ask for everything), balanced (auto-approve safe calls), restricted (auto-approve safe calls, deny the rest), or autonomous
--model <ref>
Override model(s). Use provider/model for all agents, or agent=provider/model for specific agents.
--session <id>
Resume a previous session. Supports relative refs (-1 = newest by creation time)
--prompt-file <path>
Include file contents as additional system context (repeatable)
--dry-run
Initialize the agent without executing anything (useful for validating a config)
--lean
Use a simplified, non-alternate-screen TUI.
--working-dir <path>
Set the working directory for the session (applies to tools and relative paths).
--json
Output results as newline-delimited JSON (use with --exec); with --last, output only the final answer as a JSON value
--last
Print only the final agent answer after all turns finish (requires --exec)
-d, --debug
Enable debug logging
docker agent run --exec [config] [message...] [flags]
$ docker agent run agent.yaml --model anthropic/claude-sonnet-4-5
"""

[[commands.subcommand.field]]
id = "config"
label = "Agent config"
description = "A .yaml, .yml or .hcl file; omit to use docker-agent.yaml in the current directory or the built-in agent."
type = "path"
position = 0
path = { kind = "file", role = "input" }
sources = ["cli"]

[[commands.subcommand.field]]
id = "messages"
label = "Messages"
description = "Queued in order; each is processed in sequence."
type = "string"
position = 1
multiple = true
sources = ["cli"]

[[commands.subcommand.field]]
id = "exec"
label = "Non-interactive (headless)"
type = "boolean"
option = ["--exec"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "agent"
label = "Agent name"
type = "string"
option = ["--agent", "-a"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "model"
label = "Model override"
description = "provider/model, or agent=provider/model."
type = "string"
option = ["--model"]
suggestions = [{ value = "anthropic/claude-sonnet-4-5", label = "Anthropic Claude Sonnet 4.5" }, { value = "openai/gpt-4o", label = "OpenAI GPT-4o" }]
sources = ["cli"]

[[commands.subcommand.field]]
id = "safety"
label = "Tool approval mode"
type = "enum"
option = ["--safety"]
choices = [{ value = "strict", label = "Strict (ask for everything)" }, { value = "balanced", label = "Balanced (auto-approve safe calls)" }, { value = "restricted", label = "Restricted (deny the rest)" }, { value = "autonomous", label = "Autonomous" }]
sources = ["cli"]

[[commands.subcommand.field]]
id = "yolo"
label = "Auto-approve tool calls"
type = "boolean"
option = ["--yolo"]
effect = "exec"
sources = ["cli"]

[[commands.subcommand.field]]
id = "session"
label = "Resume session"
description = "Session id or relative ref such as -1 for the newest."
type = "string"
option = ["--session"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "prompt_file"
label = "Extra context files"
type = "path"
option = ["--prompt-file"]
path = { kind = "file", role = "input" }
multiple = true
sources = ["cli"]

[[commands.subcommand.field]]
id = "working_dir"
label = "Working directory"
type = "path"
option = ["--working-dir"]
path = { kind = "directory", role = "input" }
sources = ["cli"]

[[commands.subcommand.field]]
id = "last"
label = "Only the final answer"
description = "Requires headless mode."
type = "boolean"
option = ["--last"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "json"
label = "JSON output"
type = "boolean"
option = ["--json"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "dry_run"
label = "Validate only"
type = "boolean"
option = ["--dry-run"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "lean"
label = "Lean inline TUI"
type = "boolean"
option = ["--lean"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "debug"
label = "Debug logging"
type = "boolean"
option = ["--debug", "-d"]
sources = ["cli"]

[[commands.subcommand.task]]
id = "interactive"
label = "Interactive session"
fields = ["config", "messages", "agent", "model"]
required = []

[[commands.subcommand.task]]
id = "oneshot"
label = "One-shot headless task"
fields = ["exec", "config", "messages", "last"]
required = ["config", "messages"]
set = { exec = [true] }

[[commands.subcommand.task]]
id = "validate"
label = "Validate a config"
fields = ["config", "dry_run"]
required = ["config"]
set = { dry_run = [true] }

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["config", "messages", "exec", "agent", "model", "safety"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["session", "prompt_file", "working_dir", "json", "dry_run", "lean", "debug", "yolo", "last"]