CLI reference

The ao CLI is a thin client for the local AO desktop app and its loopback daemon. Product commands require the desktop app to be running. Run ao <command> --help for the exact flags supported by your installed version.

Command tree

ao
├── start                         Open the desktop app (download it when needed)
├── stop                          Stop the local daemon
├── status                        Show daemon health
├── doctor                        Check the local AO environment
├── agent ls                      List built-in agent adapters and readiness
├── project                       add, ls, get, set-config, rm
├── spawn                         Create a worker or orchestrator session
├── session                       ls, get, kill, restore, rename, cleanup, claim-pr,
│                                 switch-agent, agent-switch
├── orchestrator ls               List orchestrator sessions
├── send                           Send a message to a session
├── pr                             merge, resolve-comments
├── review                         ls, trigger, cancel, submit
├── preview                        select/clear a target; start, status, stop a server
├── browser                        Control the selected session browser
├── import                         Import projects from legacy AO data
├── completion                     Generate shell completions
└── version                        Print build information

Internal commands such as daemon, hooks, launch, agent-process, and pty-host are intentionally omitted.

Desktop and daemon

ao start

Opens the installed Agent Orchestrator desktop app. If no app is installed, the legacy launcher can fetch the latest desktop release first. It does not supervise the daemon itself.

For a new installation, download the desktop app from the installation guide. The frozen npm package is a legacy launcher, not the current distribution channel.

ao stop

Asks the loopback daemon to shut down after checking that the run file identifies AO.

ao status

Reports daemon state, process identity, run-file location, health, and readiness. This command does not list sessions.

Use ao session ls for sessions.

ao doctor

Checks AO configuration, the data directory and database, daemon state, Git, GitHub authentication, and the platform runtime (tmux on macOS/Linux; ConPTY is built into Windows).

Projects and agents

ao agent ls

Lists the daemon's built-in agent catalog together with local installation and authentication readiness.

Agent adapters are compiled into AO. There is no plugin marketplace or ao plugin install command.

ao project

Project configuration is persisted by the daemon in SQLite. set-config supports common flags and --config-json; it does not edit agent-orchestrator.yaml. Use command help for the complete typed fields.

Sessions

ao spawn

Creates a session in a registered project. The command takes no positional arguments and requires a display name.

ao spawn --name fix-login --project my-app --agent codex --prompt "Fix the login regression"

Important flags include:

Project resolution order is explicit --project, AO_PROJECT_ID, the project of AO_SESSION_ID, then the closest registered project containing the current directory. Before spawning, AO refreshes the selected agent's advisory readiness unless --skip-agent-check is set.

ao session

Most lookup commands accept --project to disambiguate a session ID.

ao send

Sends a message through the daemon to a running session.

ao send --session ao-123 --message "Please address the failing test"

Both flags are required. When called from a session with AO_SESSION_ID, AO prefixes the sender identity.

ao orchestrator ls

Lists orchestrator sessions. Add --json for structured output.

Pull requests and reviews

Use each subcommand's help for required review-run IDs, verdict values, and file/stdin inputs.

Preview and browser control

ao preview [url]

Selects what the desktop Browser panel displays for the session identified by AO_SESSION_ID. With no argument AO looks for a supported static entry point in the session workspace; with a file or file:, http:, or https: target it opens that target.

.ao/launch.json is optional project configuration. AO does not infer or scaffold development servers, and static files do not require one.

ao browser

Controls the live, session-isolated Electron browser owned by the desktop app. It also resolves its target from AO_SESSION_ID; the desktop app must be open.

The command family includes status/open, accessibility snapshots and references, click/drag/fill/type/press/hover, highlight, scroll, select/check state, property reads, tabs and popups, DevTools, frames, dialogs, waits, screenshots, console/page errors, and bounded opt-in network metadata capture.

References become stale after navigation, DOM replacement, frame changes, or tab changes. Take another snapshot when AO reports STALE_REFERENCE. Network capture is off by default, metadata-only, bounded, and automatically expires.

Migration and shell integration

Environment

All current AO application state stays under ~/.ao unless AO_DATA_DIR or AO_RUN_FILE overrides it.