Auto-generated by
scripts/generate-cli-reference.sh. Do not edit manually. Re-run the script to update.
--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
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
Create local evidence and verdict directories, then add one commented,
ao init [flags]
AgentOps is a small semantic evidence layer around agent work.
ao quick-start [flags]
Print the machine-readable contract for the whole ao CLI as JSON.
ao capabilities [flags]
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:
Print the machine-readable doctor contract (JSON)
ao doctor capabilities [flags]
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
Expand a single finding with full evidence
ao doctor explain <finding-id> [flags]
Run detectors, then apply fixers (backs up before every mutation)
ao doctor fix [flags]
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)
Cheap one-line liveness summary
ao doctor health [flags]
List runs in .doctor/runs/
ao doctor ls [flags]
Print the paste-ready agent handbook (Markdown)
ao doctor robot-docs [flags]
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)
Run ordinary deterministic repository checks.
ao gate [command]
Subcommands:
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")
Read text on stdin, apply the canonical secret redactor (the same
ao redact [flags]
Print a paste-ready, agent-targeted handbook for the whole ao CLI.
ao robot-docs [flags]
Display the content-addressed intent and verdict evidence stored by AgentOps.
ao status [flags]
Display the version, build information, and runtime details.
ao version [flags]
Run deterministic AgentOps evaluation suites and compare run records.
ao eval [command]
Subcommands:
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
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")
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
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
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")
Outcomes is a derived projection of the locked eval substrate (SCHEMA.md), never an alternate authority.
ao eval outcomes [command]
Compile a holdout-safe Outcomes rubric payload from a locked Task + criteria
ao eval outcomes compile <input.json> [flags]
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)
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)
Create, list, validate, and evaluate holdout scenarios stored in .agents/holdout/.
ao eval scenario [command]
Author a holdout scenario from a goal description
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)
Evaluate directive-linked scenarios and record satisfaction results
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)
Initialize .agents/holdout/ directory for scenario storage
ao eval scenario init [flags]
List holdout scenarios
ao eval scenario list [flags]
Flags:
-h, --help help for list
--status string Filter by status (active, draft, retired)
Validate holdout scenarios against schema
ao eval scenario validate [flags]
Run a knowledge-reuse holdout scenario with vs. without the gold pull (the discriminating A/B)
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)
Aggregate moat-eligible scenario A/B scorecards into a publication verdict
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)
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
Suite-level operations against the §6.5 statistical contract.
ao eval suite [command]
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)
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)
Operate on the §3 Task primitive of the eval substrate.
ao eval task [command]
Register a Task by copying its yaml + samples into the substrate
ao eval task add <task.yaml> [flags]
List registered Task ids
ao eval task list [flags]
Open a new Run manifest for ; refuses on gate failure
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, resolved from <evals-root>/models/<id>/spec.yaml
--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)
Print a registered Task summary
ao eval task show <task-id> [flags]
Prepare and qualify the stock Gas City maintainer pack without owning a pack.
ao gc [command]
Subcommands:
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)
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)
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)
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:
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)
Validate GOALS.yaml structure and wiring
ao goals validate [flags]
Aliases:
validate, v
Compare snapshots for regressions
ao goals drift [flags]
Aliases:
drift, d
Export latest snapshot as JSON (for CI)
ao goals export [flags]
Aliases:
export, e
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)
Run and report meta-goals only
ao goals meta [flags]
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
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
Inspect or export session evidence
ao session [command]
Subcommands:
Report local orientation files without starting runtimes, probing
ao session bootstrap [flags]
Flags:
-h, --help help for bootstrap
--json Emit JSON
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
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
Generate shell completion scripts for ao.
ao completion [bash|zsh|fish|powershell]
View and manage AgentOps configuration.
ao config [flags]
Flags:
-h, --help help for config
--show Show resolved configuration with sources
Append and inspect generic, evidence-backed relationships between
ao provenance [command]
Subcommands:
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)
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
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
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)
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
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
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
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
Tooling for the skills/ source-of-truth and its skills-codex/
ao skills [command]
Subcommands:
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)
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
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)
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
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
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)
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
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)
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
Tooling for the top-level workflows/ source-of-truth: the Claude-harness
ao workflows [command]
Subcommands:
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
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
Knowledge flywheel operations and status.
ao flywheel [command]
Subcommands:
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")
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")
Help provides help for any command in the application.
ao help [command] [flags]