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: ~/.agents/ao/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 demo

Show a native coding-agent change from accepted behavior through checks,

ao demo [flags]

Flags:

      --concepts   explain the product boundary
  -h, --help       help for demo
      --quick      show the compact native example (the default)
      --rpi        show the optional full RPI workflow

---

ao init

Optional local evidence setup; native execution needs no init, skills or

ao init [flags]

---

ao quick-start

Use your native coding agent and shell to complete the accepted work.

ao quick-start [flags]

---

ao capabilities

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

ao capabilities [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]

Flags:

  -h, --help           help for diff
      --only strings   Scope the fix-plan preview to finding ids or subsystems (comma-separated), mirroring --fix --only

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 )

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//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 content-addressed intent and verdict evidence stored by AgentOps.

ao status [flags]

Flags:

      --evidence-root string   Existing explicit non-Git evidence directory (default: working directory's .agents/ao)
  -h, --help                   help for status

---

ao version

Display the version, build information, and runtime details.

ao version [flags]

---

ao gc

Prepare and qualify the stock Gas City maintainer pack without owning a pack.

ao gc [command]

Subcommands:

ao gc check

Verify a prepared maintainer runtime read-only

ao gc check [flags]

Flags:

      --city string            Gas City root directory (required)
      --codex-bin string       Codex CLI used to resolve hook trust identities (default: codex on PATH)
      --gc-bin string          Gas City 1.4 binary (default: gc on PATH)
  -h, --help                   help for check
      --pack-dir string        resolved official gascity pack root (normally auto-detected)
      --rig string             rig directory inside the city (required)
      --skills-source string   AgentOps skills directory to link from (default: enclosing checkout, then installed skills root)

ao gc prepare

Stage the contained maintainer runtime, skill links, and codex trust for a rig

ao gc prepare [flags]

Flags:

      --city string            Gas City root directory (required)
      --codex-bin string       Codex CLI used to resolve hook trust identities (default: codex on PATH)
      --gc-bin string          Gas City 1.4 binary (default: gc on PATH)
  -h, --help                   help for prepare
      --pack-dir string        resolved official gascity pack root (normally auto-detected)
      --rig string             rig directory inside the city (required)
      --skills-source string   AgentOps skills directory to link from (default: enclosing checkout, then installed skills root)

ao gc recover-affinity

Clear stale required session-affinity assignments (dry-run by default)

ao gc recover-affinity [flags]

Flags:

      --apply             apply the recovery; the default is a read-only dry run
      --city string       Gas City root directory (required)
      --gc-bin string     Gas City 1.4 binary (default: gc on PATH)
  -h, --help              help for recover-affinity
      --pack-dir string   resolved official gascity pack root (normally auto-detected)
      --rig string        rig directory inside the city (required)

---

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 session

Inspect session evidence and maintain .agents artifacts

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 prune-agents

Apply .agents retention policies (dry-run by default)

ao session prune-agents [flags]

Flags:

      --execute   Delete the selected artifacts; the default is a read-only dry run
  -h, --help      help for prune-agents
      --quiet     Suppress per-path output and print only the summary

ao session read-source

Read one explicit regular source file under independently selected T05 context

ao session read-source [flags]

Flags:

      --access-policy-ref string      Independently selected T05 access policy JSON (required)
      --allow-oversize                Explicitly bypass serialized profile size bound; host delivery remains unverified
      --consumer-root string          Existing consumer checkout for T05 route verification (required)
      --destination-ref string        Expected destination identity (required)
      --expect-file-identity string   Expected prior file_before.identity, for replacement checks across calls
      --expect-prefix-sha256 string   Expected SHA-256 of all bytes before through-byte
      --file string                   Exact absolute source file path (required)
  -h, --help                          help for read-source
      --json                          Emit JSON (also the default; no text-only coverage view)
      --max-bytes int                 Positive maximum returned source bytes (required)
      --model-ref string              Expected model/provider identity (required)
      --native-directory string       Explicit directory for native BD source verification (required)
      --owner-scope string            Independently expected owner scope (required)
      --project-id string             Expected native project identity (required)
      --source-id string              Expected canonical native beads_dir (required)
      --start-byte int                First byte of the returned half-open range (required)
      --task-ref string               Expected caller task identity (required)
      --through-byte int              Frozen exclusive prefix boundary, paired with expect-prefix-sha256

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 context

Resolve caller/home CDLC routes and read the selected native maintenance anchor.

ao config context [flags]

Flags:

      --access-policy-ref string      Existing caller-owned access policy JSON
      --bundle-root string            Selected existing external bundle
      --consumer-root string          Existing consumer checkout to exclude
      --destination-ref string        Caller destination identity
      --evidence-root string          Selected existing protected non-Git evidence
      --field string                  Emit one checked root for its caller-owned consumer
  -h, --help                          help for context
      --maintenance-work-ref string   Known native maintenance anchor
      --model-ref string              Caller model/provider identity
      --native-directory string       Explicit native BD source directory
      --owner-scope string            Expected separately authorized owner scope
      --project-id string             Expected native project ID
      --recover                       Recover the same route from its native maintenance anchor
      --source-id string              Expected canonical native beads_dir
      --staging-root string           Selected existing protected non-Git staging
      --task-ref string               Caller task identity

---

ao provenance

Append and inspect generic, evidence-backed relationships between

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 (for example decision, artifact, or observation) (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 (for example decision, artifact, or observation) (default "artifact")
      --trust-tier string   Trust tier (authored|inferred|mined) (default "authored")
      --ts string           Override the UTC RFC3339 timestamp (defaults to now)

ao provenance check-okf

Check one explicitly selected Markdown concept against agentops-okf-v0.2/v1,

ao provenance check-okf [flags]

Flags:

      --file string      Explicit Markdown concept file (required; at most 1 MiB)
  -h, --help             help for check-okf
      --json             Emit JSON (the default)
      --profile string   Exact supported structural profile version (default "agentops-okf-v0.2/v1")

ao provenance digest

Hash a strict JSON object in canonical form.

ao provenance digest <json-file> [flags]

Flags:

  -h, --help                    help for digest
      --helper-version string   Require evidence helper version; incompatibility fails before mutation (default "1")
      --json                    Emit JSON (the default for evidence operations except digest)

ao provenance evidence-orphans

Read the established scorecard, fixture-set and capture-contract bindings

ao provenance evidence-orphans [flags]

Flags:

      --changed stringArray   Changed bound path; repeat to preserve input order
  -h, --help                  help for evidence-orphans
      --root string           Explicit repository root to scan

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 manifest

Compute subject-manifest.v1 from declared filesystem paths.

ao provenance manifest [flags]

Flags:

      --base-manifest string           Base manifest for deletions
      --evidence-root string           Existing non-Git directory required with --out
      --exclude stringArray            Excluded path or fnmatch pattern (repeatable)
      --exclude-git-root stringArray   Caller-known existing Git storage root to exclude (repeatable); unresolved roots fail before writes
      --git-metadata-json string       Descriptive string/null metadata object; excluded from identity
  -h, --help                           help for manifest
      --helper-version string          Require evidence helper version; incompatibility fails before mutation (default "1")
      --include stringArray            Declared relative path (repeatable)
      --json                           Emit JSON (the default for evidence operations except digest)
      --out string                     Optional relative output path inside evidence root
      --root string                    Explicit subject directory

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)
      --max-bytes int          Excerpts only: maximum source-window bytes (default 65536)
      --max-output-bytes int   Excerpts only: maximum serialized JSON bytes, including newline (default 131072)
      --max-records int        Excerpts only: maximum emitted records (default 20)
      --start-byte int         Excerpts only: zero-based record-aligned source offset
      --state string           Path to the incremental watermark state JSON (created/updated; omit for a full one-shot mine)
      --target string          Excerpts only: explicit instruction file, at most 64 KiB
      --view string            Output view: events (legacy JSONL) or excerpts (one bounded JSON document) (default "events")

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 snapshot-intent

Store exact immutable intent bytes in an explicit non-Git evidence root.

ao provenance snapshot-intent [flags]

Flags:

      --evidence-root string           Existing explicit non-Git evidence directory
      --exclude-git-root stringArray   Caller-known existing Git storage root to exclude (repeatable); unresolved roots fail before writes
  -h, --help                           help for snapshot-intent
      --helper-version string          Require evidence helper version; incompatibility fails before mutation (default "1")
      --json                           Emit JSON (the default for evidence operations except digest)
      --source string                  Intent file, or - for stdin

ao provenance store-verdict

Verify and atomically store a supplied verdict.v2 with runtime facts.

ao provenance store-verdict [flags]

Flags:

      --author-context-id string       Runtime author identity
      --base-manifest string           Base manifest for deletions
      --draft string                   Fresh judge's supplied draft JSON
      --evidence-root string           Existing explicit non-Git evidence directory
      --exclude-git-root stringArray   Caller-known existing Git storage root to exclude (repeatable); unresolved roots fail before writes
      --freshness-attester-id string   Freshness attester identity
      --freshness-source string        runtime or caller
  -h, --help                           help for store-verdict
      --helper-version string          Require evidence helper version; incompatibility fails before mutation (default "1")
      --intent-source string           Independently supplied immutable intent file
      --json                           Emit JSON (the default for evidence operations except digest)
      --root string                    Explicit subject directory
      --scope-result string            Runtime-derived PASS, FAIL or NOT_PROVEN scope fact
      --subject-manifest string        Runtime-derived manifest
      --validator-context-id string    Fresh validator identity

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 provenance verify-judgments

Check caller-selected required judgment legs using existing verdict.v2 evidence_refs.

ao provenance verify-judgments [flags]

Flags:

      --allowed-provider stringArray   Independently authorized provider: openai or anthropic (repeatable)
      --author-context-id string       Independent native author context identity
      --base-manifest string           Base manifest for deletions
      --evidence-root string           Explicit private non-Git root for receipts, transcripts and verdicts
  -h, --help                           help for verify-judgments
      --helper-version string          Required evidence helper version (default "1")
      --intent string                  Independent expected immutable acceptance file
      --json                           Emit JSON (the default)
      --manifest string                Expected subject-manifest.v1 file
      --required-profiles string       Independent JSON object containing the required profiles array
      --root string                    Explicit subject directory
      --verdict stringArray            Content-addressed verdict.v2 file inside evidence root (repeatable)

ao provenance verify-manifest

Recompute and compare exact subject identity.

ao provenance verify-manifest [flags]

Flags:

      --base-manifest string    Base manifest required for deletion identity
  -h, --help                    help for verify-manifest
      --helper-version string   Require evidence helper version; incompatibility fails before mutation (default "1")
      --json                    Emit JSON (the default for evidence operations except digest)
      --manifest string         subject-manifest.v1 file
      --root string             Explicit subject directory

ao provenance verify-subject

Check a supplied PASS against exact content and independent expected intent.

ao provenance verify-subject [flags]

Flags:

      --base-manifest string    Base manifest required for deletion identity
  -h, --help                    help for verify-subject
      --helper-version string   Require evidence helper version; incompatibility fails before mutation (default "1")
      --intent string           Independent expected immutable acceptance file
      --json                    Emit JSON (the default for evidence operations except digest)
      --manifest string         subject-manifest.v1 file
      --root string             Explicit subject directory
      --verdict string          Content-addressed supplied verdict.v2 PASS

ao provenance verify-verdict

Structurally verify a content-addressed verdict.v2.

ao provenance verify-verdict [flags]

Flags:

  -h, --help                    help for verify-verdict
      --helper-version string   Require evidence helper version; incompatibility fails before mutation (default "1")
      --json                    Emit JSON (the default for evidence operations except digest)
      --verdict string          Content-addressed verdict.v2 file

---

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 — i.e. who

ao skills consumers <skill> [flags]

Flags:

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

ao skills find

Score every skills//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

Optionally install skills from a source checkout. Native execution needs no

ao skills link [flags]

Flags:

      --dest string         Link into this single dir instead of the auto-detected roots (default: ~/.agents plus every installed runtime)
  -h, --help                help for link
      --json                Emit machine-readable JSON
      --skill stringArray   Install only this skill; repeat for more names (default: all skills)

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 — 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 roots (default: ~/.agents plus every installed runtime)
  -h, --help          help for unlink
      --json          Emit machine-readable JSON

---

ao workflows

Tooling for the top-level workflows/ source-of-truth: the Claude-harness

ao workflows [command]

Subcommands:

ao workflows link

Scan the agentops checkout's workflows/ directory and create a symlink in

ao workflows link [flags]

Flags:

  -h, --help          help for link
      --into string   Link into this single dir instead of <cwd-git-root>/.claude/workflows
      --json          Emit machine-readable JSON

ao workflows unlink

The clean uninstall inverse of ao workflows link. Sweep the target

ao workflows unlink [flags]

Flags:

  -h, --help          help for unlink
      --into string   Sweep this single dir instead of <cwd-git-root>/.claude/workflows
      --json          Emit machine-readable JSON

---

ao help

Help provides help for any command in the application.

ao help [command] [flags]

---