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
├── session                     ls, attach, kill, cleanup, restore, claim-pr, remap
├── setup                       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)

Flag	Default	Purpose
`--no-dashboard`	—	Skip starting the dashboard server
`--no-orchestrator`	—	Skip starting the orchestrator agent
`--rebuild`	—	Clean and rebuild the dashboard before starting
`--dev`	—	Use Next.js dev server with hot reload (monorepo only; ignored in npm installs)
`--interactive`	—	Prompt to configure config settings

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

Flag	Default	Purpose
`--purge-session`	—	Delete the mapped OpenCode session when stopping
`--all`	—	Stop all running AO instances on this machine

`ao status`

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

Flag	Default	Purpose
`-p, --project <id>`	—	Filter to one project
`--json`	—	Output JSON
`-w, --watch`	—	Refresh continuously
`--interval <seconds>`	`5`	Refresh interval

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

Flag	Default	Purpose
`--open`	—	Open the session in a terminal tab
`--agent <name>`	config default	Override the agent plugin (`claude-code`, `codex`, `cursor`, `aider`, `opencode`)
`--claim-pr <pr>`	—	Immediately claim an existing PR for the spawned session
`--assign-on-github`	—	Assign the claimed PR to the authenticated GitHub user
`--prompt <text>`	—	Use an inline prompt instead of an issue (max 4096 chars, newlines stripped)

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

The old two-arg form ao spawn <project> <issue> is rejected with an error. Use -p or run from inside a worktree.

`ao batch-spawn <issues...>`

Spawn sessions for multiple issues with duplicate detection

Flag	Default	Purpose
`--open`	—	Open sessions in terminal tabs

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

Flag	Default	Purpose
`-f, --file <path>`	—	Send contents of a file instead of an inline message
`--no-wait`	—	Don't wait for the session to become idle before sending
`--timeout <seconds>`	`600`	Max seconds to wait for idle

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

Flag	Default	Purpose
`--dry-run`	—	Show what would happen; don't nudge agents

Checks all projects if [project] is omitted.

`ao dashboard`

Start the web dashboard

Flag	Default	Purpose
`-p, --port <port>`	config `port` or `3000`	Port to listen on
`--no-open`	—	Don't open the browser
`--rebuild`	—	Clean stale Next.js artifacts and rebuild

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

`ao open [target]`

Open session(s) in terminal tabs

Flag	Default	Purpose
`-w, --new-window`	—	Open in a new terminal window instead of a tab

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

Flag	Default	Purpose
`-p, --project <id>`	—	Required if multiple projects
`--fail`	—	Mark as failed instead of passing
`-c, --comment <msg>`	—	Custom comment to add
`-l, --list`	—	List all issues with the merged-unverified label

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

`ao doctor`

Run install, environment, and runtime health checks

Flag	Default	Purpose
`--fix`	—	Apply safe fixes for launcher and stale-temp issues
`--test-notify`	—	Send a test notification through each configured notifier

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

Flag	Default	Purpose
`--skip-smoke`	—	Skip smoke tests after rebuilding (git installs only)
`--smoke-only`	—	Run smoke tests without fetching or rebuilding (git installs only)
`--check`	—	Print version info as JSON; don't upgrade

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.

`ao init` (deprecated)

Use ao start instead — it auto-creates config on first run.

Runs the same config-only bootstrap; kept for backward compatibility.

Session subcommands

`ao session ls`

List all sessions

Flag	Default	Purpose
`-p, --project <id>`	—	Filter to one project
`-a, --all`	—	Include orchestrator sessions
`--json`	—	Output JSON

`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

Flag	Default	Purpose
`--purge-session`	—	Delete the mapped OpenCode session

`ao session cleanup`

Kill sessions where PR is merged or issue is closed

Flag	Default	Purpose
`-p, --project <id>`	—	Filter to one project
`--dry-run`	—	Show what would be cleaned up

`ao session claim-pr <pr> [session]`

Attach an existing PR to a session

Flag	Default	Purpose
`--assign-on-github`	—	Assign the PR to the authenticated user on GitHub

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

Flag	Default	Purpose
`-f, --force`	—	Override a stale mapping

Setup subcommands

`ao setup openclaw`

Connect AO notifications to an OpenClaw gateway

Flag	Default	Purpose
`--url <url>`	—	OpenClaw webhook URL
`--token <token>`	—	OpenClaw hooks auth token
`--routing-preset <preset>`	—	`urgent-only` · `urgent-action` · `all`
`--non-interactive`	—	Skip prompts — auto-detect OpenClaw on localhost

Interactive mode (TTY) uses @clack/prompts. Writes to agent-orchestrator.yaml, ~/.openclaw/openclaw.json, and your shell profile. The token lands in YAML as ${OPENCLAW_HOOKS_TOKEN} — never committed raw.

Plugin subcommands

`ao plugin list`

List bundled marketplace plugins

Flag	Default	Purpose
`--installed`	—	Only show plugins present in your current config
`--type <slot>`	—	Filter by slot: `agent`, `runtime`, `tracker`, `scm`, `notifier`, `workspace`, `terminal`
`--refresh`	—	Re-fetch the marketplace catalog

`ao plugin search <query>`

Search the bundled marketplace catalog

No flags.

`ao plugin create [directory]`

Scaffold a new AO plugin package

Flag	Default	Purpose
`--name <name>`	prompt	Plugin name
`--slot <slot>`	prompt	Which slot it implements
`--description <text>`	prompt	Manifest description
`--author <name>`	prompt	Package author
`--package-name <name>`	derived	npm package name
`--non-interactive`	—	Use all flags without prompting

`ao plugin install <reference>`

Install a plugin into the current config

Flag	Default	Purpose
`--url <url>`	—	Passed to `ao setup openclaw` when installing `notifier-openclaw`
`--token <token>`	—	Same — passed through for the openclaw handshake

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

`ao plugin update [reference]`

Update installer-managed plugins in the current config

Flag	Default	Purpose
`--all`	—	Update all managed plugins

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:

Variable	Purpose
`AO_DATA_DIR`	Override the `~/.agent-orchestrator` base directory.
`AO_LOG_LEVEL`	`error` · `warn` · `info` · `debug` · `trace`
`AO_CONFIG_PATH`	Absolute path to a specific `agent-orchestrator.yaml`. Overrides CWD-based search.
`AO_SESSION_ID` · `AO_SESSION_NAME`	Auto-set inside spawned sessions; used by `claim-pr` default
`AO_PROJECT_ID`	Set by AO inside spawned sessions. Used by `ao spawn` to resolve the active project.
`PORT`	Next.js dashboard port. Overrides `config.port`.
`TERMINAL_PORT`	WebSocket mux server port (default 14800).
`DIRECT_TERMINAL_PORT`	Direct PTY WebSocket port (default 14801).
`NEXT_PUBLIC_TERMINAL_WS_PATH`	Override the WebSocket path used by the terminal client (for reverse-proxy setups).

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

CLI reference

On this page