boshu2__agentops/cli/docs/COMMANDS.md

# ao CLI Reference

> Auto-generated by `scripts/generate-cli-reference.sh`.
> Do not edit manually. Re-run the script to update.

## Global Flags

          --config string   Config file (default: ~/.agentops/config.yaml)
          --dry-run         Show what would happen without executing
      -h, --help            help for ao
          --json            Output as JSON (shorthand for -o json)
      -o, --output string   Output format (json, table, yaml) (default "table")
      -v, --verbose         Enable verbose output
          --version         version for ao

---

## Commands

### `ao init`

Create local evidence and verdict directories. This command does not

```
ao init [flags]
```

---

### `ao quick-start`

AgentOps is a small semantic evidence layer around agent work.

```
ao quick-start [flags]
```

---

### `ao capabilities`

Print the machine-readable contract for the whole ao CLI as JSON.

```
ao capabilities [flags]
```

---

### `ao constraint`

Manage constraints compiled from promoted findings.

```
ao constraint [command]
```

**Subcommands:**

#### `ao constraint activate`

Promote a precision-backed shadow constraint to active blocking

```
ao constraint activate <id> [flags]
```

#### `ao constraint list`

List all constraints with status

```
ao constraint list [flags]
```

#### `ao constraint publish`

Export the ACTIVE constraints to docs/constraints/published.json (tracked + committed),

```
ao constraint publish [flags]
```

#### `ao constraint retire`

Change constraint status from active to retired

```
ao constraint retire <id> [flags]
```

#### `ao constraint review`

List constraints compiled >90 days ago without recent citation

```
ao constraint review [flags]
```

---

### `ao doctor`

Run health checks on your AgentOps installation.

```
ao doctor [command]
```

**Flags:**

```
      --dry-run           With --fix: print the plan, change nothing
      --explain string    Expand a single finding by id
      --fix               Apply fixers for findings (routes through mutate())
  -h, --help              help for doctor
      --json              Output results as JSON
      --online            Enable network probes (default: offline-only)
      --only strings      Scope to a subset of detectors or subsystems
      --quick             Run only fast-path detectors (< 200ms)
      --robot             Alias for --json with structured wrapper
      --robot-triage      Emit the mega-command triage JSON
      --severity string   Minimum severity to emit (P0|P1|P2|P3) (default "P3")
      --since string      Diff findings against an earlier run
      --skip strings      Inverse of --only
```

**Subcommands:**

#### `ao doctor capabilities`

Print the machine-readable doctor contract (JSON)

```
ao doctor capabilities [flags]
```

#### `ao doctor diff`

Show what --fix would change (read-only)

```
ao doctor diff [flags]
```

#### `ao doctor explain`

Expand a single finding with full evidence

```
ao doctor explain <finding-id> [flags]
```

#### `ao doctor fix`

Run detectors, then apply fixers (backs up before every mutation)

```
ao doctor fix [flags]
```

#### `ao doctor gc`

Prune old runs (requires --yes and --before <date>)

```
ao doctor gc [flags]
```

**Flags:**

```
      --before string   Prune runs started before this date (YYYY-MM-DD)
  -h, --help            help for gc
      --yes             Confirm pruning (required)
```

#### `ao doctor health`

Cheap one-line liveness summary

```
ao doctor health [flags]
```

#### `ao doctor ls`

List runs in .doctor/runs/

```
ao doctor ls [flags]
```

#### `ao doctor robot-docs`

Print the paste-ready agent handbook (Markdown)

```
ao doctor robot-docs [flags]
```

#### `ao doctor undo`

Restore from .doctor/runs/<run-id>/backups/ (run-id may be 'latest')

```
ao doctor undo <run-id> [flags]
```

**Flags:**

```
      --dry-run   Print the restore plan; do not execute
  -h, --help      help for undo
      --strict    Refuse if any backup is missing or hash-mismatched (default true)
```

---

### `ao gate`

Run ordinary deterministic repository checks.

