Skip to content

CLI.md

Latest commit

 

History

History
77 lines (59 loc) · 4.21 KB

CLI.md

File metadata and controls

77 lines (59 loc) · 4.21 KB

AO CLI Reference

The ao CLI is the control interface for Agent Orchestrator. Most commands are used by the orchestrator agent itself to manage sessions, not by humans directly. Humans typically only need ao start and the web dashboard.

Commands humans use

ao start                               # Auto-detect, generate config, start dashboard + orchestrator
ao start <url>                         # Clone repo, auto-configure, and start
ao start ~/other-repo                  # Add a new project and start
ao stop                                # Stop everything (dashboard, orchestrator, lifecycle worker)
ao status                              # Overview of all sessions
ao status --watch                      # Live-updating terminal status view
ao dashboard                           # Open web dashboard in browser
ao setup dashboard                     # Configure dashboard notification retention/routing
ao setup desktop                       # Install/configure native macOS desktop notifications
ao notify test --to desktop            # Send a manual notifier test without starting AO
ao completion zsh                      # Print the zsh completion script

Commands the orchestrator agent uses

These are primarily invoked by the orchestrator agent running inside a runtime session (a tmux window on macOS/Linux; a ConPTY pty-host on Windows). You can use them manually if needed, but the orchestrator handles this automatically.

ao spawn [issue]                       # Spawn an agent (project auto-detected from cwd)
ao spawn 123 --agent codex             # Override agent for this session
ao batch-spawn 101 102 103             # Spawn agents for multiple issues at once
ao send <session> "Fix the tests"      # Send instructions to a running agent
ao session ls                          # List active sessions (terminated hidden)
ao session ls --include-terminated     # Include killed/done/merged/errored/cleanup sessions
ao session ls --json                   # Machine-readable session inventory (see note below)
ao session kill <session>              # Kill a session
ao session restore <session>           # Revive a crashed agent

JSON output: ao session ls --json and ao status --json emit { "data": [...], "meta": { "hiddenTerminatedCount": N } }. Terminated sessions (killed, terminated, done, merged, errored, cleanup) are filtered from data by default; meta.hiddenTerminatedCount reports how many were dropped. Pass --include-terminated to include them and reset the count to 0.

Maintenance commands

ao doctor                              # Check install, runtime, and stale temp issues
ao doctor --fix                        # Apply safe fixes automatically
ao setup openclaw                      # Connect AO notifications to OpenClaw
ao update                              # Update local AO install (source installs only)
ao config-help                         # Show full config schema reference

Zsh completion

mkdir -p ~/.zsh/completions
ao completion zsh > ~/.zsh/completions/_ao

Add the directory to fpath before running compinit:

fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit
compinit

With Oh My Zsh, write the generated file to ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/ao/_ao and add ao to the plugins=(...) list in ~/.zshrc.

ao doctor checks PATH and launcher resolution, required binaries, configured plugin resolution, terminal-runtime health (tmux on Unix; PowerShell / runtime-process on Windows), GitHub CLI health, config support directories, stale AO temp files, and core build/runtime sanity. Runs and is supported on macOS, Linux, and Windows.

ao update fast-forwards the local install on main, reinstalls dependencies, clean-rebuilds core packages, refreshes the launcher, and runs smoke tests. Works on macOS, Linux, and Windows (Windows uses the bundled ao-update.ps1 script automatically). Use ao update --skip-smoke to stop after rebuild, or ao update --smoke-only to rerun just the smoke checks.

Multi-Project Rollout

Portfolio mode is enabled by default. Users do not need to set AO_ENABLE_PORTFOLIO unless they explicitly want to disable portfolio/project-management flows.