---
name: ao-usage
description: "Complete CLI reference for the AO (Agent Ops Issues) tool. Flag reference, command catalog, common patterns, and error handling."
version: "1.0.0"
category: core
invokes: []
invoked_by: [ao-task, ao-planning, ao-implementation, ao-complete, ao-focus-scan, ao-state, ao-housekeeping, ao-issue-merge]
state_files:
  read: [issues/events.jsonl, issues/active.jsonl]
  write: [issues/events.jsonl, issues/active.jsonl]
entrypoint: ao
audience: [agent]
requires:
  tools:
    - ao
  files:
    - ".agent/ops/issues/events.jsonl (auto-created)"
    - ".agent/ops/issues/active.jsonl (auto-created)"
---

# AO CLI Reference

## Global Options

| Flag | Values | Default | Notes |
|------|--------|---------|-------|
| `--root PATH` | directory path | auto-detected | Override `.agent/ops/` |
| `--format` | `table\|json\|jsonl\|plain` | `table` | Output format |
| `--yes` | flag | off | Non-interactive mode |
| `--quiet` | flag | off | Minimal output |
| `--progress` | `auto\|rich\|none` | `auto` | Progress display |
| `--in TEXT` | file path or `-` | — | Read JSON from file/stdin |
| `--out TEXT` | file path or `-` | `-` | Write output to file/stdout |
| `--sandbox` | flag | off | No background processes |

### Flag Guidelines

Most commands need **no global flags**:

- `--yes` is **only needed** for interactive commands: `compact`, `triage`, `worktree`, `profile create`
- When `--yes` is set, `--format json` and `--progress none` are **auto-applied** — never add them explicitly
- Commands like `add`, `set`, `close`, `log`, `ls`, `show`, `next`, `ac`, `link`, `label`, `rebuild` need **no global flags**

Global flags go **before** the subcommand:
```bash
ao --format json ls          # ✅ correct
ao ls --format json          # ❌ wrong
ao --yes compact             # ✅ correct (--yes auto-sets json+none)
```

## Issue ID Format

All issue IDs use: `{TYPE}-{NNNN}@{HASH}` (e.g., `FEAT-0042@c2d4e6`)

Short IDs resolve automatically when unambiguous.

---

## Command Reference

### add — Create issue

```bash
ao add "Title" [OPTIONS]
```

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--type` | TEXT | `feat` | Issue type: feat, bug, test, docs, refac, perf, idea, sec, enh |
| `--priority` | TEXT | `backlog` | Priority: critical, high, medium, low, backlog |
| `--epic` | TEXT | `""` | Epic name |
| `--owner` | TEXT | `agent` | Owner |
| `--confidence` | TEXT | `normal` | Confidence: low, normal, high |
| `--status` | TEXT | `todo` | Initial status |
| `--stacked-diff` | TEXT | `optional` | yes\|no\|optional |
| `--separate-worktree` | TEXT | `optional` | required\|optional\|no |
| `--version` | TEXT | from `.version` | Issue version |
| `--body` | TEXT | — | Issue body (stored as first log entry) |
| `--label` | TEXT | — | Comma-separated labels |

### set — Update issue fields

```bash
ao set ISSUE_ID [OPTIONS]
```

| Flag | Type | Description |
|------|------|-------------|
| `--status` | TEXT | Status |
| `--priority` | TEXT | Priority |
| `--owner` | TEXT | Owner |
| `--confidence` | TEXT | Confidence |
| `--epic` | TEXT | Epic |
| `--title` | TEXT | Title |
| `--notes` | TEXT | Notes |
| `--external-ref` | TEXT | External reference (e.g. JIRA-123, URL) |
| `--stacked-diff` | TEXT | yes\|no\|optional |
| `--separate-worktree` | TEXT | required\|optional\|no |
| `--version` | TEXT | Version metadata |

### show — Display issue details

```bash
ao show ISSUE_ID
ao issue show ISSUE_ID
```

### close — Close issue

```bash
ao close ISSUE_ID [OPTIONS]
```

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--status` | TEXT | `done` | Terminal status |
| `--log` | TEXT | — | Log message before close |
| `--solution` | TEXT | — | Solution notes |

### ls — List and filter issues