```
ao gate [command]
```

**Subcommands:**

#### `ao gate check`

Run the declarative deterministic check registry.

```
ao gate check [flags]
```

**Flags:**

```
      --fail-fast                 stop after the first blocking check failure
      --fast                      explicitly select the default fast changed-surface subset
      --full                      run every registered deterministic check
      --github-annotations        emit GitHub Actions annotations for check results
  -h, --help                      help for check
      --json                      emit the machine-readable JSON report
      --require-workflow-parity   fail if the workflow references unregistered blocking scripts
      --scope string              changed-file scope: head|staged|worktree|upstream|range:<base>..<head> (default "head")
      --workflow-coverage         include workflow-to-registry coverage in the report
      --workflow-path string      workflow used for optional coverage comparison (default ".github/workflows/validate.yml")
```

---

### `ao robot-docs`

Print a paste-ready, agent-targeted handbook for the whole ao CLI.

```
ao robot-docs [flags]
```

---

### `ao status`

Display the current state of AgentOps knowledge base.

```
ao status [flags]
```

---

### `ao version`

Display the version, build information, and runtime details.

```
ao version [flags]
```

---

### `ao goals`

Track, measure, and validate project fitness goals.

```
ao goals [command]
```

**Flags:**

```
      --file string   Path to goals file (auto-detects GOALS.md then GOALS.yaml)
  -h, --help          help for goals
      --timeout int   Check timeout in seconds (default 240)
```

**Subcommands:**

#### `ao goals measure`

Run goal checks and produce a snapshot

```
ao goals measure [flags]
```

**Aliases:**

```
  measure, m
```

**Flags:**

```
      --directives           Output directives as JSON (skip gate checks)
      --exclude-tag string   Skip goals whose Tags include this value (e.g. long-cycle)
      --goal string          Measure a single goal by ID
  -h, --help                 help for measure
      --scenarios-only       Evaluate only executable-spec scenario satisfaction; skip shell gate-command execution
      --total-timeout int    Overall measurement timeout in seconds (0 disables)
```

#### `ao goals validate`

Validate GOALS.yaml structure and wiring

```
ao goals validate [flags]
```

**Aliases:**

```
  validate, v
```

#### `ao goals drift`

Compare snapshots for regressions

```
ao goals drift [flags]
```

**Aliases:**

```
  drift, d
```

#### `ao goals export`

Export latest snapshot as JSON (for CI)

```
ao goals export [flags]
```

**Aliases:**

```
  export, e
```

#### `ao goals history`

Show goal measurement history

```
ao goals history [flags]
```

**Aliases:**

```
  history, h
```

**Flags:**

```
      --goal string    Filter history to a specific goal
  -h, --help           help for history
      --since string   Show entries since date (YYYY-MM-DD)
```

#### `ao goals meta`

Run and report meta-goals only

```
ao goals meta [flags]
```

#### `ao goals render`

Render the executable-spec layer as BDD/Gherkin text.

```
ao goals render [flags]
```

**Flags:**

```
  -h, --help         help for render
      --out string   Write Gherkin to this file instead of stdout
```

#### `ao goals scenarios`

Inspect the executable-spec scenarios linked to GOALS.md directives.

```
ao goals scenarios [flags]
```

**Flags:**

```
      --directive int         Filter by directive display number
      --directive-id string   Filter listing to one directive by stable Directive ID
  -h, --help                  help for scenarios
      --lint                  Lint the directive↔scenario link graph instead of listing
      --strict                With --lint, exit non-zero on warnings as well as errors
```

#### `ao goals trace`

Walk the executable-spec trace chain defined in docs/adr/ADR-0005.

```
ao goals trace [flags]
```

**Flags:**

```
      --from string   Render the trace lineage rooted at this directive, scenario, or bead ID
  -h, --help          help for trace
      --orphans       Audit the whole chain for broken references (errors) and missing yields (warnings)
      --strict        Escalate warning-class defects to a non-zero exit (ADR-0005 §4.2)
```

