# AO CLI Command Reference

> Use `ao` directly (not `uv run ao`). Global flags go **before** the subcommand.

## Global Flags

| Flag | Values | Default | Description |
|------|--------|---------|-------------|
| `--version` | — | — | Show version |
| `--root PATH` | path | auto-detect | Override `.agent/ops/` root |
| `--format` | table, json, jsonl, plain | table | Output format |
| `--yes` | — | — | Non-interactive mode |
| `--quiet` | — | — | Minimal output |
| `--progress` | auto, rich, none | auto | Progress display |
| `--in TEXT` | file path or `-` | — | Read JSON input from file/stdin |
| `--out TEXT` | file path or `-` | `-` | Write output to file/stdout |
| `--sandbox` | — | — | No background processes, direct JSONL I/O |

## Core Commands

| Command | Description | Key Flags |
|---------|-------------|-----------|
| `add [TITLE]` | Create a new issue | `--type`, `--priority`, `--epic`, `--owner`, `--confidence`, `--status`, `--version`, `--label`, `--body` |
| `idea TITLE` | Quick backlog IDEA issue | `--body`, `--epic` |
| `show ISSUE_ID` | Display full issue details | — |
| `set ISSUE_ID[,ID2,…]` | Quick scalar update (comma-separated IDs for batch) | `--status`, `--priority`, `--owner`, `--confidence`, `--epic`, `--title`, `--notes`, `--external-ref` |
| `close ISSUE_ID` | Close an issue | `--status` (done/cancelled/dropped), `--log`, `--solution` |
| `complete ISSUE_ID` | Execute completion verification | — |
| `ls [QUERY_TOKENS]` | List and filter issues | `--status`, `--priority`, `--type`, `--epic`, `--owner`, `--confidence`, `--label`, `--text`, `--view`, `--sort`, `--limit`, `--all` |
| `kanban` | Kanban board (alias for `ls --view kanban`) | — |
| `query [QUERY_TOKENS]` | Query and filter active issues | Same as `ls` |
| `next` | Top N ready-to-work issues | `--owner`, `--limit` |
| `stale` | Issues not updated in N days | `--days` |
| `rebuild` | Rebuild active.jsonl from events.jsonl | — |
| `dep-tree ISSUE_ID` | Dependency tree with cycle detection | — |
| `merge FILE` | Merge two events.jsonl files | — |
| `validate` | Run validation commands | — |
| `gate ISSUE_ID` | Completion gate check | — |
| `import FILE` | Import external events | — |
| `suggest-labels FILES...` | Suggest labels for file paths | — |
| `onboard` | Generate AOI_GUIDE.md | — |
| `install` | Install AO asset folders | — |
| `update` | Update AO assets | — |
| `prime` | Machine-readable CLI summary | — |
| `duplicate SKILL` | Duplicate skill across engines | `--engine` |
| `triage` | Interactive bulk triage (human only) | — |
| `web` | Launch Kanban web UI | — |

## Subcommand Groups

### `issue` — Issue Management

| Subcommand | Description | Key Flags |
|------------|-------------|-----------|
| `issue add` | Create issue (same as top-level `add`) | Same as `add` |
| `issue show` | Show issue (same as top-level `show`) | — |
| `issue set` | Update issue (same as top-level `set`) | Same as `set` |
| `issue patch` | JSON patch from stdin | `--in -` |
| `issue close` | Close issue (same as top-level `close`) | Same as `close` |
| `issue complete` | Completion check (same as top-level) | — |

### `log` — Log Entries

| Subcommand | Description |
|------------|-------------|
| `log add ISSUE_ID MESSAGE` | Append timestamped log entry |

### `epic` — Epic Management

| Subcommand | Description |
|------------|-------------|
| `epic ls` | List epics with issue counts |
| `epic show NAME` | List issues in epic |
| `epic summary NAME` | Status/priority breakdown |
| `epic rename OLD NEW` | Rename epic across all issues |
| `epic analyze` | AI-assisted epic assignment |

### `ac` — Acceptance Criteria

| Subcommand | Description |
|------------|-------------|
| `ac ls ISSUE_ID` | List acceptance criteria |
| `ac add ISSUE_ID TEXT` | Add criterion |
| `ac check ISSUE_ID INDEX` | Mark criterion done (1-based) |
| `ac uncheck ISSUE_ID INDEX` | Unmark criterion |
| `ac rm ISSUE_ID INDEX` | Remove criterion |

### `link` — Dependency Links

