agent-orchestrator/docs/cli/README.md

AO CLI

The ao CLI is a thin Go/Cobra client for the local Agent Orchestrator daemon.
It starts, discovers, inspects, and stops the daemon through the loopback HTTP
surface and the running.json handshake. It must not open SQLite directly or
call runtime, workspace, tracker, or agent adapters in-process.

When using the CLI directly from a shell, make sure the daemon is running first
with ao start or by opening the desktop app. Product commands such as
ao agent ls and ao spawn call the loopback daemon and will fail with a
"daemon is not running" error if no running.json points at a live process. From
a source checkout, build and run the local binary explicitly, for example:

cd backend
go build -o ./bin/ao ./cmd/ao
./bin/ao agent ls

Current commands

Every product command resolves to a daemon HTTP route. Run ao <command> --help for the authoritative flag shape.

Daemon control

Command	Purpose
ao start	Start the daemon in the background and wait for /readyz.
ao stop	Gracefully stop the daemon via loopback POST /shutdown after verifying daemon identity.
ao status / --json	Report daemon state from running.json, process liveness, /healthz, and /readyz.
ao doctor / --json	Check config, data directory, DB-file presence, daemon state, git, and (on Darwin/Linux) tmux; on Windows conpty is built in.
ao completion <shell>	Generate completions for bash, zsh, fish, or powershell.
ao version / ao --version	Print build metadata.
ao daemon	Hidden internal daemon entrypoint used by ao start.

Product commands

Command	Daemon route
ao project add	POST /api/v1/projects
ao project ls	GET /api/v1/projects
ao project get <id>	GET /api/v1/projects/{id}
ao project set-config <id>	PUT /api/v1/projects/{id}/config
ao project rm <id>	DELETE /api/v1/projects/{id}
ao agent ls	GET /api/v1/agents
ao agent ls --refresh	POST /api/v1/agents/refresh
ao spawn	POST /api/v1/sessions
ao session ls	GET /api/v1/sessions
ao session get <id>	GET /api/v1/sessions/{id}
ao session kill <id>	POST /api/v1/sessions/{id}/kill
ao session restore <id>	POST /api/v1/sessions/{id}/restore
ao session rename <id> <name>	PATCH /api/v1/sessions/{id}
ao session cleanup	POST /api/v1/sessions/cleanup
ao session claim-pr <id> <pr-ref>	POST /api/v1/sessions/{id}/pr/claim
ao orchestrator ls	GET /api/v1/orchestrators
ao send	POST /api/v1/sessions/{id}/send
ao preview [url]	POST /api/v1/sessions/{id}/preview
ao hooks <agent> <event>	POST /api/v1/sessions/{id}/activity (hidden)

ao agent ls prints the daemon-supported agent catalog with local install/auth
readiness. Use --refresh to rerun the bounded local probes and --json to
print the raw inventory response.

ao spawn resolves project context in this order: explicit --project,
AO_PROJECT_ID, AO_SESSION_ID (by fetching the current session from the
daemon), then the current working directory matched against registered project
paths. If AO_SESSION_ID is set but the session cannot be fetched, pass
--project explicitly.

If --agent / --harness is omitted, ao spawn uses the resolved project's
worker.agent config. Before spawning, the CLI refreshes the advisory agent
catalog and fails early when the selected agent is unsupported, not installed,
or unauthorized. It warns-but-continues when auth remains unknown because daemon
spawn remains the authoritative runtime validation point. Use
--skip-agent-check to bypass only this CLI-side preflight.

ao preview resolves its session from the AO_SESSION_ID environment variable
(it is meant to run inside a session), not a flag. With no argument it
autodetects an index.html in the session workspace; with a URL argument it
opens that URL verbatim (file://, http, https).

go run . in backend/ remains a compatibility wrapper around the daemon.

PR and review actions (merge, resolve-comments, review execute/send) are
HTTP-only today and driven by the frontend; there are no ao pr / ao review
commands yet.

Configuration

The CLI and daemon share the same environment-driven config:

Var	Default	Purpose
AO_PORT	3001	Loopback daemon port.
AO_RUN_FILE	~/.ao/running.json	PID/port handshake.
AO_DATA_DIR	~/.ao/data	SQLite data directory.
AO_REQUEST_TIMEOUT	60s	REST request timeout.
AO_SHUTDOWN_TIMEOUT	10s	Graceful shutdown cap.

The daemon always binds 127.0.0.1.

Manual smoke test

cd backend
go build -o /tmp/ao ./cmd/ao

tmp=$(mktemp -d)
export AO_RUN_FILE="$tmp/running.json"
export AO_DATA_DIR="$tmp/data"
export AO_PORT=3037

/tmp/ao status --json
/tmp/ao doctor
/tmp/ao start
/tmp/ao status --json
/tmp/ao stop
/tmp/ao status --json
rm -rf "$tmp"

Adding new commands

Add a product command only when a daemon HTTP route owns the corresponding
mutation/read; the CLI must call that route rather than reimplementing daemon
behavior. Commands not yet exposed but with backend routes in place include
ao events ... (over the CDC/SSE endpoint) and CLI parity for PR/review
actions.

Do not port old in-process TypeScript CLI behavior that mixed command handling
with storage and runtime implementation details.