---

### `ao session`

Inspect or export session evidence

```
ao session [command]
```

**Subcommands:**

#### `ao session bootstrap`

Report local orientation files without starting runtimes, probing

```
ao session bootstrap [flags]
```

**Flags:**

```
  -h, --help   help for bootstrap
      --json   Emit JSON
```

#### `ao session handoff`

Write a small handoff artifact without selecting work, claiming it,

```
ao session handoff [summary] [flags]
```

**Flags:**

```
      --collect               Collect best-effort read-only Git observations
      --continuation string   Caller-supplied continuation note
      --dry-run               Print the artifact without writing it
      --goal string           Caller-supplied goal
  -h, --help                  help for handoff
```

#### `ao session memory`

Manage repo-root MEMORY.md for cross-runtime access

```
ao session memory [command]
```

##### `ao session memory sync`

Write recent session history to a repo-root MEMORY.md with managed block markers.

```
ao session memory sync [flags]
```

**Flags:**

```
  -h, --help                 help for sync
      --max-entries int      Maximum session entries to keep (default 10)
      --output-file string   Output path (default: MEMORY.md in repo root)
      --quiet                Suppress output
```

#### `ao session rehydrate`

Read a handoff without consuming it, claiming work, or choosing a next action.

```
ao session rehydrate [flags]
```

**Flags:**

```
  -h, --help   help for rehydrate
      --json   Emit the stored artifact as JSON
```

---

### `ao completion`

Generate shell completion scripts for ao.

```
ao completion [bash|zsh|fish|powershell]
```

---

### `ao config`

View and manage AgentOps configuration.

```
ao config [command]
```

**Flags:**

```
  -h, --help   help for config
      --show   Show resolved configuration with sources
```

**Subcommands:**

#### `ao config models`

Display the current model cost tier settings with sources.

```
ao config models [flags]
```

**Flags:**

```
  -h, --help               help for models
      --set-skill string   Set a skill-specific tier override (e.g. council=quality)
      --set-tier string    Set the default model cost tier (quality, balanced, budget)
```

---

### `ao flywheel`

Knowledge flywheel operations and status.

```
ao flywheel [command]
```

**Subcommands:**

#### `ao flywheel compare`

Compare retrieval quality between primary and shadow namespaces.

```
ao flywheel compare [flags]
```

**Flags:**

```
  -h, --help            help for compare
      --shadow string   Shadow namespace to compare against primary (default "shadow")
```

#### `ao flywheel status`

Display comprehensive flywheel health status.

```
ao flywheel status [flags]
```

**Flags:**

```
      --days int           Period in days for metrics calculation (default 7)
  -h, --help               help for status
      --namespace string   Citation namespace to evaluate (primary by default) (default "primary")
```

---

### `ao claim`

Removed in the AgentOps Cathedral Cut

```
ao claim [flags]
```

---

### `ao close`

Removed in the AgentOps Cathedral Cut

```
ao close [flags]
```

---

### `ao converge`

Removed in the AgentOps Cathedral Cut

```
ao converge [flags]
```

---

### `ao crank`

Removed in the AgentOps Cathedral Cut

```
ao crank [flags]
```

---

### `ao done`

Removed in the AgentOps Cathedral Cut

```
ao done [flags]
```

---

### `ao governor`

Removed in the AgentOps Cathedral Cut

```
ao governor [flags]
```

---

### `ao help`

Help provides help for any command in the application.

```
ao help [command] [flags]
```

---

### `ao land`

Removed in the AgentOps Cathedral Cut

```
ao land [flags]
```

---

### `ao membrane`

Removed in the AgentOps Cathedral Cut

```
ao membrane [flags]
```

---

### `ao next-work`

Removed in the AgentOps Cathedral Cut

```
ao next-work [flags]
```

---

### `ao pawl`

Removed in the AgentOps Cathedral Cut

```
ao pawl [flags]
```

---

### `ao plan-pawl`

Removed in the AgentOps Cathedral Cut

