CLI reference

All commands support --help. Use that in place of re-reading this page.

Command tree

ao
├── start [project]             Start orchestrator + dashboard (auto-creates config on first run)
├── stop [project]              Stop orchestrator + dashboard
├── status                      Show all sessions with PR and CI status
├── spawn [issue]               Spawn a single agent session
├── batch-spawn <issues...>     Spawn sessions for multiple issues, with duplicate detection
├── send <session> [message…]   Send a message to a session with busy detection
├── review-check [project]      Check PRs for review comments and trigger agents
├── dashboard                   Start the web dashboard on its own
├── open [target]               Open session(s) in terminal tabs
├── verify [issue]              Mark an issue as verified (or failed) after staging check
├── doctor                      Run install, environment, and runtime health checks
├── update                      Check for updates and upgrade AO
├── init                        (deprecated — use ao start)
├── config-help                 Print the config schema and a guide
├── notify                      test
├── session                     ls, attach, kill, cleanup, restore, claim-pr, remap
├── setup                       dashboard, desktop, webhook, slack, discord, composio, openclaw
└── plugin                      list, search, create, install, update, uninstall

Core commands

ao start [project]

Start orchestrator agent and dashboard (auto-creates config on first run, adds projects by path/URL)

Positional [project] — project id, local path, or repo URL. If omitted and no config exists in cwd, AO creates agent-orchestrator.yaml.

If AO is already running, you'll get an interactive prompt to open/restart/spawn-new/quit. Non-TTY callers get info + process.exit(0).

ao stop [project]

Stop orchestrator agent and dashboard

ao status

Show all sessions with branch, activity, PR, and CI status

--watch and --json are mutually exclusive. Falls back to tmux session discovery if no config is found.

ao spawn [issue]

Spawn a single agent session

Positional [first] — issue identifier. The project is auto-detected from cwd.

ao batch-spawn <issues...>

Spawn sessions for multiple issues with duplicate detection

Skips duplicates within the batch and any issues that already have an active session.

ao send <session> [message...]

Send a message to a session with busy detection and retry

Positional: <session> required, [message...] variadic. One of inline message or --file is required. Long messages (>200 chars or multiline) go via tmux paste-buffer + temp file.

ao review-check [project]

Check PRs for review comments and trigger agents to address them

Checks all projects if [project] is omitted.

ao dashboard

Start the web dashboard

If the build looks stale you'll see a suggestion to run ao dashboard --rebuild.

ao open [target]

Open session(s) in terminal tabs

Positional [target] — session name, project id, or "all". Defaults to all sessions. Falls back to printing the dashboard URL when the native terminal helper isn't available (anywhere but macOS + iTerm2).

ao verify [issue]

Mark an issue as verified (or failed) after checking the fix on staging

[issue] is required unless --list is passed.

ao doctor

Run install, environment, and runtime health checks

Runs ao-doctor.sh for shell-level checks, then TypeScript checks (version freshness, plugin resolution, notifier connectivity). OpenClaw is the only notifier probed without side effects.

ao update

Check for updates and upgrade AO to the latest version

Behavior depends on how AO was installed — git, npm-global, pnpm-global, or unknown (manual instructions printed).

ao config-help

Show config schema and guide for creating agent-orchestrator.yaml

No flags.

Notify subcommands

ao notify test

Send a manual demo notification without spawning sessions

Session subcommands

ao session ls

List all sessions

ao session attach <session>

Attach to a session's tmux window

No flags. Attaches via tmux attach-session. Only meaningful with runtime: tmux.

ao session kill <session>

Kill a session and remove its worktree

ao session cleanup

Kill sessions where PR is merged or issue is closed

ao session claim-pr <pr> [session]

Attach an existing PR to a session

If [session] is omitted, falls back to AO_SESSION_NAME / AO_SESSION env vars.

ao session restore <session>

Restore a terminated or crashed session in-place

No flags. Relaunches the agent inside the same worktree and rewires session metadata.

ao session remap <session>

Re-discover and persist OpenCode session mapping for an AO session

Setup subcommands

Notifier setup commands that write AO config support --routing-preset <preset>. Valid presets are urgent-only, urgent-action, and all. In interactive mode, AO asks which notification priorities the notifier should receive before writing notificationRouting.

ao setup openclaw

Connect AO notifications to an OpenClaw gateway

Interactive mode (TTY) uses @clack/prompts with review/change steps for the gateway URL, OpenClaw config path, and routing preset. OpenClaw owns the token in hooks.token; AO does not generate it or write shell-profile exports.

Plugin subcommands

ao plugin list

List bundled marketplace plugins

ao plugin search <query>

Search the bundled marketplace catalog

No flags.

ao plugin create [directory]

Scaffold a new AO plugin package

ao plugin install <reference>

Install a plugin into the current config

<reference> is a marketplace id, npm package name, or local path.

ao plugin update [reference]

Update installer-managed plugins in the current config

Requires either [reference] or --all.

ao plugin uninstall <reference>

Remove a plugin from the current config

No flags.

Environment

A few env vars affect every command:

Agent-specific env vars are documented on each agent plugin's page.