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
Global flags
Work with all commands:
| Flag | Type | Default | Description |
|---|---|---|---|
-d, --debug | boolean | false | Enable debug logging |
-o, --otel | boolean | false | Enable OpenTelemetry |
--log-file | string | - | Debug log file path |
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.
| Flag | Type | Default | Description |
|---|---|---|---|
--models-gateway | string | - | Models gateway address |
--env-from-file | array | - | Load environment variables from file |
--code-mode-tools | boolean | false | Enable JavaScript tool orchestration |
--working-dir | string | - | Working directory for the session |
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.
NoteA2A 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:
| Flag | Type | Default | Description |
|---|---|---|---|
-a, --agent | string | root | Agent name |
--port | integer | 0 | Port (0 = random) |
Supports runtime flags.
Examples:
acp
Start agent as ACP (Agent Client Protocol) server on stdio for editor integration. See ACP integration for setup guides.
Arguments:
agent-file|registry-ref- Path to YAML or OCI registry reference (required)
Supports runtime flags.
alias add
Create alias for agent.
Arguments:
name- Alias name (required)target- Path to YAML or registry reference (required)
Examples:
Setting alias name to "default" lets you run cagent run without arguments.
alias list
List all aliases.
alias remove
Remove alias.
Arguments:
name- Alias name (required)
api
HTTP API server.
Arguments:
agent-file|agents-dir- Path to YAML or directory with agents (required)
Flags:
| Flag | Type | Default | Description |
|---|---|---|---|
-l, --listen | string | :8080 | Listen address |
-s, --session-db | string | session.db | Session database path |
--pull-interval | integer | 0 | Auto-pull OCI ref every N minutes |
Supports runtime flags.
Examples:
The --pull-interval flag works only with OCI references. Automatically pulls and reloads at the specified interval.
build
Build Docker image for agent.
Arguments:
agent-file|registry-ref- Path to YAML or OCI registry reference (required)image-name- Docker image name (optional)
Flags:
| Flag | Type | Default | Description |
|---|---|---|---|
--dry-run | boolean | false | Print Dockerfile only |
--push | boolean | false | Push image after build |
--no-cache | boolean | false | Build without cache |
--pull | boolean | false | Pull all referenced images |
Example:
catalog list
List catalog agents.
Arguments:
org- Organization name (optional, default:agentcatalog)
Queries Docker Hub for agent repositories.
debug config
Show resolved agent configuration.
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.
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.
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.
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:
feedback
Submit 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.
Arguments:
agent-file|registry-ref- Path to YAML or OCI registry reference (required)
Supports runtime flags.
Examples:
new
Create agent configuration interactively.
Flags:
| Flag | Type | Default | Description |
|---|---|---|---|
--model | string | - | Model as provider/model |
--max-iterations | integer | 0 | Maximum agentic loop iterations |
Supports runtime flags.
Opens interactive TUI to configure and generate agent YAML.
pull
Pull agent from OCI registry.
Arguments:
registry-ref- OCI registry reference (required)
Flags:
| Flag | Type | Default | Description |
|---|---|---|---|
--force | boolean | false | Pull even if already exists |
Example:
Saves to local YAML file.
push
Push agent to OCI registry.
Arguments:
agent-file- Path to local YAML (required)registry-ref- OCI reference likedocker.io/user/agent:latest(required)
Example:
run
Interactive terminal UI for agent sessions.
Arguments:
agent-file|registry-ref- Path to YAML or OCI registry reference (optional)message- Initial prompt, or-for stdin (optional)
Flags:
| Flag | Type | Default | Description |
|---|---|---|---|
-a, --agent | string | root | Agent name |
--yolo | boolean | false | Auto-approve all tool calls |
--attach | string | - | Attach image file |
--model | array | - | Override model (repeatable) |
--dry-run | boolean | false | Initialize without executing |
--remote | string | - | Remote runtime address |
Supports runtime flags.
Examples:
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:
| Command | Description |
|---|---|
/exit | Exit |
/reset | Clear history |
/eval | Save conversation for evaluation |
/compact | Compact conversation |
/yolo | Toggle auto-approval |
version
Print version information.
Shows cagent version and commit hash.
Environment variables
| Variable | Description |
|---|---|
CAGENT_MODELS_GATEWAY | Models gateway address |
TELEMETRY_ENABLED | Telemetry control (set false) |
CAGENT_HIDE_TELEMETRY_BANNER | Hide telemetry banner (set 1) |
OTEL_EXPORTER_OTLP_ENDPOINT | OpenTelemetry endpoint |
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:
Apply to specific agents only:
Providers: openai, anthropic, google, dmr
Omit provider for automatic selection based on model name.
