---
title: CLI reference
description: Every `ao` command, every flag, drawn from the source.
---

import { Callout } from "fumadocs-ui/components/callout";

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)

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

<Callout type="warn">
	The old two-arg form `ao spawn &lt;project&gt; &lt;issue&gt;` is rejected with an error. Use `-p` or run from inside a
	worktree.
</Callout>

### `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.

## Notify subcommands

### `ao notify test`

> Send a manual demo notification without spawning sessions

| Flag                 | Default | Purpose                                                       |
| -------------------- | ------- | ------------------------------------------------------------- |
| `--template <name>`  | `basic` | Demo template to send                                         |
| `--to <refs>`        | —       | Comma-separated notifier refs to target                       |
| `--all`              | —       | Send to all configured, default, and routed notifier refs     |
| `--route <priority>` | —       | Send through `urgent`, `action`, `warning`, or `info` routing |
| `--actions`          | —       | Include demo actions when supported                           |
| `--message <text>`   | —       | Override the notification message                             |
| `--dry-run`          | —       | Resolve targets without sending                               |
| `--json`             | —       | Print structured JSON output                                  |
| `--sink [port]`      | —       | Add a local webhook target named `sink`                       |

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

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

| Command                         | Purpose                                                |
| ------------------------------- | ------------------------------------------------------ |
| `ao setup dashboard`            | Configure dashboard notification retention and routing |
| `ao setup desktop`              | Configure native desktop notifications                 |
| `ao setup webhook`              | Configure a generic HTTP webhook                       |
| `ao setup slack`                | Configure a Slack incoming webhook                     |
| `ao setup discord`              | Configure a Discord incoming webhook                   |
| `ao setup composio`             | Open the interactive Composio setup hub                |
| `ao setup composio-slack`       | Configure Slack through Composio                       |
| `ao setup composio-discord`     | Configure Discord webhook mode through Composio        |
| `ao setup composio-discord-bot` | Configure Discord bot mode through Composio            |
| `ao setup composio-mail`        | Configure Gmail through Composio                       |
| `ao setup openclaw`             | Configure OpenClaw gateway notifications               |

### `ao setup openclaw`

> Connect AO notifications to an OpenClaw gateway

| Flag                            | Default                     | Purpose                                                                            |
| ------------------------------- | --------------------------- | ---------------------------------------------------------------------------------- |
| `--url <url>`                   | —                           | OpenClaw webhook URL                                                               |
| `--token <token>`               | —                           | Remote/manual fallback; local setup should read `hooks.token` from OpenClaw config |
| `--openclaw-config-path <path>` | `~/.openclaw/openclaw.json` | OpenClaw config path that contains `hooks.token`                                   |
| `--routing-preset <preset>`     | —                           | `urgent-only` · `urgent-action` · `all`                                            |
| `--refresh`                     | —                           | Reuse existing values and rewrite AO config                                        |
| `--no-test`                     | —                           | Skip the setup token probe                                                         |
| `--force`                       | —                           | Replace a conflicting `notifiers.openclaw` entry                                   |
| `--status`                      | —                           | Show OpenClaw config, gateway state, and token probe status                        |
| `--non-interactive`             | —                           | Skip prompts — auto-detect OpenClaw on localhost                                   |

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

| 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>`               | —                           | Remote/manual OpenClaw token fallback                             |
| `--openclaw-config-path <path>` | `~/.openclaw/openclaw.json` | OpenClaw config path that contains `hooks.token`                  |

`<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 `~/.ao` 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](/docs/plugins/agents).
