CLI reference

The ao CLI is a thin client for the local desktop app's daemon. Commands that operate on projects and sessions require the app and its daemon to be running. ao start opens or downloads the app, ao status inspects daemon state even when it is stopped, and ao doctor checks the local environment without requiring a running daemon. Run ao <command> --help to see 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 Orchestrator 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, delete,
│                                 claim-pr, exit-agent, resume-agent
├── automation                    create, list, get, update, delete, runs
├── cue                           create, list
├── report                        Report worker progress or artifacts
├── 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
├── remote-host                    status, enable, disable, link
├── import                         Import projects from legacy product data
├── completion                     Generate shell completions
└── version                        Print build information

This reference omits internal commands such as daemon, hooks, launch, agent-process, and pty-host. ao dev is a developer launcher; see the repository development guide for source builds.

Desktop and daemon

ao start

Opens the installed desktop app. If the app is missing, the legacy launcher can download the latest release first. The desktop app starts and supervises the daemon.

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 Orchestrator.

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 Orchestrator 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 Orchestrator. There is no plugin marketplace or ao plugin install command.

ao project

Focused set-config flags change only the fields they name and keep the rest of the saved config. --config-json replaces the entire project config, and its JSON decoder ignores unknown keys. See Projects: update from the CLI for safe alternatives and details. This command does not edit the old agent-orchestrator.yaml file.

Use ao automation create, list, get, update, delete, and runs to manage recurring work. To create one, provide a project, name, prompt, and exactly one schedule: --cron or --rrule. Set --timezone to an IANA time-zone name such as America/New_York. Pause a definition with ao automation update <id> --enabled=false. See schedule behavior.

ao cue create --project <id> --name <name> requires exactly one --command or --prompt. ao cue list --project <id> lists definitions. Editing, deleting, and invoking Cues is available in the desktop; the CLI does not have a cue run command.

Sessions

ao spawn

Creates a session in a registered project, or a projectless worker with --standalone. 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:

Orchestrator chooses a project in this order: --project, AO_PROJECT_ID, the project for AO_SESSION_ID, then the closest registered project containing the current directory. Before spawning, Orchestrator refreshes the selected agent's readiness unless you use --skip-agent-check. Readiness is advisory.

ao session

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

Claiming a PR records ownership and starts observation. It does not check out the PR branch, so prepare the right branch or worktree separately. Archive ends the session. Exit and resume stop or start only its controller. Closing a view does neither.

ao send

Sends a message through the daemon to a running session.

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

--session and --message are required for ordinary sends. When called from a session with AO_SESSION_ID, Orchestrator prefixes the sender identity.

Use --steer to steer an active supported Chat turn or submit a normal turn when idle. --client-message-id supplies a stable delivery handle. If delivery is uncertain, recover the recorded result without resending:

ao send --session <session-id> --steer --recover-only --client-message-id <handle>

--recover-only requires --steer and a handle; it does not require a new message or contact the provider. A receipt confirms acceptance state, not that the agent completed the instruction.

ao orchestrator ls

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

Inside a worker, ao report "Progress summary" sends a report to its existing orchestrator. Reporting requires AO_SESSION_ID; it does not create an orchestrator or claim a PR.

Needs-input reports are sent immediately. Stuck reports may interrupt or combine with other reports. Done reports wait five minutes before delivery; ordinary checkpoints can wait up to one hour.

For a structured report, choose one state flag: --checkpoint, --needs-input, --stuck, or --done. Include --note with it. Attach reviewable deliverables with --artifact, --pr-created, or --pr-reviewed; pull-request flags require full URLs. Do not combine free-form text with structured state or output flags.

ao report --done --note "Focused tests passed"

ao report must run in a worker environment that provides AO_SESSION_ID.

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 Orchestrator 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. Orchestrator 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.

Browser commands include status and open, page snapshots, click/drag/fill/type, scrolling, tabs and popups, DevTools, screenshots, console and page errors, and optional network metadata capture. Run ao browser --help for the full command list.

An element reference becomes stale when navigation or a frame or tab change replaces the page. Take a new snapshot when Orchestrator reports STALE_REFERENCE.

The first ao browser snapshot --delta returns the full page tree. Later calls return only changes; add --full to request the full tree again. The --annotate option on screenshots labels interactive elements with references.

click and drag accept --human for pages that ignore instant pointer movement. Keep the Browser panel visible when using --human or taking screenshots. Hidden or covered windows stop painting, so these commands time out.

Network capture is off by default. When enabled, it records bounded metadata only, excludes request and response bodies and sensitive values, and expires automatically.

Remote access

ao remote-host

Lets your other devices use this machine through its authenticated remote listener.

link is how a VM or other machine without the desktop app joins your account. See Connect a VM or other headless machine.

Migration and shell integration

Environment

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