```
ao plan-pawl [flags]
```

---

### `ao provenance`

Append-only write model for the SDLC provenance/intent graph

```
ao provenance [command]
```

**Subcommands:**

#### `ao provenance add`

Append one schema-valid, hash-chained provenance edge linking a source

```
ao provenance add <from-id> <to-id> [flags]
```

**Flags:**

```
      --evidence string     Optional evidence pointer (path, commit, CI run URL, event id)
      --from-type string    Source node type (decision|artifact|bead|...) (default "decision")
  -h, --help                help for add
      --json                Emit the sealed edge as JSON
      --relation string     Typed PROV-O relation (required), e.g. wasGeneratedBy
      --to-type string      Target node type (decision|artifact|bead|...) (default "artifact")
      --trust-tier string   Trust tier (authored|inferred|mined) (default "authored")
      --ts string           Override the UTC RFC3339 timestamp (defaults to now)
```

#### `ao provenance export`

Read docs/provenance/ledger.jsonl, canonically sort its edges by

```
ao provenance export [flags]
```

**Flags:**

```
  -h, --help     help for export
      --json     Emit a single indented JSON array instead of JSONL
      --verify   Verify the re-chained export and print only a one-line summary
```

#### `ao provenance list`

Read the provenance edges recorded in docs/provenance/ledger.jsonl, in

```
ao provenance list [flags]
```

**Flags:**

```
      --from-id string    Filter to edges whose from_id matches
  -h, --help              help for list
      --json              Emit machine-readable JSON
      --relation string   Filter to edges with this relation
```

#### `ao provenance mine-session`

Parse a Claude Code or Codex session transcript and emit the per-inference

```
ao provenance mine-session --file <session.jsonl> [flags]
```

**Flags:**

```
      --file string    Path to the session transcript (.jsonl) to mine (required)
  -h, --help           help for mine-session
      --json           Emit events as JSONL on stdout (default true)
      --state string   Path to the incremental watermark state JSON (created/updated; omit for a full one-shot mine)
```

#### `ao provenance position`

Report the ledger record count and latest hash without inferring lifecycle state.

```
ao provenance position [flags]
```

**Flags:**

```
  -h, --help   help for position
      --json   Emit machine-readable JSON
```

#### `ao provenance show`

Read the provenance ledger and show every edge whose from_id or to_id

```
ao provenance show <node-id> [flags]
```

**Flags:**

```
  -h, --help   help for show
      --json   Emit machine-readable JSON
```

#### `ao provenance trace`

Audit a provenance trace-graph for orphans: engineered artifact nodes

```
ao provenance trace [flags]
```

**Flags:**

```
      --graph string   Path to the JSONL trace-graph to audit (required)
  -h, --help           help for trace
      --json           Emit each finding as one JSON object per line
      --orphans        Audit for artifact nodes with no inbound provenance edge
      --strict         Exit non-zero when any orphan exists
```

#### `ao provenance verify`

Read docs/provenance/ledger.jsonl exactly as committed and verify its

```
ao provenance verify [flags]
```

**Flags:**

```
  -h, --help   help for verify
      --json   Emit the machine-readable verify result as JSON
```

---

### `ao reconcile`

Removed in the AgentOps Cathedral Cut

```
ao reconcile [flags]
```

---

### `ao skills`

Tooling for the skills/ source-of-truth and its skills-codex/

```
ao skills [command]
```

**Subcommands:**

#### `ao skills check`

Walk skills/ and skills-codex/, validating each skill's YAML

```
ao skills check [flags]
```

**Flags:**

```
  -h, --help           help for check
      --json           Emit machine-readable JSON
      --skill string   Restrict the audit to a single skill name
      --strict         Exit non-zero on any finding (CI mode)
```

#### `ao skills consumers`

Print the skills whose consumes[] list includes <skill> — i.e. who

```
ao skills consumers <skill> [flags]
```

**Flags:**

