ao CLI Reference
July 11, 2026 · View on GitHub
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
Set up a repository for AgentOps: directories and gitignore.
ao init [flags]
Flags:
-h, --help help for init
--stealth Use .git/info/exclude instead of .gitignore
ao quick-start
Initialize AgentOps in your current project.
ao quick-start [flags]
Aliases:
quick-start, quickstart
Flags:
-h, --help help for quick-start
--minimal Minimal setup (just directories)
--no-beads Skip beads initialization
ao capabilities
Print the machine-readable contract for the whole ao CLI as JSON.
ao capabilities [flags]
ao claim
Claim a BR bead for harness-neutral AgentOps loops, or bind/list claim evidence via the typed BC2 ClaimEvidenceBinderPort.
ao claim [command]
Subcommands:
ao claim bind
Append (or upgrade) a claim→evidence binding via the typed BC2
ao claim bind --claim <AOP-CLAIM-X> --path <evidence-path> [--level PG1|PG2|PG3|PG4] [--anchor ...] [--author-id <id> --judge-id <id>] [flags]
Flags:
--anchor stringArray optional in-file anchors (repeatable)
--author-id string artifact author identity for reviewer separation checks
--claim string claim ID (required, e.g. AOP-CLAIM-X)
-h, --help help for bind
--judge-id string judge/verifier identity for reviewer separation checks
--level string promotion level: PG1|PG2|PG3|PG4 (default "PG1")
--path string evidence file path (required, relative to repo root)
ao claim check
Report read-only proof cards for changed public claim markers.
ao claim check --changed [--base <ref>] [flags]
Flags:
--base string base ref for --changed comparison (default "origin/main")
--changed check claim markers in files changed against --base plus worktree changes
-h, --help help for check
ao claim list
Emit all known claim→evidence bindings via the typed BC2 ClaimEvidenceBinderPort. Output is line-delimited JSON.
ao claim list [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/
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
Manage human review gates for bronze-tier candidates.
ao gate [command]
Subcommands:
ao gate approve
Approve a bronze-tier candidate for promotion.
ao gate approve <candidate-id> [flags]
Flags:
-h, --help help for approve
--note string Optional approval note
ao gate bulk-approve
Approve all silver-tier candidates older than a threshold.
ao gate bulk-approve [flags]
Flags:
-h, --help help for bulk-approve
--older-than string Age threshold for bulk approval (default "24h")
--tier string Tier to bulk approve (default: silver) (default "silver")
ao gate check
Run the declarative gate registry.
ao gate check [flags]
Flags:
--fail-fast stop after the first blocking failure
--fast fast cockpit subset routed to changed files (the default; explicit flag for clarity in hooks)
--full run every check (routing ignored); default is the fast changed-file subset
--github-annotations emit GitHub Actions annotations for WARN/FAIL checks
-h, --help help for check
--json emit the machine-readable JSON report
--require-workflow-parity fail if validate.yml references scripts missing from the Go gate registry
--scope string fast-mode changed-file scope: head|staged|worktree|upstream|range:<base>..<head> (default "head")
--workflow-coverage include validate.yml-vs-registry script coverage in the report
--workflow-path string workflow path used by --workflow-coverage and --require-workflow-parity (default ".github/workflows/validate.yml")
ao gate pending
List bronze-tier candidates awaiting human review.
ao gate pending [flags]
ao gate reject
Reject a candidate with a required reason.
ao gate reject <candidate-id> [flags]
Flags:
-h, --help help for reject
--reason string Required rejection reason
ao gate run
Invoke a check-*.sh gate via the typed BC2 GateRunnerPort
ao gate run <name> [flags]
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 eval
Run deterministic AgentOps evaluation suites and compare run records.
ao eval [command]
Subcommands:
ao eval baseline
Promote an eval run record as a baseline
ao eval baseline <run.json> [flags]
Flags:
-h, --help help for baseline
--out string write promoted baseline run record to path
--promoted-by string identity promoting the baseline
--rationale string rationale for promoting the baseline
ao eval baseline-audit
Audit eval suite baseline policy against promoted baselines
ao eval baseline-audit [suite.json ...] [flags]
Flags:
--baseline-dir string promoted baseline directory (default ".agents/evals/baselines")
-h, --help help for baseline-audit
--root string suite root to scan when no suite paths are provided (default "evals/agentops-core")
ao eval bench
Measure Precision@K and MRR against a curated corpus of learning artifacts.
ao eval bench [flags]
Flags:
--corpus string Path to benchmark corpus directory
--global Include ~/.agents/learnings/ (cross-rig aggregated store, requires --live)
-h, --help help for bench
--json JSON output
--k int K for Precision@K (default 3)
--live Benchmark against real .agents/learnings/ instead of synthetic corpus
--search-backend string Search backend for --search-eval (local-lexical, ao-auto, agentic-rg, wiki-link-expand, rerank-llamacpp) (default "local-lexical")
--search-compare-backends string Comma-separated search backends to compare for --search-eval
--search-eval string Path to an ao-search eval manifest with queries and ground_truth paths
--search-root string Repo root to search for --search-eval (defaults to current directory)
ao eval chaos
Run a read-only smoke test of the tick membrane
ao eval chaos [flags]
ao eval cleanup
Per SCHEMA.md §4 cleanup state-transition rule (rc2):
ao eval cleanup [flags]
Flags:
--delete Remove Run directories whose status is failed or aborted (never retracted)
--dry-run Preview without mutations
-h, --help help for cleanup
--tmp-age int Minimum tmp-file age in seconds before sweep (0 = sweep all) (default 60)
--tmp-files Sweep orphan *.tmp files older than --tmp-age
ao eval compare
Compare an eval run against a baseline
ao eval compare <candidate-run.json> <baseline-run.json> [flags]
Flags:
-h, --help help for compare
--max-aggregate-regression float allowed aggregate regression before verdict becomes regression
--max-dimension-regression float allowed per-dimension regression before verdict becomes regression
--out string write compared eval run record to path
ao eval coverage
Summarize eval suite coverage
ao eval coverage [suite.json ...] [flags]
Flags:
-h, --help help for coverage
--require-dimension stringArray required score dimension for missing-dimension reporting (default [correctness,process_adherence,artifact_quality,runtime_compatibility,efficiency,safety,learning_closure])
--require-domain stringArray required product domain for missing-domain reporting (default [cli,hook,skill,rpi,runtime,retrieval,scenario,mixed,security])
--require-evidence-kind stringArray required evidence kind for missing-evidence-kind reporting
--require-runtime stringArray required deterministic runtime for missing-runtime reporting (default [static,shell,mock])
--root string suite root to scan when no suite paths are provided (default "evals/agentops-core")
ao eval outcomes
Outcomes is a derived projection of the locked eval substrate (SCHEMA.md), never an alternate authority. Subcommands compile holdout-safe rubric payloads and ingest returned scores into the one verdict format.
ao eval outcomes [command]
ao eval outcomes compile
Compile a holdout-safe Outcomes rubric payload from a locked Task + criteria
ao eval outcomes compile <input.json> [flags]
ao eval outcomes ingest
Ingest an Outcomes score payload into the one council verdict record
ao eval outcomes ingest <score.json> [flags]
Flags:
--burn-ledger string path to a JSON HoldoutBurnLedger; when set, a holdout-split score registers a burn and is REFUSED if the (suite,gt) quota is exhausted (gate #3 runtime enforcement), persisted across invocations
--expect-judge-hash string refuse the ingest if the score's judge_content_hash does not match this value (gate #2 rubric-drift parity)
-h, --help help for ingest
--manifest-out string also write an eval-run.v1 manifest to <dir>/<run-id>/manifest.json so the verdict pipeline feeds the Knowledge Flywheel (closes the Outcomes→Flywheel loop)
--run-id string run id for the --manifest-out manifest; defaults to the score's run_id, then source_task_id (sanitized to the eval-run.v1 pattern)
ao eval run
Run a deterministic eval suite
ao eval run <suite.json> [flags]
Flags:
--baseline string compare the run against a baseline run record
--baseline-mode string skill-on | skill-off | both — runs the suite once with skills loaded, once with hooks suppressed, or both for a delta scorecard (default "skill-on")
--context-mode string none | ab — run context-off/context-on legs over isolated AO_AGENTS_DIR roots (default "none")
--context-off-agents-dir string AO_AGENTS_DIR root for the context-off leg (defaults to suite fixtures)
--context-on-agents-dir string AO_AGENTS_DIR root for the context-on leg (defaults to suite fixtures)
--delta-out string write delta scorecard JSON to path (with --baseline-mode=both or --context-mode=ab)
-h, --help help for run
--out string write eval run record to path
--run-id string stable run id to use in the run record
--runtime string runtime override (static, mock, shell, claude, codex)
ao eval scenario
Create, list, and validate holdout scenarios stored in .agents/holdout/.
ao eval scenario [command]
ao eval scenario add
Author a schema-compliant holdout scenario in .agents/holdout/.
ao eval scenario add <goal> [flags]
Flags:
--expected-outcome string Expected observable outcome (default: inferred from goal)
-h, --help help for add
--narrative string Narrative description (default: inferred from goal)
--source string Scenario source (human, agent, prod-telemetry) (default "human")
--status string Scenario status (active, draft, retired) (default "draft")
--threshold float Satisfaction threshold in [0,1] (default 0.8)
ao eval scenario evaluate
Evaluate the executable-spec scenarios linked to GOALS.md directives and
ao eval scenario evaluate [flags]
Flags:
--all Evaluate every directive's linked scenarios
--directive string Evaluate only the directive with this stable Directive ID
-h, --help help for evaluate
--json Emit the machine-readable evaluation report
--run-id string run_id recorded in the results artifact (default "ao-scenario-evaluate")
--timeout duration Per-check execution timeout (default 2m0s)
ao eval scenario init
Initialize .agents/holdout/ directory for scenario storage
ao eval scenario init [flags]
ao eval scenario list
List holdout scenarios
ao eval scenario list [flags]
Flags:
-h, --help help for list
--status string Filter by status (active, draft, retired)
ao eval scenario validate
Validate holdout scenarios against schema
ao eval scenario validate [flags]
ao eval scenario-ab
Run one holdout scenario (scenario.v1) twice — a control arm WITHOUT the gold
ao eval scenario-ab [flags]
Flags:
--control-only Run only the without-gold control arm and fail on ceiling/no-headroom
-h, --help help for scenario-ab
--output string Write the ScenarioDeltaScorecard JSON to this path
--scenario string Path to the scenario.v1 JSON file (required)
--timeout duration Per-arm timeout (0 = default 5m)
--token-budget int Fail the gate if summed arm token cost exceeds this (0 = default 200000)
ao eval scenario-moat
Render a moat positive/null/inconclusive verdict over one or more
ao eval scenario-moat [flags]
Flags:
-h, --help help for scenario-moat
--output string Write the MoatClaimResult JSON to this path
--scorecard stringArray Path to a ScenarioDeltaScorecard JSON (repeatable)
ao eval scorecard
Build an eval scorecard from run records
ao eval scorecard <candidate-run.json> [baseline-run.json] [flags]
Flags:
-h, --help help for scorecard
--kind string scorecard kind (rpi, skill-change) (default "rpi")
--max-category-regression float allowed per-category regression before verdict becomes regression
--out string write scorecard JSON to path
ao eval session-outcome
Parse a Claude Code session transcript and derive a composite reward signal.
ao eval session-outcome [transcript-path] [flags]
Flags:
-h, --help help for session-outcome
--output string Output format: text, json (default "text")
--session string Session ID (extracted from transcript if not provided)
ao eval suite
Suite-level operations against the §6.5 statistical contract.
ao eval suite [command]
ao eval suite n-required
Compute power-derived n_required (gate #6 input on Day 3+)
ao eval suite n-required [flags]
Flags:
--alpha float Type-I error rate (default 0.05)
--baseline-rate float Baseline rate (binomial worst-case fallback) (default 0.5)
-h, --help help for n-required
--mde float Minimum detectable effect (default 0.05)
--paired Paired comparison (default true)
--power float Statistical power (1-beta) (default 0.8)
ao eval suite verdict
Compute the §6.5 paired cluster-bootstrap verdict
ao eval suite verdict <suite-id> --arms a,b --inputs <bootstrap-inputs.json> [flags]
Flags:
--B int Bootstrap resamples (default 10000)
--arms string Comma-separated arm ids (default: from suite varied_axis)
-h, --help help for verdict
--inputs string Path to canonical bootstrap-inputs JSON (REQUIRED)
--mde float Minimum detectable effect (used for inconclusive_high_variance)
--n-required int Override n_required (default: derived from suite power block)
ao eval task
Operate on the §3 Task primitive of the eval substrate.
ao eval task [command]
ao eval task add
Register a Task by copying its yaml + samples into the substrate
ao eval task add <task.yaml> [flags]
ao eval task list
List registered Task ids
ao eval task list [flags]
ao eval task run
Opens a new Run under $AGENTOPS_EVALS_ROOT/runs/
ao eval task run <task-id> [flags]
Flags:
--allow-weak-labels Allow runs against confidence=weak ground-truth rows (gate #7)
--cross-spec Allow ModelSpec drift (gate #4)
--dry-run Run gates and exit without writing a Run manifest
--ground-truth string Ground-truth row id (head of supersession chain)
--harness string Harness id (recorded into manifest)
--harness-dir string Path to harness source dir for snapshot + gate #8
-h, --help help for run
--inspect-command string Inspect command recorded into the Run manifest (not executed yet)
--inspect-version string Inspect AI version stamped into manifest (default "0.3.216")
--model-spec string ModelSpec id (already captured via ao eval models capture)
--n-samples int Override Suite.n_samples
--quick Mark Run as quick_session=true (excluded from --vs auto-baseline pool)
--rig-id string Rig identifier stamped into the Run manifest
--sample-split string Sample split (dev|holdout); default from suite
--seeds string Comma-separated seeds (>=3, per §4)
--suite string Suite id or path to suite.yaml (required)
ao eval task show
Print a registered Task summary
ao eval task show <task-id> [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 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
List or create the executable-spec scenarios linked to GOALS.md directives.
ao goals scenarios [flags]
Flags:
--create string Create a scenario from this goal description and link it to --directive
--directive int Directive display number (filter when listing, target when creating)
--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
--source string Source for a created scenario (human, agent, prod-telemetry) (default "human")
--status string Status for a created scenario (active, draft, retired) (default "draft")
--strict With --lint, exit non-zero on warnings as well as errors
--threshold float Satisfaction threshold for a created scenario (default 0.8)
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 goals add
Add a new goal
ao goals add <id> <check-command> [flags]
Aliases:
add, a
Flags:
--description string Goal description
-h, --help help for add
--type string Goal type (health, architecture, quality, meta)
--weight int Goal weight (1-10) (default 5)
ao goals init
Bootstrap a new GOALS.md file
ao goals init [flags]
Flags:
-h, --help help for init
--non-interactive Use defaults without prompting
--template string Goal template (go-cli, python-lib, web-app, rust-cli, generic)
ao goals meta
Run and report meta-goals only
ao goals meta [flags]
ao goals migrate
Migrate goals between formats.
ao goals migrate [flags]
Aliases:
migrate, mg
Flags:
-h, --help help for migrate
--to-md Convert GOALS.yaml to GOALS.md format
ao goals prune
Remove goals referencing nonexistent files
ao goals prune [flags]
Aliases:
prune, p
ao goals steer
Manage directives
ao goals steer [command]
ao goals steer add
Add a new directive
ao goals steer add <title> [flags]
Flags:
--description string Directive description (required)
-h, --help help for add
--steer string Steer direction (increase, decrease, hold, explore) (default "increase")
ao goals steer apply
Apply the top re-steer recommendation to GOALS.md via the non-lossy directive-block patcher. Requires policy auto_apply:true AND explicit human confirmation (interactive prompt, or --auto --yes for scripts). A run without confirmation never changes GOALS.md.
ao goals steer apply [flags]
Flags:
--auto Equivalent to --yes: explicit non-interactive consent to apply
-h, --help help for apply
--policy string Re-steer policy path (default: docs/re-steer-policy.json)
--yes Pre-confirm the apply for non-interactive/scripted use (explicit consent)
ao goals steer prioritize
Move a directive to a new position
ao goals steer prioritize <number> <new-position> [flags]
ao goals steer recommend
Run the re-steer policy engine over the verdict ledger and print recommended directive mutations and skip reasons. GOALS.md is never modified. Use ao goals steer apply to apply a recommendation.
ao goals steer recommend [flags]
Flags:
-h, --help help for recommend
--policy string Re-steer policy path (default: docs/re-steer-policy.json)
ao goals steer remove
Remove a directive by number
ao goals steer remove <number> [flags]
ao land
Land one reviewed bead the trusted way, in one verb. 'ao land' builds NOTHING
ao land <bead-id> [flags]
ao session
Session lifecycle operations.
ao session [command]
Subcommands:
ao session bootstrap
Universal init prompt for any agent spawned into an AgentOps repo.
ao session bootstrap [flags]
Flags:
--json Emit the full status object as JSON (default: 1-line summary).
--no-mail Skip the mcp-agent-mail probe even if the MCP server is reachable.
--robot Same as --json but tighter exit-code contract for hooks.
-h, --help help for bootstrap
--json Emit machine-readable status as JSON
--no-mail Skip the mcp-agent-mail probe
--robot Robot mode: JSON output with tight exit-code contract for SessionStart hooks
ao session close
Close a session by forging its transcript, extracting learnings,
ao session close [flags]
Flags:
--auto-extract Extract lightweight learnings (quality-filtered) and write handoff artifact
-h, --help help for close
--session string Session ID to close (default: most recent transcript)
ao session handoff
Write a structured JSON handoff artifact that captures session context
ao session handoff [summary] [flags]
Flags:
--collect Auto-collect git/bead state into the artifact
--dry-run Print artifact to stdout without writing file
--epic string Epic ID for RPI context
--goal string What the session was working on
-h, --help help for handoff
--no-kill Write artifact without restarting the session via tmux
--rpi-phase int RPI phase number (populates RPI context, sets type=rpi)
--run-id string Run ID for RPI context
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
Rehydrate emits a lane's re-bootstrap brief from the most recent handoff
ao session rehydrate [flags]
Flags:
-h, --help help for rehydrate
--json Emit the raw handoff artifact as JSON
--peek Read the brief without marking the handoff consumed
ao session state
Manage the durable AgentOps state-memory contract.
ao session state [command]
ao session state admit
Admit one independently reviewed Finding candidate into .ao/accepted
ao session state admit --candidate <path> --verdict <path> [flags]
Flags:
--candidate string Path to an .ao Finding candidate JSON file (required)
--destination string Destination under .ao/accepted/findings/ (default: finding id)
-h, --help help for admit
--max-age-days int Maximum age for reviewed findings (default 30)
--verdict string Path to an independent admission verdict JSON file (required)
ao session state candidate
Inspect inert .ao state candidates
ao session state candidate [command]
ao session state candidate validate
Validate an inert .ao Finding candidate and print its digest
ao session state candidate validate <path> [flags]
ao session state doctor
Diagnose state memory health
ao session state doctor [flags]
ao session state review-request
Emit the digest-bound review request for a Finding candidate
ao session state review-request <candidate> [flags]
ao session state validate
Validate state memory JSON files against their schemas
ao session state validate <file> [file...] [flags]
ao session state verify
Verify .ao state schemas, fixtures, accepted findings, and ledger rows
ao session state verify [flags]
Flags:
--all Verify all .ao state authority surfaces
-h, --help help for verify
ao validate
Run a deterministic validation gate over RPI artifacts and emit a single
ao validate [flags]
Flags:
--bead string Validate artifacts bound to a bead id
--changes strings Explicit files to validate
--gate Exit-code mode: 0=PASS/WARN, 1=FAIL, 2=error
-h, --help help for validate
--json Structured verdict (honored in both modes)
--lenient Allow legacy artifacts without schema_version
--lenient-expiry int Days until lenient bypass expires (default 90)
--strict Promote WARN to FAIL (exit 1)
--warn-as-fail Alias for --strict
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 beads
Commands that help maintain the bd issue tracker alongside the main
ao beads [command]
Subcommands:
ao beads audit
Audits open and in-progress beads for backlog hygiene issues.
ao beads audit [flags]
Flags:
--auto-close Close likely-fixed beads when commit or file-change evidence is found
-h, --help help for audit
--json Emit audit report as JSON
--strict Exit 1 when any likely-fixed, likely-stale, or consolidatable bead is found
ao beads cluster
Analyzes open beads for domain overlap and suggests consolidation groups.
ao beads cluster [flags]
Flags:
--apply Reparent non-representative beads under the cluster representative
-h, --help help for cluster
--json Emit cluster report as JSON
ao beads dir
Print the BEADS_DIR path AgentOps will use for br subprocesses.
ao beads dir [flags]
Flags:
-h, --help help for dir
--json Emit {beads_dir, source} as JSON
--require Fail closed: exit non-zero (printing nothing to stdout) unless the resolved directory holds a br ledger
ao beads epic-status
Emit a deterministic "is this epic/wave actually done" verdict, replacing
ao beads epic-status <epic-id> [flags]
Flags:
-h, --help help for epic-status
--json Emit the verdict as a JSON object instead of a human-readable line.
--terminal Map the verdict to the process exit code (0 terminal / 2 not-terminal / 3 skipped).
ao beads exec
Forward a bead command verbatim to the resolved beads tracker (bd or br),
ao beads exec [args...] [flags]
ao beads harvest
Reads a closed bead via 'bd show
ao beads harvest <bead-id> [flags]
Flags:
--dry-run Print the learning content to stdout without writing a file
-h, --help help for harvest
--out-dir string Directory to write the learning file into (default ".agents/learnings")
ao beads lint
Runs 'ao beads verify' on every bead matching a status filter and
ao beads lint [flags]
Flags:
-h, --help help for lint
--json Emit lint report as JSON
--status string bd status filter (open, closed, all) (default "open")
ao beads resume
Transfers a stale claim via 'br update
ao beads resume <bead-id> [flags]
Flags:
--agent string New claimant id (defaults to BEADS_ACTOR env var, else ao-beads-resume).
-h, --help help for resume
--json Emit the claim_transferred event to stdout (always written to ledger).
--ledger string Path to the provenance ledger (relative to repo root). (default "docs/provenance/ledger.jsonl")
ao beads scenarios
Turn a bead's free-text acceptance criteria into structured Gherkin
ao beads scenarios [command]
ao beads scenarios extract
Read a bead's acceptance criteria via 'bd show
ao beads scenarios extract <bead-id> [flags]
Flags:
--force Extract even when the bead already has a '## Scenarios' block
-h, --help help for extract
--json Emit extracted scenarios as JSON (data on stdout) instead of a Gherkin block
--write After printing the block and an operator y/N confirmation, append it to the bead via 'bd update'
ao beads scenarios validate
Read a bead via 'bd show
ao beads scenarios validate <bead-id> [flags]
Flags:
-h, --help help for validate
--json Emit a structured validation verdict as JSON on stdout
ao beads stale-claims
Lists in_progress beads whose claim activity is older than --threshold.
ao beads stale-claims [flags]
Flags:
-h, --help help for stale-claims
--json Emit JSON array conforming to stale-claim-event.v1 (event_type: stale_detected).
--threshold float Staleness threshold in hours (claim updated more than N hours ago). (default 4)
ao beads tracker
Detect which beads tracker AgentOps will drive here and how it was
ao beads tracker [flags]
Flags:
-h, --help help for tracker
--json Emit {tracker, binary, ledger_dir, source} as JSON
ao beads verify
Reads a bead description via 'bd show
ao beads verify <bead-id> [flags]
Flags:
-h, --help help for verify
--json Emit verification report as JSON instead of human-readable text
--verbose Include FRESH citations in the output (default: stale only)
ao beads verify-acceptance
Read beads via br (never the retired bd) and check each bead carries the
ao beads verify-acceptance <bead-id>... [flags]
Flags:
-h, --help help for verify-acceptance
--json Emit verdicts as JSON
--strict Exit non-zero on any FAIL or UNDEFINED verdict
ao membrane
Operate the self-improving membrane (epic age-cwo).
ao membrane [command]
Subcommands:
ao membrane calibrate
Run the standing membrane calibration harness (age-e508.2): measure the current
ao membrane calibrate [--membrane-label <adapter>] [--membrane-cmd <c>] [--out-dir <dir>] [flags]
ao membrane catch
Record a catch out-of-band: a REFUTED gate-verdict carrying the bounded
ao membrane catch --bead <id> (--domain <bc> --reason <what> | --evidence <file>) [--scope head|staged|upstream] [--base <sha>] [--class <slug>] [--paths f1,f2] [--detector-pattern <re> --globs <g> --detector-kind <k>] [flags]
Flags:
--base string With --scope upstream: exact reviewed ancestor commit (default: configured-upstream merge-base)
--bead string Bead id the catch was found on (required)
--class string Optional SEMANTIC class slug (e.g. stale-retired-surface). When set it keys the class CROSS-BEAD (the same label on different beads is ONE class), instead of the bead-drifting reason. Slug shape: lowercase [a-z0-9] words joined by '-'
--detector-kind string Optional detector kind (e.g. regex)
--detector-pattern string Optional regex that mechanically detects this class (makes it a compile candidate)
--domain string Bounded-context / work-class tag (required)
--evidence string Pawl-review evidence file: derive --reason (two-tier REFUTED salvage), --domain (first changed file's top dir) and --paths (changed files, first 20); explicit flags win
--globs string Optional path globs scoping the detector pattern
--head string Commit sha the catch was found at (default: git HEAD)
-h, --help help for catch
--mode string Pawl diversity mode: fresh-context (default) | multi-model | deterministic
--paths strings Concrete repo-relative file paths the catch touches (comma-separated or repeated)
--reason string What was caught — the defect (required; the class reason when no --class given)
--run string Run id (default: membrane-catch)
--scope string With --evidence: changed-file scope — head (the --head commit), staged (the index), or upstream (configured-upstream merge-base through --head) (default "head")
ao membrane derive-checks
Derive membrane checks from escapes in a run
ao membrane derive-checks --run <id> [flags]
Flags:
--dry-run Report what would be derived without writing files
--force Overwrite existing derived artifacts
-h, --help help for derive-checks
--run string Run id to scan for escapes (required)
ao membrane digest
Mine the ABUNDANT catch corpus into a single GLOBAL top-N recurring-defect
ao membrane digest [--top N] [--json] [--deltas --since <date>] [flags]
Flags:
--deltas Per-class recurrence before vs since --since (read-only; for the producer-defect register)
-h, --help help for digest
--include-placeholders Include reason-less placeholder classes (e.g. "pawl-review REFUTED (see evidence)") for corpus auditing; excluded by default so the checklist stays actionable
--json Also print the ranked digest as JSON (the checklist file is written either way)
--since string Cutoff for --deltas: an ISO date (2026-07-08, UTC midnight) or RFC3339 timestamp — typically a producer fix's land date
--top int How many top recurring catch classes to include (default 10)
ao membrane recall
Recall the membrane's accumulated memory for one bounded context: every
ao membrane recall --domain <domain> [flags]
Flags:
--domain string Bounded-context / work-class tag to recall escapes for (required)
-h, --help help for recall
--include-catches Also surface CATCH classes in the domain (the abundant memory; escapes are rare)
--json Emit the recalled escapes as JSON
--paths strings With --include-catches, narrow to catches whose affected_paths overlap these files
ao membrane triage
Read the CATCH corpus and report whether the compiler thesis has fuel — with a
ao membrane triage [flags]
Flags:
-h, --help help for triage
--json Emit the triage result as JSON
ao close
Close a bead and persist the explicit ledger/evidence paths
ao close <id> <commit-message> <evidence-ref> [paths...] [flags]
ao council-gate
Fail-closed two-plus judge verdict aggregation
ao council-gate <verdict1> <verdict2> [...] [flags]
ao done
Close a bead through the membrane's bookkeeping half: the close reason is
ao done <bead-id> [flags]
Flags:
--force-no-verdict Close without a verdict, stamping an explicit UNVERIFIED marker
-h, --help help for done
--json Emit machine-readable JSON (stdout-as-data)
-r, --reason string Close reason prose (the verdict stamp is appended) (default "Done")
--sha string Commit sha (or >=7-char prefix) the bead landed as (default: HEAD at cwd)
ao governor
The slow-loop setpoint that keeps the self-improving membrane from oscillating
ao governor [command]
Subcommands:
ao governor budget
SPC.1 (control-loop-model.md §4). The ERROR BUDGET is the top governor: inside
ao governor budget [--json] [--window N] [--tolerance T] [--min-confirmed N] [flags]
Flags:
-h, --help help for budget
--json Emit the verdict as JSON
--min-confirmed int Special-cause floor: min confirmed in window before harden can fire; 0 = default
--tolerance float Tolerated escape rate T; 0 = default
--window int Rolling window size (gate-verdicts); 0 = default
ao governor noise-band
SPC.2 (control-loop-model.md §4). The membrane adjusts ONLY on a special-cause
ao governor noise-band [--json] [--window N] [--limit K] [flags]
Flags:
-h, --help help for noise-band
--json Emit the verdict as JSON
--limit int Special-cause control limit K (escapes per domain in window); 0 = default
--window int Rolling window size (gate-verdicts); 0 = default
ao help
Help provides help for any command in the application.
ao help [command] [flags]
ao pawl
The pawl is AgentOps's acceptance gate: a change reaches "done" only with an
ao pawl [command]
Subcommands:
ao pawl review
Wrap scripts/pawl-review.sh and surface it on the ao CLI. Dispatches the codex
ao pawl review <bead-id> [--scope head|staged|upstream] [--base <sha>] [--converge] [--strict] [--author-family <fam>] [--context <s>] [--smoke <cmd>] [flags]
ao pawl doctor
Read-only standing pawl preflight: assert swarm binary (ntm-first), session, pane cwd/model, trust prompts, readiness, and evidence policy
ao pawl doctor [--json] [--expected-cwd PATH] [--expected-claude-model MODEL] [--expected-codex-model MODEL] [flags]
ao pawl down
Tear down the standing pawl-service (no orphan panes)
ao pawl down [flags]
ao pawl health
Per-pane liveness/readiness of the standing pawl-service + the membrane tier
ao pawl health [--json] [flags]
ao pawl metrics
p50/p95 route latency + agreement-rate SLOs over the recorded routes
ao pawl metrics [--json] [flags]
ao pawl reap
Tear down the standing pawl-service iff idle > PAWL_IDLE_TTL (substrate/cron schedules it; no-op otherwise)
ao pawl reap [flags]
ao pawl route
Route a review packet to the warm cross-family panel; require tier-appropriate agreement, record the verdict
ao pawl route <bead> <packet> [pr] [flags]
ao pawl smoke
Alias for pawl doctor: non-mutating readiness smoke before routing real reviews
ao pawl smoke [--json] [--expected-cwd PATH] [--expected-claude-model MODEL] [--expected-codex-model MODEL] [flags]
ao pawl up
Stand up the standing pawl-service — adaptive: probe installed families (claude/codex/agy) and form the strongest membrane; pin with --dual/--tri/--models. Readiness-gated, idempotent
ao pawl up [--dual|--tri|--models a,b,c] [flags]
ao plan-pawl
The plan-pawl is the multi-model pawl applied to a discovery PLAN artifact
ao plan-pawl [command]
Subcommands:
ao plan-pawl decide
Apply the deterministic quorum/round/breaker rules to one round of judge
ao plan-pawl decide [flags]
Flags:
--dir string directory of judge verdict *.json files
-h, --help help for decide
--json emit the decision as JSON
--judgment-flag a reviewer raised an explicit value/irreversibility judgment (hard breaker)
--max-rounds int max rounds before the max-attempts breaker trips (<=0 = unbounded) (default 3)
--oscillation the same failure has repeated (hard breaker)
--round int current round (1-based) (default 1)
--verdict stringArray judge verdict: family:disposition[:warnclass] (repeatable)
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 emit-landed
Read the commit(s) being landed and append a schema-valid, hash-chained
ao provenance emit-landed [flags]
Flags:
--commit string Single commit-ish to emit edges for (default HEAD when no --range)
--dry-run Resolve and print edges without writing the ledger
-h, --help help for emit-landed
--json Emit appended edges as JSON
--range string Git revision range (e.g. origin/main..HEAD); emits for every commit in it
--trunk-ref string Require each commit to be an ancestor of this ref (e.g. origin/main) before emitting; merge_sha uses the resolved full OID
ao provenance emit-verdict
Read a pawl-verdict JSON artifact (.agents/pawl-verdicts/
ao provenance emit-verdict [flags]
Flags:
--dry-run Resolve and print edges without writing the ledger
--file string Path to the pawl-verdict JSON file (required)
-h, --help help for emit-verdict
--json Emit appended edges as JSON
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 ledger-reader-version
Print, as a single bare integer, the ledger-reader capability level this ao
ao provenance ledger-reader-version [flags]
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
Read the provenance ledger and report the navigator's current position:
ao provenance position [flags]
Flags:
-h, --help help for position
--json Emit machine-readable JSON (stdout-as-data)
ao provenance reconcile
Scan the pawl-verdicts dir (.agents/pawl-verdicts/*.json) and, for every
ao provenance reconcile [flags]
Flags:
--dir string Verdicts dir (default: <repo>/.agents/pawl-verdicts)
--emit Re-emit missing ledger edges for unbound verdicts
--force Run even with an uncommitted ledger worktree
-h, --help help for reconcile
--json Emit the reconcile result as JSON
ao provenance show
Render the human story of one change from the committed provenance
ao provenance show <sha|bead-id> [flags]
Flags:
-h, --help help for show
--json Emit machine-readable JSON (stdout-as-data)
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 ready
Print harness-neutral ready bead state as JSON
ao ready [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
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/
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
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 retire
One deterministic retire operation for a skill.
ao skills retire <slug> [flags]
Flags:
--allow-critical Allow retiring a slug listed in docs/contracts/critical-skills.txt
--dry-run Report every planned operation without mutating anything
-h, --help help for retire
--into string Target skill the retiree merges into (historical state merged-into; default: cut)
--json Emit a machine-readable JSON report
--no-regen Skip the regen scripts after the ledger flip
ao verdict-gate
Reject verdicts without commands and independent judge identity
ao verdict-gate <file|-> [flags]
ao verify
Run an independent cross-family review of your change and, on CONFIRMED, write
ao verify [command]
Subcommands:
ao verify init
Install a pre-push hook into THIS git repository that refuses any push to
ao verify init [--remove] [flags]
Flags:
-h, --help help for init
--remove Uninstall the ratchet, restoring any pre-existing pre-push hook byte-identically
ao verify receipts
Render the membrane-receipts proof page for THIS git repository from its
ao verify receipts [flags]
ao verify stats
Report the COST of verified-done from the committed provenance ledger
ao verify stats [flags]
Flags:
--days int Trailing window in days for the trend section (<=0 = all time) (default 30)
-h, --help help for stats
--json Emit machine-readable JSON (stdout-as-data)
--ledger string Ledger path override (default: repo docs/provenance/ledger.jsonl)
ao yield
Record durable, append-only, bead-keyed operational events for the
ao yield [command]
Subcommands:
ao yield emit
Append one operational event keyed by bead to the yield ledger
ao yield emit <accept|gate-verdict|usage> --bead <id> --run <id> [--json <body> | typed flags] [flags]
Flags:
--bead string bead id this event is keyed to (required)
-h, --help help for emit
--json string the typed body object as a single JSON blob
--run string factory run/cycle id (required)
--ts string optional RFC3339 timestamp; defaults to now (UTC)
ao yield gauge
Load the yield ledger, compute the dynamo yield vector for one run, and
ao yield gauge --run <id> [--json] [--c-delta <float>] [flags]
Flags:
--c-delta float ag-8p8o's published corpus delta (C); omit to report C as pending
-h, --help help for gauge
--json emit the computed gauges as JSON for machine consumption
--run string factory run/cycle id to compute gauges for (required)
ao yield report
Print what an autonomous loop did — and what it parked for you — without
ao yield report [--since <RFC3339|duration>] [--json] [flags]
Flags:
-h, --help help for report
--json emit the full report struct as JSON
--since string cutoff: an RFC3339 instant or a duration lookback like 8h (default 24h)
ao yield tokens
Parse a Claude Code or Codex session transcript and sum the real token
ao yield tokens --transcript <path> [--json] [flags]
Flags:
-h, --help help for tokens
--json emit {"tokens_in":N,"tokens_out":M} as JSON
--pair emit two whitespace-separated values: tokens_in tokens_out
--transcript string path to a session transcript (JSONL) to sum tokens from (required)