```bash
ao ls [OPTIONS] [QUERY_TOKENS...]
```

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--status` | TEXT | — | Filter by status |
| `--priority` | TEXT | — | Filter by priority |
| `--type` | TEXT | — | Filter by type |
| `--epic` | TEXT | — | Filter by epic |
| `--owner` | TEXT | — | Filter by owner |
| `--confidence` | TEXT | — | Filter by confidence |
| `--label` | TEXT | — | Filter by label |
| `--text` | TEXT | — | Text search |
| `--view` | TEXT | `table` | table\|kanban\|summary\|counts\|ids |
| `--sort` | TEXT | `priority` | priority\|updated\|id\|confidence |
| `--limit` | INT | — | Max results |
| `--all` | flag | — | Include done/blocked |

Query token shorthand: `ao ls status:todo prio:high type:bug`

### next — Top ready issues

```bash
ao next
```

### log add — Append log entry

```bash
ao log add ISSUE_ID "message"
```

### label add / rm / ls

```bash
ao label add ISSUE_ID "label-name"
ao label rm ISSUE_ID "label-name"
ao label ls ISSUE_ID
```

### ac — Acceptance criteria

```bash
ao ac add ISSUE_ID "Criterion text"
ao ac check ISSUE_ID INDEX          # 1-based index
ao ac rm ISSUE_ID INDEX
```

### link — Dependency links

```bash
ao link add ISSUE_ID --depends-on OTHER_ID
ao link add ISSUE_ID --blocks OTHER_ID
ao link rm ISSUE_ID --depends-on OTHER_ID
ao link rm ISSUE_ID --blocks OTHER_ID
```

### ref — Reference documents

```bash
ao ref init ISSUE_ID    # Create reference doc from template
```

### epic — Epic management

```bash
ao epic rename OLD_NAME NEW_NAME
```

### rebuild — Rebuild snapshot

```bash
ao rebuild
```

### focus — Session focus management

```bash
ao focus                                     # Show current focus
ao focus set-doing ISSUE_ID --task "desc" --confidence normal
ao focus set-just-did "Summary of work done"
ao focus set-next "Description of next step"
ao focus iteration --increment --issues "ID1,ID2" --confidence-mix "2 normal"
ao focus sync                                # Sync focus with issue states
```

**Never edit focus.json directly** — always use `ao focus` subcommands.

### Pipe mode (advanced)

```bash
printf '{"title":"T","type":"bug"}' | ao issue add --in -
printf '{"set":{"status":"in_progress"}}' | ao issue patch ISSUE_ID --in -
```

---

## Agent Cheat Sheet

### Create a fully-described issue (single command)

```bash
ao add "Fix login timeout" --type bug --priority high --body "Users report 30s timeout on login page" --label "auth,urgent"
```

### Standard issue lifecycle

```bash
ao add "Implement feature X" --type feat --priority high --epic my-epic
ao set FEAT-0042@abc123 --status in_progress
ao log add FEAT-0042@abc123 "Started implementation"
ao ac add FEAT-0042@abc123 "Unit tests pass"
ao ac check FEAT-0042@abc123 1
ao close FEAT-0042@abc123 --log "Completed: implemented feature X" --status done
```

### Find work

```bash
ao next                                  # Top ready issues by priority
ao ls --status todo --priority high      # High-priority todos
ao ls --epic my-epic                     # Issues in an epic
ao next --limit 10                       # Ready issues sorted
```

### Track progress

```bash
ao focus set-doing FEAT-0042@abc123 --task "Implementing X" --confidence normal
ao log add FEAT-0042@abc123 "Progress: completed step 1"
ao focus set-just-did "Completed FEAT-0042: implemented X"
```

---

## Common Errors

| Error | Cause | Fix |
|-------|-------|-----|
| Version mismatch | `.version` file differs from issue version | Update `.version` or pass `--version` |
| Issue not found | Wrong ID or typo | Use `ao ls` to find correct ID |
| Title is required | Missing title argument | Pass title as first argument |
| Global flag after subcommand | `ao ls --format json` | Move flag before: `ao --format json ls` |

## Non-negotiables

- Prefer minimal-diff operations (set/log/ac) over full JSON patches
- If a command fails, report the error code and message
- Never edit `events.jsonl` or `active.jsonl` directly
- Never edit `focus.json` directly — use `ao focus` subcommands
