boshu
18 KiB
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 demo
Show the AgentOps product boundary:
ao demo [flags]
Flags:
--concepts explain the product boundary
-h, --help help for demo
--quick show the compact one-pass example
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 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 )
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 redact
Read text on stdin, apply the canonical secret redactor (the same
ao redact [flags]
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]
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
Removed in the AgentOps Cathedral Cut
ao goals trace [flags]
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
Removed in the AgentOps Cathedral Cut
ao session memory [flags]
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 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 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 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 edit
Removed in the AgentOps Cathedral Cut
ao skills edit [flags]
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
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 roots (default: ~/.agents plus every installed runtime)
-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 — 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 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 constraint
Removed in the AgentOps Cathedral Cut
ao constraint [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 reconcile
Removed in the AgentOps Cathedral Cut
ao reconcile [flags]
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]