cli

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.

Current commands

Command	Purpose
ao start	Start the daemon in the background and wait for /readyz.
ao status	Report daemon state from running.json, process liveness, /healthz, and /readyz.
ao status --json	Emit the same daemon state as machine-readable JSON.
ao stop	Gracefully stop the daemon via loopback POST /shutdown after verifying daemon identity.
ao doctor	Check config, data directory, DB-file presence, daemon state, git, and optional zellij.
ao doctor --json	Emit doctor checks as JSON.
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.

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

Configuration

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

Var	Default	Purpose
AO_PORT	3001	Loopback daemon port.
AO_RUN_FILE	<UserConfigDir>/agent-orchestrator/running.json	PID/port handshake.
AO_DATA_DIR	<UserConfigDir>/agent-orchestrator/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"

Product commands not present yet

The backend has project, session, lifecycle, terminal, and CDC building blocks, but the public CLI currently exposes only daemon-control commands. Add product commands only when a daemon HTTP route owns the corresponding mutation/read:

• ao project ... should call project HTTP routes.
• ao spawn, ao session ..., and ao send should call session/messaging HTTP routes.
• ao events ... should call CDC/event HTTP routes.

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