```
  -h, --help   help for consumers
      --json   Emit machine-readable JSON
```

#### `ao skills edit`

Immune-system commands for the live skill tier.

```
ao skills edit [command]
```

##### `ao skills edit digest`

Summarize recent committed skill edits

```
ao skills edit digest [flags]
```

**Flags:**

```
      --critical-policy string   Critical skills policy file (default: docs/contracts/critical-skills.txt)
  -h, --help                     help for digest
      --json                     Emit JSON
      --since string             git log --since value (default "24 hours ago")
```

##### `ao skills edit seal`

Commit one live skill edit with critical-skill protection

```
ao skills edit seal [flags]
```

**Flags:**

```
      --actor string             Agent/operator name recorded in the commit body
      --allow-critical           Allow a critical skill edit; use only for human-supervised edits
      --critical-policy string   Critical skills policy file (default: docs/contracts/critical-skills.txt)
      --dry-run                  Check policy and print the commit action without staging or committing
  -h, --help                     help for seal
      --message string           Commit subject (default: chore(skills): update <skill> via live edit)
      --skill string             Skill slug under skills/<slug> to seal
```

#### `ao skills find`

Score every skills/<name>/SKILL.md against a free-text intent and

```
ao skills find <intent> [flags]
```

**Flags:**

```
  -h, --help        help for find
      --json        Emit machine-readable JSON on stdout
      --limit int   Maximum number of results to return (default 5)
```

#### `ao skills graph`

Render the skill execution/delegation graph (A --> B means A declares

```
ao skills graph [flags]
```

**Flags:**

```
      --format string   Graph output format (mermaid|json) (default "mermaid")
  -h, --help            help for graph
```

#### `ao skills link`

Scan skills/ and create a live-tier symlink for every skill dir that has

```
ao skills link [flags]
```

**Flags:**

```
      --dest string   Link into this single dir instead of the auto-detected runtimes (default: every installed runtime — ~/.claude, ~/.codex, ~/.gemini, ~/.cursor, ~/.pi)
  -h, --help          help for link
      --json          Emit machine-readable JSON
```

#### `ao skills list`

Filter the generated skill catalog by hexagonal role, produced or

```
ao skills list [flags]
```

**Flags:**

```
      --consumes string         Filter to skills that consume this port/sibling
  -h, --help                    help for list
      --json                    Emit machine-readable JSON
      --practice string         Filter to skills that apply this practice
      --produces string         Filter to skills that produce this port/artifact
      --role string             Filter by hexagonal_role (domain, driving-adapter, ...)
      --user-invocable string   Filter by user-invocability (true|false)
```

#### `ao skills producers`

Print the skills whose produces[] list includes <output> — i.e. who

```
ao skills producers <output> [flags]
```

**Flags:**

```
  -h, --help   help for producers
      --json   Emit machine-readable JSON
```

#### `ao skills resolve`

Walk skills/ and resolve the corpus toward MECE:

```
ao skills resolve [flags]
```

**Flags:**

```
  -h, --help     help for resolve
      --json     Emit machine-readable JSON
      --strict   Exit non-zero when ME overlaps are found (CI dedup gate)
```

#### `ao skills unlink`

The clean uninstall inverse of `ao skills link`. Scan each runtime's

```
ao skills unlink [flags]
```

**Flags:**

```
      --dest string   Sweep this single dir instead of the auto-detected runtimes (default: every installed runtime — ~/.claude, ~/.codex, ~/.gemini, ~/.cursor, ~/.pi)
  -h, --help          help for unlink
      --json          Emit machine-readable JSON
```

---

### `ao state`

Removed in the AgentOps Cathedral Cut

```
ao state [flags]
```

---

### `ao validate`

Removed in the AgentOps Cathedral Cut

```
ao validate [flags]
```

---

### `ao worktree`

Removed in the AgentOps Cathedral Cut

```
ao worktree [flags]
```

---

### `ao yield`

Removed in the AgentOps Cathedral Cut

```
ao yield [flags]
```

---