CLI Commands
Complete reference for all CAO CLI commands.
Global Options
cao [command] --help # Show help for any command
cao --version # Show version
Entry Points
| Binary | Description |
|---|---|
cao | Main CLI |
cao-server | API server (default port 9889) |
cao-mcp-server | MCP server |
cao-ops-mcp-server | Ops MCP server |
Command Overview
| Command | Description |
|---|---|
cao launch | Launch a session with an agent profile |
cao session | Manage CAO sessions (list, status, send) |
cao shutdown | Shutdown sessions |
cao profile | Manage agent profiles (list, show, find, validate, remove, templates, create) |
cao schedule | Manage scheduled flows (add, list, remove, disable, enable, run) |
cao config | Configuration management |
cao init | Initialize CAO |
cao install | Install agent profiles |
cao env | Environment management |
cao mcp-server | Start MCP server inline |
cao info | Show system info |
cao memory | Memory management |
cao skills | Skills management |
cao terminal | Terminal management |
cao workflow | Workflow management |
cao update | Update CAO to the latest version |
cao fleet | Inspect and tear down a remote fleet's workers (status, shutdown) |
cao worker | Talk to one worker in a remote fleet (list, status, send, sessions, attach, logs, release) |
cao flow | [Deprecated] Alias for schedule |
Every command in this table acts on this machine — its cao-server, its config, or its sessions — except cao fleet and cao worker, which address a remote cluster through that cluster's worker broker. Those two are configured entirely by environment and never fall back to the local server.
cao launch
Launch a session with an agent profile. This is the primary command for starting agent work.
cao launch [MESSAGE] --agents PROFILE [OPTIONS]
Options
| Option | Description |
|---|---|
--agents TEXT | Agent profile to launch (required) |
--session-name TEXT | Name of the session (default: auto-generated) |
--headless | Launch in detached mode (no interactive terminal) |
--provider TEXT | Provider to use (default: profile provider or kiro_cli) |
--allowed-tools TEXT | Override allowedTools (repeatable) |
--async | Send message and return immediately |
--auto-approve | Skip confirmation prompt |
--yolo | [DANGEROUS] Unrestricted tool access |
--working-directory TEXT | Working directory (default: current directory) |
--memory | Also launch a memory_manager terminal |
--env KEY=VALUE | Forward environment variable to session (repeatable) |
Examples
# Launch with a profile and an initial message
cao launch "Fix the failing tests in src/" --agents code-reviewer
# Launch in headless (detached) mode
cao launch "Run the full test suite" --agents test-runner --headless
# Launch with a custom session name
cao launch "Deploy to staging" --agents deployer --session-name staging-deploy
# Launch with a specific provider
cao launch "Refactor the auth module" --agents refactorer --provider claude_code
# Launch with environment variables forwarded
cao launch "Build the project" --agents builder --env AWS_REGION=us-west-2 --env STAGE=beta
# Launch asynchronously (fire and forget)
cao launch "Generate weekly report" --agents reporter --async
# Launch with memory manager
cao launch "Research this codebase" --agents explorer --memory
cao session
Manage active CAO sessions.
:::note Session names include the cao- prefix
cao launch --session-name my-session creates a session named cao-my-session.
The subcommands below take the full prefixed name; cao session list shows the
exact values.
:::
cao session list
List all active sessions.
cao session list [--json]
| Option | Description |
|---|---|
--json | Output in JSON format |
cao session status
Show status of a specific session.
cao session status SESSION_NAME [--terminal ID] [--workers] [--json]
| Option | Description |
|---|---|
--terminal ID | Show status of a specific terminal within the session |
--workers | Include worker status |
--json | Output in JSON format |
cao session send
Send a message to a running session.
cao session send SESSION_NAME MESSAGE [--terminal ID] [--async] [--timeout N]
| Option | Description |
|---|---|
--terminal ID | Target a specific terminal within the session |
--async | Send and return immediately without waiting for response |
--timeout N | Timeout in seconds to wait for response |
Examples
# List all sessions
cao session list
# List sessions in JSON format
cao session list --json
# Check status of a session
cao session status cao-my-session
# Check status including workers
cao session status cao-my-session --workers
# Send a follow-up message to a session
cao session send cao-my-session "Now run the integration tests"
# Send a message to a specific terminal
cao session send cao-my-session "Check the logs" --terminal a1b2c3d4
# Send asynchronously
cao session send cao-my-session "Generate the report" --async
# Send with a timeout
cao session send cao-my-session "Run benchmarks" --timeout 300
cao shutdown
Shutdown one or all sessions.
cao shutdown --all
cao shutdown --session NAME
| Option | Description |
|---|---|
--all | Shutdown all active sessions |
--session NAME | Shutdown a specific session by name |
Examples
# Shutdown all sessions
cao shutdown --all
# Shutdown a specific session
cao shutdown --session cao-staging-deploy
cao profile
Manage agent profiles. Profiles define agent behavior, tools, and configuration.
cao profile list
List all installed profiles.
cao profile list
cao profile show
Display the full contents of a profile.
cao profile show NAME_OR_PATH
cao profile validate
Validate a profile for correctness.
cao profile validate NAME_OR_PATH
cao profile remove
Remove an installed profile.
cao profile remove NAME [-y]
| Option | Description |
|---|---|
-y | Skip confirmation prompt |
cao profile find
Search profiles by keyword.
cao profile find QUERY [--limit N] [--json]
| Option | Description |
|---|---|
--limit N | Maximum results to return (default: 10) |
--json | Output in JSON format |
cao profile templates
List available profile templates.
cao profile templates
cao profile create
Create a new profile from a template.
cao profile create --template NAME --config FILE [--output-dir DIR]
| Option | Description |
|---|---|
--template NAME | Template to base the profile on, namespaced e.g. aws/sqs-monitor (required). Run cao profile templates to list. |
--config FILE | Configuration file for profile creation (required) |
--output-dir DIR | Directory to write the profile to |
Examples
# List all installed profiles
cao profile list
# Show a profile's configuration
cao profile show code-reviewer
# Validate a profile file
cao profile validate ./my-profile.md
# List available templates
cao profile templates
# Create a new profile from a template
cao profile create --template aws/sqs-monitor --config ./my-config.json
# Create a profile with a custom output directory
cao profile create --template aws/stepfunction --config ./config.json --output-dir ./agents
# Remove a profile (with confirmation)
cao profile remove old-profile
# Remove a profile without confirmation
cao profile remove old-profile -y
cao schedule
Manage scheduled flows. Flows are automated sequences of agent operations that can run on a schedule.
cao schedule add
Add a new scheduled flow from a file.
cao schedule add FILE_PATH
cao schedule list
List all scheduled flows.
cao schedule list
cao schedule remove
Remove a scheduled flow.
cao schedule remove NAME
cao schedule disable
Disable a scheduled flow (keeps configuration but stops execution).
cao schedule disable NAME
cao schedule enable
Re-enable a disabled scheduled flow.
cao schedule enable NAME
cao schedule run
Manually trigger a scheduled flow.
cao schedule run NAME
Examples
# Add a new scheduled flow
cao schedule add ./flows/nightly-tests.md
# List all scheduled flows
cao schedule list
# Manually run a flow
cao schedule run nightly-tests
# Disable a flow temporarily
cao schedule disable nightly-tests
# Re-enable it
cao schedule enable nightly-tests
# Remove a flow entirely
cao schedule remove nightly-tests
cao config
Configuration management for CAO settings.
cao config
cao init
Initialize CAO in the current directory or environment.
cao init
cao install
Install an agent profile. AGENT_SOURCE is required and may be a built-in
profile name, a local .md path, or a URL on an allowlisted host
(github.com, raw.githubusercontent.com by default).
cao install AGENT_SOURCE [--provider PROVIDER] [--env KEY=VALUE]
| Option | Description |
|---|---|
--provider PROVIDER | Provider to install for. Precedence: this flag, then the profile's provider: frontmatter, then kiro_cli |
--env KEY=VALUE | Substitute a value into ${VAR} placeholders in the profile (repeatable) |
# Install a built-in profile
cao install code_supervisor
# Install from a local file
cao install ./my-agent.md
# Install for a specific provider
cao install developer --provider claude_code
cao update
Update CAO to the latest version. Automatically detects how CAO was installed (git, PyPI registry, or local) and runs the appropriate upgrade command.
cao update
Behavior by install method
| Install source | What cao update does |
|---|---|
PyPI (uv tool install cli-agent-orchestrator) | Runs uv tool upgrade cli-agent-orchestrator |
PyPI with version pin (==2.3.0, <3.0) | Runs uv tool install cli-agent-orchestrator@latest --upgrade (unpins) |
Git (uv tool install git+...) | Runs uv tool install <git-source> --upgrade --reinstall |
| Local directory / editable | Prints guidance (cannot auto-update a local install) |
After updating, restart any running cao-server to pick up the new version.
Examples
# Update CAO
cao update
# If installed from git, it will fetch the latest commits:
# $ uv tool install git+https://github.com/awslabs/cli-agent-orchestrator.git@main --upgrade --reinstall
cao env
Manage environment settings for CAO sessions.
cao env
cao mcp-server
Start an MCP server inline (within the current process).
cao mcp-server
cao info
Display information about the current CAO session (database path, active session context). For version info, use cao --version.
cao info
cao memory
Memory management for agent sessions.
cao memory
cao skills
Skills management for agent capabilities.
cao skills
cao terminal
Terminal management for multi-terminal sessions.
cao terminal
cao workflow
Workflow management for complex multi-step operations.
cao workflow
cao fleet
Inspect and tear down a CAO fleet's workers. A fleet is a cluster that runs one
agent per worker, each with its own cao-server; these commands reach it through
the fleet's worker broker over HTTP and know nothing about Kubernetes.
Both cao fleet and cao worker read the same two variables and take no other
configuration:
export CAO_ELASTIC_BROKER_URL=http://127.0.0.1:9890 # a port-forward is enough
export CAO_ELASTIC_BROKER_TOKEN=...
Without both, every subcommand exits with No fleet configured. — neither group
ever falls back to the cao-server on this machine. See
Environment Variables.
:::warning cao shutdown and cao fleet shutdown are different commands
cao shutdown stops tmux sessions on this machine. cao fleet shutdown
releases workers in a remote cluster, and the agent sessions inside them go
with the workers.
:::
cao fleet status
Summarise the fleet: whether the broker is reachable, and what it is holding.
cao fleet status [--json]
| Option | Description |
|---|---|
--json | Output in JSON format |
A settled count is not an error count. completed and released are the normal
end of a task; terminated, failed and expired are the three the broker
records a reason for, and cao worker list --all prints those reasons.
cao fleet shutdown
Release every live worker in the fleet.
cao fleet shutdown [--yes] [--json]
| Option | Description |
|---|---|
--yes, -y | Skip the confirmation prompt |
--json | Output in JSON format (requires --yes) |
This deletes the workers and their sessions; nothing is resumable afterwards. It does not touch the supervisor, the panel, or the cluster itself — those are deployed and removed by the cluster's own manifests, so this command cannot leave you without the fleet you would use to make new workers.
--json cannot ask for confirmation without corrupting its own output, so it
requires --yes; the two together are the only unattended form. The exit code is
non-zero if any worker could not be released, in both modes.
Examples
# Is the broker there, and what is it holding?
cao fleet status
# Release everything, interactively
cao fleet shutdown
# Release everything from a script, and fail the step if any worker survived
cao fleet shutdown --yes --json
cao worker
Inspect and talk to one worker in a remote fleet. These are cao session's verbs
pointed at a single worker, and they name no scheduler: a worker is addressed the
same way whatever the fleet runs it as. Configuration is the two variables under
cao fleet.
cao worker list
List the workers the broker knows about.
cao worker list [--all] [--json]
| Option | Description |
|---|---|
--all | Include settled leases and the reason each settled |
--json | Output in JSON format |
Settled leases are hidden by default and are the interesting rows when a delegation claimed success and produced nothing: the broker's ledger records why a worker is gone, which a deleted pod cannot answer and the supervisor's own transcript does not contain.
cao worker status
Show a worker's lease and what its agent is doing.
cao worker status WORKER_ID [--json]
| Option | Description |
|---|---|
--json | Output in JSON format |
Two sources, and both are needed: the lease says whether the cluster still considers the worker alive, the terminal says whether the agent inside it is working. They disagree in exactly the case worth catching — a Ready pod whose agent finished minutes ago without saying so.
cao worker send
Send a message to a worker's agent and print its reply.
cao worker send WORKER_ID MESSAGE [--async] [--timeout N]
| Option | Description |
|---|---|
--async | Send and return immediately, without waiting for the reply |
--timeout N | Seconds to wait for the agent to finish (default 300; ignored with --async) |
Done-detection is the same logic a local cao session send uses, with the status
read through the broker rather than re-implemented, so a worker running a provider
that idles mid-turn is not reported as hung.
cao worker sessions
List the sessions and terminals inside a worker.
cao worker sessions WORKER_ID [--json]
| Option | Description |
|---|---|
--json | Output in JSON format |
cao worker attach
Talk to a worker's agent turn by turn until you exit.
cao worker attach WORKER_ID
cao worker logs
Print a worker's container log — the smallest thing that makes a worker which
failed to boot diagnosable without handing the caller kubectl.
cao worker logs WORKER_ID [-n LINES] [-f]
| Option | Description |
|---|---|
-n, --tail LINES | Lines to show (default 200) |
-f, --follow | Stream new lines as they arrive |
cao worker release
Release one worker, deleting it and the session it was running.
cao worker release WORKER_ID
Examples
# What is live right now?
cao worker list
# Why did that worker disappear?
cao worker list --all
# Ask one worker a question and wait for its answer
cao worker send a1b2c3d4 "summarise what you changed"
# Fire and forget
cao worker send a1b2c3d4 "keep going" --async
# Follow a worker that never became ready
cao worker logs a1b2c3d4 -f
# Hand one worker back without touching the rest of the fleet
cao worker release a1b2c3d4
Providers
CAO supports multiple agent providers. Specify a provider with the --provider flag on cao launch.
| Provider | Description |
|---|---|
kiro_cli | Kiro CLI (default) |
claude_code | Claude Code |
codex | OpenAI Codex |
kimi_cli | Kimi CLI |
copilot_cli | GitHub Copilot CLI |
opencode_cli | OpenCode CLI |
omp | Oh My Pi |
hermes | Hermes |
cursor_cli | Cursor CLI |
antigravity_cli | Antigravity CLI |
Example
# Launch with Claude Code as the provider
cao launch "Analyze this codebase" --agents analyst --provider claude_code
# Launch with Codex
cao launch "Write unit tests" --agents test-writer --provider codex
Deprecated Commands
| Command | Replacement |
|---|---|
cao flow | Use cao schedule instead |