bkinnightskytw
/
agent-orchestrator
mirror of https://github.com/ComposioHQ/agent-orchestrator.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
agent-orchestrator/website/content/docs/cli.mdx

336 lines
12 KiB
Plaintext
Raw Permalink Blame History

---
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
├── 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`.
<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.
## 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](/docs/plugins/agents).
Reference in New Issue View Git Blame Copy Permalink