| Subcommand | Description |
|------------|-------------|
| `link add ISSUE_ID` | Add dependency (`--depends-on`, `--blocks`) |
| `link rm ISSUE_ID` | Remove dependency |
| `link show ISSUE_ID` | Show dependency info |
| `link graph` | Generate dependency graph |
| `link typed-add ISSUE_ID` | Add typed link (`--related`, `--duplicate-of`, `--discovered-from`, `--parent`, `--child`) |
| `link typed-rm ISSUE_ID` | Remove typed link |

### `ref` — Reference Documents

| Subcommand | Description |
|------------|-------------|
| `ref init ISSUE_ID` | Create reference doc from template |
| `ref open ISSUE_ID` | Open in $EDITOR |
| `ref attach ISSUE_ID` | Attach custom path (`--path`) |
| `ref status ISSUE_ID` | Check reference doc status |

### `focus` — Session State

| Subcommand | Description |
|------------|-------------|
| `focus set-doing ISSUE_ID` | Set active work (`--task`, `--confidence`) |
| `focus set-next TEXT` | Set next up |
| `focus set-just-did TEXT` | Record completed work |
| `focus iteration` | Update iteration (`--increment`, `--issues`, `--confidence-mix`) |
| `focus sync` | Rebuild focus state from issues |

### `label` — Labels

| Subcommand | Description |
|------------|-------------|
| `label add ISSUE_ID LABEL` | Add label |
| `label rm ISSUE_ID LABEL` | Remove label |
| `label ls ISSUE_ID` | List labels |

### `state` — Operational State

| Subcommand | Description |
|------------|-------------|
| `state set ISSUE_ID DIM:VAL` | Set dimension value |
| `state get ISSUE_ID DIM` | Get dimension value |

### `event` — Raw Events

| Subcommand | Description |
|------------|-------------|
| `event append` | Append raw event from stdin (`--in -`) |

### `export` — Export

| Subcommand | Description |
|------------|-------------|
| `export json` | Export as single JSON (`--out`) |
| `export jsonl` | Export as JSONL (`--out`) |

### `idea` — Quick Backlog Capture

| Command | Description | Key Flags |
|---------|-------------|-----------|
| `idea TITLE` | Shortcut to create a backlog IDEA issue | `--body`, `--epic` |

### `lesson` — Lessons Learned

| Subcommand | Description | Key Flags |
|------------|-------------|-----------|
| `lesson add ISSUE_ID MESSAGE` | Add a lesson learned to an issue | — |
| `lesson ls ISSUE_ID` | List lessons learned for an issue | `--query`/`-q`, `--limit`/`-n` |

### `compact` — Event Log Compaction

| Subcommand | Description |
|------------|-------------|
| `compact analyze` | Analyze event log and show compaction candidates |
| `compact apply` | Compact event log by collapsing events into snapshots |

### `hooks` — Git Hook & Agent Loop Management

| Subcommand | Description | Key Flags |
|------------|-------------|-----------|
| `hooks install` | Install AO git hooks (post-merge, post-checkout, pre-push) | `--force` |
| `hooks uninstall` | Remove AO-installed git hooks | — |
| `hooks status` | Show status of AO git hooks | — |
| `hooks run` | Run an AO hook rule (JSON stdin → decision stdout) | `--engine` (required), `--event` (required) |
| `hooks test` | Test an AO hook rule with a sample payload | `--engine` (required), `--event` (required), `--payload` |
| `hooks agent-install` | Install AO hook config for an AI agent engine | `--engine` (required) |
| `hooks loop-prompt` | Generate an AO iteration prompt for an agent engine | `--engine` (required), `--output`/`-o` |
| `hooks loop-run` | Run the AO iteration loop until no ready issues remain | `--engine` (required), `--max`, `--dry-run` |

### `worker` — Worker Registry

| Subcommand | Description | Key Flags |
|------------|-------------|-----------|
| `worker ls` | List all registered workers | — |
| `worker add NAME` | Register a new worker | — |
| `worker show NAME` | Show details of a registered worker | — |
| `worker update NAME` | Update fields of a registered worker | `--label`, `--model`, `--context`, `--instructions`, `--engine` |
| `worker rm NAME` | Remove a registered worker | — |
| `worker assign NAME` | Assign a worker to an issue (sets owner field) | — |

### Other Groups

| Group | Description |
|-------|-------------|
| `gen` | Data generation commands |
| `bench` | Benchmark commands |
| `profile` | Profile management |
| `version` | Project version management |
| `stack` | Stacked-diff workflow |
| `guard` | Stack workflow guards |
| `admin` | Admin recovery and migration |
| `lock` | Lock management |
| `worktree` / `wt` | Git worktree management |
