ao CLI Reference
June 22, 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 demo
Run a demonstration of AgentOps as the engineering operating system
ao demo [flags]
Flags:
--concepts Explain product model
-h, --help help for demo
--quick 2-minute council-first overview
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 seed
Plant the AgentOps seed in any repository.
ao seed [path] [flags]
Flags:
--force Overwrite existing seed files
-h, --help help for seed
--template string Goal template: go-cli, python-lib, web-app, rust-cli, generic (default: auto-detect)
ao anti-patterns
List learnings that have been marked as anti-patterns.
ao anti-patterns [flags]
ao badge
Display a visual badge showing knowledge flywheel health status.
ao badge [flags]
ao canon
The team-knowledge canon is the trusted set of learnings a team shares.
ao canon [command]
Subcommands:
ao canon cite
Record that you used a learning (the 'useful' signal)
ao canon cite <entry-id> [flags]
Flags:
--as string acting actor override ("Name" or "Name <email>"); else AGENTOPS_ACTOR / git
-h, --help help for cite
--path string path to the learning file (required)
--query string search query that surfaced the learning
--session string session ID
ao canon promote
Promote an earned learning into the team canon
ao canon promote <entry-id> [flags]
Flags:
--force promote despite an unmet gate (records the override loudly)
-h, --help help for promote
--path string path to the learning file (required)
ao canon status
Show promotion eligibility for one or all tracked entries
ao canon status [entry-id] [flags]
ao canon verify
Record that you independently checked a learning and whether it holds.
ao canon verify <entry-id> [flags]
Flags:
--as string acting actor override ("Name" or "Name <email>"); else AGENTOPS_ACTOR / git
--council obtain the verdict from an independent cross-vendor judge (cmd: AGENTOPS_CANON_VERIFIER_CMD) instead of asserting it
-h, --help help for verify
--method string how it was checked: manual|ao-verify|council|cross-model (default "manual")
--path string path to the learning file (required)
--receipt string evidence you independently gathered (gate log, file:line, hash)
--verdict string confirmed|refuted (default "confirmed")
ao capabilities
Print the machine-readable contract for the whole ao CLI as JSON.
ao capabilities [flags]
ao ci
Operations on CI run history via the typed BC2 CIStatusPort. The 'latest' subcommand wraps 'gh run list --commit
ao ci [command]
Subcommands:
ao ci latest
Get the most recent CI run for a given commit SHA via the typed
ao ci latest <sha> [flags]
ao ci recent
List recent CI runs (any SHA) via productionCIStatus. Default
ao ci recent [flags]
Flags:
-h, --help help for recent
--limit int max runs to emit (0 = all up to port cap of 50) (default 10)
ao citation
Verify citation freshness via the typed BC1 CitationPort. Useful for cross-repo citation auditing and dream-loop staleness checks.
ao citation [command]
Subcommands:
ao citation verify
Verify a single citation (file, function, or symbol) against HEAD
ao citation verify --kind <file|function|symbol> --raw <text> [flags]
Flags:
-h, --help help for verify
--kind string citation kind (required: file|function|symbol)
--raw string citation text to verify (required)
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 constraint
Manage constraints compiled from promoted findings.
ao constraint [command]
Subcommands:
ao constraint activate
Change constraint status from draft to active
ao constraint activate <id> [flags]
ao constraint list
List all constraints with status
ao constraint list [flags]
ao constraint publish
Export the ACTIVE constraints to docs/constraints/published.json (tracked + committed),
ao constraint publish [flags]
ao constraint retire
Change constraint status from active to retired
ao constraint retire <id> [flags]
ao constraint review
List constraints compiled >90 days ago without recent citation
ao constraint review [flags]
ao contradict
Scan learnings and patterns for potential contradictions using keyword overlap heuristics.
ao contradict [flags]
ao curate
Curate manages the knowledge curation pipeline: catalog artifacts,
ao curate [command]
Subcommands:
ao curate catalog
Catalog a knowledge artifact
ao curate catalog <path> [flags]
ao curate status
Show curation pipeline status
ao curate status [flags]
ao curate verify
Verify gate health against baselines
ao curate verify [flags]
Flags:
-h, --help help for verify
--since string Filter to changes within duration (e.g. 24h, 7d)
ao dedup
Scan learnings and patterns for near-duplicates using normalized content hashing.
ao dedup [flags]
Flags:
-h, --help help for dedup
--merge Auto-resolve duplicates: keep highest utility, archive the rest
--yes Skip the interactive confirmation prompt for large merges (for hooks/CI)
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 flywheel
Knowledge flywheel operations and status.
ao flywheel [command]
Subcommands:
ao flywheel close-loop
Close the knowledge flywheel loop by chaining:
ao flywheel close-loop [flags]
Flags:
-h, --help help for close-loop
--pending-dir string Pending directory to ingest from (default ".agents/knowledge/pending")
--quiet Suppress non-essential output (hook-friendly)
--threshold string Minimum age for auto-promotion (default: 24h) (default "24h")
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 gate
Check the post-structural readiness gate before retrieval-expansion work.
ao flywheel gate [flags]
Flags:
--corpus string Benchmark corpus directory (defaults to repo testdata)
-h, --help help for gate
ao flywheel nudge
Returns structured JSON combining:
ao flywheel nudge [flags]
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 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 (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 harness
Inspect the sync state between the canonical skills/ tree and the skills-codex/ mirror via the typed BC5 HarnessPort. Useful as a typed alternative to scripts/audit-codex-parity.sh for drift detection.
ao harness [command]
Subcommands:
ao harness status
Emit HarnessSkillSync entries via the typed BC5 HarnessPort
ao harness status [--skill <name>] [--out-of-sync-only] [flags]
Flags:
-h, --help help for status
--out-of-sync-only emit only entries with OutOfSync=true
--skill string filter to one skill name (empty = all)
ao loop
Operations on the /evolve cycle history and related Loop bounded-context state. The 'history' subcommand reads .agents/evolve/cycle-history.jsonl via the typed BC3 LoopReaderPort.
ao loop [command]
Subcommands:
ao loop append
Append a new entry to .agents/evolve/cycle-history.jsonl via the
ao loop append --mode <m> --result <r> [flags]
Flags:
--commit string git commit SHA (optional)
--cycle int cycle number (0 = auto-assign max+1)
-h, --help help for append
--milestone string milestone note (optional)
--mode string cycle mode (required)
--result string cycle result: improved|harvested|unchanged|idle (required)
--trace-json string XP/BDD/TDD evidence trace as a JSON object — a file path or inline JSON (optional)
ao loop blocked
Record or inspect typed blocked-events emitted by the /evolve loop.
ao loop blocked [flags]
Flags:
--bead string Bead id the agent was working on (write mode, optional)
--clear string Clear mode: delete entries for the given cycle id (operator-only)
--cycle string Override cycle-id (write mode; defaults to date-derived counter)
-h, --help help for blocked
--json Read mode: emit JSON instead of human-readable text
--ladder-step-failed int Ladder step that failed (write mode, optional)
--list Read mode: list blocked events
--needed-context string Missing context description (write mode, optional)
--reason string Reason text (write mode)
--tail int Read mode: show last N entries (default 10)
ao loop converged
Evaluate the evolve loop's convergence STOP predicate via the typed
ao loop converged [flags]
Flags:
--fitness-baseline a fitness baseline artifact has been captured
--green-streak int current leading green CI streak (caller-supplied evidence)
-h, --help help for converged
--unconsumed-high-medium int current unconsumed HIGH+MEDIUM finding count
ao loop history
Read .agents/evolve/cycle-history.jsonl via the typed BC3 LoopReaderPort.
ao loop history [flags]
Flags:
--end int end cycle number (inclusive; 0 = unbounded)
-h, --help help for history
--latest emit only the latest entry
--limit int max entries to emit (0 = all)
--start int start cycle number (inclusive; 0 = unbounded)
ao loop hypothesis
Operations on the /evolve hypothesis ledger (.agents/evolve/hypotheses.jsonl) via the typed BC3 HypothesisLedgerPort.
ao loop hypothesis [command]
ao loop hypothesis append
Append a falsifiable hypothesis to .agents/evolve/hypotheses.jsonl
ao loop hypothesis append --id <id> --hypothesis <h> --measure <m> [flags]
Flags:
--check-at-cycle int future cycle that evaluates the measure
--cycle-landed int cycle the patch landed
-h, --help help for append
--hypothesis string expected effect of the patch
--id string unique hypothesis ID, e.g. H210.1 (required)
--measure string how the effect is verified
--patch string one-line description of what landed
--verdict string verdict: PENDING|VERIFIED|FALSIFIED (default "PENDING")
ao loop hypothesis list
Read .agents/evolve/hypotheses.jsonl via the typed BC3
ao loop hypothesis list [flags]
ao loop next-work
Run the 5-step next-work ladder and recommend a bead to claim.
ao loop next-work [flags]
Flags:
--bd-binary string Override path to the 'bd' binary (default: resolves via PATH)
-h, --help help for next-work
--include-operator-shape Do not filter operator-shape beads at step 1
--json Emit JSON instead of human-readable text
--mode string Execution contract: 'burst' (default) or 'loop' (default "burst")
ao loop verify
Audit .agents/evolve/cycle-history.jsonl integrity via the typed
ao loop verify [flags]
Flags:
-h, --help help for verify
--max-idle int max acceptable trailing idle/unchanged streak before flagging dormancy (default 5)
ao loop write-stop-marker
Write a DORMANT, STOP, or KILL marker under .agents/evolve/.
ao loop write-stop-marker [flags]
Flags:
-h, --help help for write-stop-marker
--marker string Marker name: dormant, stop, or kill
--mode string Execution contract: 'burst' or 'loop' (loop refuses unconditionally) (default "burst")
--reason string Reason text written to the marker file
ao maturity
Check and manage CASS (Contextual Agent Session Search) maturity levels.
ao maturity [learning-id] [flags]
Flags:
--apply Apply maturity transitions
--archive Move expired/evicted/curated files to archive (requires --expire, --evict, or --curate)
--curate Normalize metadata and identify low-signal or uncited stale learnings
--evict Identify eviction candidates (composite criteria)
--expire Scan for expired learnings
--global Operate on ~/.agents/learnings instead of the local workspace learnings
-h, --help help for maturity
--migrate-md Add default frontmatter to .md learnings missing utility field
--recalibrate Reset utility to 0.5 for all learnings
--scan Scan all learnings for pending transitions
--target-size string Size-budget eviction: when set with --evict, archive lowest-utility eligible files until the learnings hub falls below the target (e.g. 250M, 1G, 1024K)
--uncited-days int Archive provisional/candidate learnings with zero citations older than this many days when used with --curate (default 60)
ao metrics
Track and report on knowledge flywheel metrics.
ao metrics [command]
Subcommands:
ao metrics baseline
Capture a baseline snapshot of the knowledge flywheel.
ao metrics baseline [flags]
Flags:
--days int Period in days for metrics calculation (default 7)
-h, --help help for baseline
ao metrics cite
Record that an artifact was cited in this session.
ao metrics cite <artifact-path> [flags]
Flags:
--artifact-author string Author/owner identity of the cited artifact
--cited-by-agent string Agent identity recording the citation outcome
--cited-by-family string Model family of the citing/reviewing agent
-h, --help help for cite
--query string Search query that surfaced this artifact
--session string Session ID (auto-detected if not provided)
--type string Citation type: retrieved, used-in-final-artifact, helpful, harmful, refuted, applied, reference (default "reference")
--vendor string Model vendor attribution: claude, codex
ao metrics cite-report
Produce an aggregated report from citation data.
ao metrics cite-report [flags]
Flags:
--days int Period in days (default 30)
-h, --help help for cite-report
--json Output as JSON
ao metrics health
Display flywheel health metrics including escape velocity status.
ao metrics health [flags]
Flags:
-h, --help help for health
--namespace string Citation namespace to evaluate (primary by default) (default "primary")
ao metrics report
Display a formatted report of knowledge flywheel metrics.
ao metrics report [flags]
Flags:
--days int Period in days for metrics calculation (default 7)
-h, --help help for report
ao operator
Read and write operator intents via the typed BC4 OperatorPort. Intents are durable records of operator decisions (halt, rescope, handoff) appended to .agents/operator/intents.jsonl.
ao operator [command]
Subcommands:
ao operator list
Emit recorded OperatorIntents from .agents/operator/intents.jsonl
ao operator list [flags]
ao operator record
Append an OperatorIntent to .agents/operator/intents.jsonl via the
ao operator record --kind <kind> [--subject S] [--note N] [flags]
Flags:
-h, --help help for record
--kind string intent kind (required: halt|rescope|handoff|other)
--note string free-text note
--subject string intent subject (e.g., bd ID, file path)
ao pool
Manage knowledge candidates in quality pools.
ao pool [command]
Subcommands:
ao pool auto-promote
Automatically approve (and optionally promote) high-quality candidates
ao pool auto-promote [flags]
Flags:
-h, --help help for auto-promote
--include-gold Include gold-tier candidates when using --promote (default true)
--promote Also stage+promote eligible candidates into .agents/ (not just approval)
--threshold string Minimum age for auto-promotion (default: 24h) (default "24h")
ao pool batch-promote
Promote pending pool candidates that meet promotion criteria.
ao pool batch-promote [flags]
Flags:
--dry-run Show what would be promoted without executing
--force Promote all pending candidates regardless of criteria
--min-age Minimum age threshold (default: 24h)
--force Promote all pending regardless of criteria
-h, --help help for batch-promote
--min-age string Minimum age for promotion eligibility (default "24h")
ao pool ingest
Ingest pending learnings into the quality pool.
ao pool ingest [<files-or-globs...>] [flags]
Flags:
--dir string Directory to ingest from when no args are provided (default ".agents/knowledge/pending")
-h, --help help for ingest
ao pool list
List knowledge candidates filtered by tier and/or status.
ao pool list [flags]
Flags:
-h, --help help for list
--limit int Maximum results to return (default 50, 0 for unlimited) (default 50)
--offset int Skip first N results (for pagination)
--status string Filter by status (pending, staged, promoted, rejected)
--tier string Filter by tier (gold, silver, bronze)
-w, --wide Show full IDs without truncation
ao pool promote
Move a staged candidate to the knowledge base (.agents/learnings/ or .agents/patterns/).
ao pool promote <candidate-id> [flags]
ao pool reindex
Walk .agents/learnings/.md and .agents/patterns/.md, compute the
ao pool reindex [flags]
Flags:
--dry-run Print counts only; do not write to the index
-h, --help help for reindex
--json Emit structured JSON output
ao pool reject
Mark a candidate as rejected and move to rejected directory.
ao pool reject <candidate-id> [flags]
Flags:
-h, --help help for reject
--reason string Reason for rejection (required)
ao pool show
Show detailed information about a pool candidate.
ao pool show <candidate-id> [flags]
ao pool stage
Move a candidate from pending to staged status.
ao pool stage <candidate-id> [flags]
Flags:
-h, --help help for stage
--min-tier string Minimum tier threshold (default: bronze)
ao reconcile
Build a read-only reconciliation report for the current AgentOps repo.
ao reconcile [flags]
Flags:
-h, --help help for reconcile
--limit int maximum bead and run records to sample (default 80)
--repo string GitHub repo override for gh calls (owner/name)
--since string recent .agents evidence window (default "48h")
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 current state of AgentOps knowledge base.
ao status [flags]
ao version
Display the version, build information, and runtime details.
ao version [flags]
ao vibe-check
Run a comprehensive vibe-check analysis on your repository.
ao vibe-check [flags]
Aliases:
vibe-check, vibecheck
Flags:
--full Show all metrics and findings (verbose)
-h, --help help for vibe-check
--markdown Output as markdown report
--repo string Path to git repository (default ".")
--since string Time window for analysis (e.g., 7d, 30d, 90d) (default "7d")
ao autodev
Define, inspect, and validate the repo-local PROGRAM.md contract.
ao autodev [command]
Flags:
--file string Path to PROGRAM.md or AUTODEV.md (auto-detects PROGRAM.md then AUTODEV.md)
-h, --help help for autodev
Subcommands:
ao autodev init
Create a PROGRAM.md template
ao autodev init [objective] [flags]
Flags:
--force Overwrite an existing program file
-h, --help help for init
ao autodev show
Show the parsed PROGRAM.md contract
ao autodev show [flags]
ao autodev validate
Validate PROGRAM.md structure
ao autodev validate [flags]
ao codex
Codex lifecycle commands for the AgentOps knowledge flywheel.
ao codex [command]
Subcommands:
ao codex dispatch
Run a non-mutating Codex task packet and write a receipt
ao codex dispatch --packet <path> [flags]
Aliases:
dispatch, run
Flags:
-h, --help help for dispatch
--packet string Path to a Codex task packet JSON file
ao codex ensure-start
Ensure Codex startup context exists once per thread
ao codex ensure-start [flags]
Flags:
-h, --help help for ensure-start
--limit int Maximum artifacts to surface per category (default 3)
--no-maintenance Skip safe close-loop maintenance on start
--query string Optional startup query (defaults to the current Codex thread name)
ao codex ensure-stop
Ensure Codex closeout runs once per thread
ao codex ensure-stop [flags]
Flags:
--auto-extract Write lightweight learnings and handoff artifacts during closeout (default true)
--close-loop Run mutating flywheel close-loop maintenance after forging
-h, --help help for ensure-stop
--no-close-loop Skip flywheel close-loop maintenance after forging
--no-history-fallback Disable history.jsonl fallback when no archived Codex transcript exists
--session string Codex session ID to close (defaults to the active thread)
--transcript string Explicit transcript path to forge instead of runtime discovery
ao codex image-health
Run read-only Codex image and runtime health checks
ao codex image-health [flags]
Flags:
--check-timeout duration Per-check timeout budget for image health checks (default 30s)
-h, --help help for image-health
ao codex start
Start a Codex session with explicit flywheel maintenance (fallback for pre-v0.115.0)
ao codex start [flags]
Flags:
-h, --help help for start
--limit int Maximum artifacts to surface per category (default 3)
--no-maintenance Skip safe close-loop maintenance on start
--query string Optional startup query (defaults to the current Codex thread name)
ao codex status
Show Codex lifecycle health (native hooks detected when available)
ao codex status [flags]
Flags:
--days int Citation window in days for Codex lifecycle health (default 7)
-h, --help help for status
ao codex stop
Close a Codex session explicitly (fallback for pre-v0.115.0)
ao codex stop [flags]
Flags:
--auto-extract Write lightweight learnings and handoff artifacts during closeout (default true)
--close-loop Run mutating flywheel close-loop maintenance after forging
-h, --help help for stop
--no-close-loop Skip flywheel close-loop maintenance after forging
--no-history-fallback Disable history.jsonl fallback when no archived Codex transcript exists
--session string Codex session ID to close (defaults to the active thread)
--transcript string Explicit transcript path to forge instead of runtime discovery
ao cron
Compatibility shims for cron-fire scheduling surfaces that now belong
ao cron [command]
Subcommands:
ao cron self-adjust
Compatibility shim for the retired local cron self-adjust renderer.
ao cron self-adjust [flags]
Flags:
-h, --help help for self-adjust
--next string Accepted for compatibility; MTO owns next-cycle selection
--on string Accepted for compatibility; MTO owns cron scheduling (default "cycle-close")
--shipped string Accepted for compatibility; MTO owns shipped-cycle context
--sub-beads string Accepted for compatibility; MTO owns sub-bead fan-out context
--template string Accepted for compatibility; MTO owns prompt rendering
--tests-delta string Accepted for compatibility; MTO owns test-delta context
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 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-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 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 feedback-loop
Automatically close the MemRL feedback loop by updating utilities of cited learnings.
ao feedback-loop [flags]
Flags:
--alpha float EMA learning rate (default 0.1)
--citation-type string Filter citations by type (retrieved, used-in-final-artifact, helpful, harmful, refuted, applied, reference, all) (default "retrieved")
--drain Walk citations.jsonl and feed entries with zero feedback_at sentinel (idempotent)
--drain-reward float Neutral reward applied to drained citations (0.0-1.0) (default 0.5)
-h, --help help for feedback-loop
--reward float Override reward value (0.0-1.0); -1 = compute from transcript (default -1)
--session string Session ID to process
--transcript string Path to transcript for reward computation
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 handoff
Write a structured JSON handoff artifact that captures session context
ao 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 orchestrate
Instrument lane for out-of-session multi-model orchestration: tools,
ao orchestrate [command]
Subcommands:
ao orchestrate preflight
Check tools, atm version floor, Agent Mail health, and session collisions
ao orchestrate preflight [flags]
Flags:
-h, --help help for preflight
--json Emit JSON instrument result
--profile string Profile id (dual-pane, tri-vendor)
ao orchestrate route
Map posture inputs to a profile and next preflight command.
ao orchestrate route [flags]
Flags:
-h, --help help for route
--json Emit JSON instrument result
--models string Comma-separated models (opus,codex,agy)
--unattended Durability axis: unattended out-of-session
--writers int Parallel writer count
ao orchestrate select
Resolve the orchestration backend via the safe-degradation ladder
ao orchestrate select [flags]
Flags:
-h, --help help for select
--json Emit the selection trace as JSON
--opt-out Bypass swarm engines and run on the beads floor
--pin string Force a backend: ntm|claude|codex|beads (overrides --opt-out and availability)
ao orchestrate shape
Validate and stamp chosen_shape on .agents/rpi/execution-packet.json.
ao orchestrate shape [flags]
Flags:
-h, --help help for shape
--no-am Skip Agent Mail gathering
--packet string Execution packet path
--project string Agent Mail project key
--proposed string Proposed shape
--unattended Durability axis
ao orchestrate status
List active ATM sessions with degraded hints
ao orchestrate status [flags]
Flags:
-h, --help help for status
--json Emit JSON
ao orchestrate tools
Probe binaries declared in docs/contracts/orchestration-tools.yaml and emit a verdict.
ao orchestrate tools [flags]
Flags:
-h, --help help for tools
--json Emit JSON instrument result
ao orchestrate verify
Verify pane map against an orchestration profile using atm activity, spawn
ao orchestrate verify [flags]
Flags:
-h, --help help for verify
--json Emit JSON instrument result
--profile string Profile id
--session string ATM session name
ao ratchet
Track progress through the phased RPI workflow.
ao ratchet [command]
Subcommands:
ao ratchet check
Check if prerequisites are satisfied for a workflow step.
ao ratchet check <step> [flags]
Aliases:
check, c
ao ratchet next
Show the next pending step in the RPI workflow.
ao ratchet next [flags]
Aliases:
next, n
Flags:
--epic string Filter by epic ID
-h, --help help for next
ao ratchet spec
Find and output the current spec artifact path.
ao ratchet spec [flags]
ao ratchet status
Display the current state of the ratchet chain.
ao ratchet status [flags]
Aliases:
status, s
Flags:
--chain string Filter by chain ID
--epic string Filter by epic ID
-h, --help help for status
ao ratchet validate
Validate that an artifact meets quality requirements.
ao ratchet validate <step> [flags]
Flags:
--changes strings Files to validate
-h, --help help for validate
--lenient Allow legacy artifacts without schema_version (expires in 90 days)
--lenient-expiry int Days until lenient bypass expires (default 90)
ao ratchet promote
Record promotion of an artifact to a higher tier.
ao ratchet promote <artifact> [flags]
Aliases:
promote, p
Flags:
-h, --help help for promote
--to int Target tier (0-4, required) (default -1)
ao ratchet record
Record that a workflow step has been completed.
ao ratchet record <step> [flags]
Flags:
--cycle int RPI cycle number (1 for first, 2+ for iterations)
-h, --help help for record
--input string Input artifact path
--lock Lock the step (engage ratchet) (default true)
--output string Output artifact path (required)
--parent-epic string Parent epic ID from prior RPI cycle
--tier int Quality tier (0-4) (default -1)
ao ratchet skip
Record that a step was intentionally skipped.
ao ratchet skip <step> [flags]
Flags:
-h, --help help for skip
--reason string Reason for skipping (required)
ao ratchet find
Search for artifacts across all locations.
ao ratchet find <pattern> [flags]
ao ratchet trace
Trace an artifact back through the ratchet chain.
ao ratchet trace <artifact> [flags]
ao ratchet migrate
Migrate chain from legacy YAML format to JSONL.
ao ratchet migrate [flags]
ao ratchet migrate-artifacts
Add schema_version: 1 to existing .agents/ artifacts.
ao ratchet migrate-artifacts [path] [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 tick
Run the typed AgentOps port of the control-plane tick helper.
ao tick [command]
Subcommands:
ao tick claim
Claim a bead through br
ao tick claim <id> [flags]
ao tick close
Close a bead and persist the explicit ledger/evidence paths
ao tick close <id> <commit-message> <evidence-ref> [paths...] [flags]
ao tick council-gate
Fail-closed two-plus judge verdict aggregation
ao tick council-gate <verdict1> <verdict2> [...] [flags]
ao tick guard-status
Verify guard hook and validator launcher installation
ao tick guard-status [flags]
ao tick install-guards
Install repo-local git guard hooks
ao tick install-guards [flags]
ao tick next
Print the next ready bead id
ao tick next [flags]
ao tick reopen
Reopen a bead after failed validation
ao tick reopen <id> [flags]
ao tick smoke
Run a read-only smoke test of the tick membrane
ao tick smoke [flags]
ao tick status
Print ready-work status or convergence state
ao tick status [flags]
ao tick verdict-gate
Reject verdicts without commands and independent judge identity
ao tick verdict-gate <file|-> [flags]
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 memory
Manage repo-root MEMORY.md for cross-runtime access
ao memory [command]
Subcommands:
ao memory sync
Write recent session history to a repo-root MEMORY.md with managed block markers.
ao 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 notebook
Manage the session notebook (MEMORY.md)
ao notebook [command]
Subcommands:
ao notebook update
Reads the most recent session data and updates MEMORY.md with a "Last Session"
ao notebook update [flags]
Flags:
-h, --help help for update
--max-lines int Maximum lines in MEMORY.md (default 190)
--memory-file string Path to MEMORY.md (auto-detected if omitted)
--quiet Suppress output (for hooks)
--session string Specific session ID to update from
--source string Source: auto|sessions|pending (default "auto")
ao worktree
Worktree maintenance utilities
ao worktree [command]
Subcommands:
ao worktree create
Create a detached git worktree off the current commit so concurrent
ao worktree create [flags]
Flags:
-h, --help help for create
--json Emit {path, run_id} as JSON
ao worktree gc
Safely remove stale AgentOps RPI worktrees and orphaned tmux sessions.
ao worktree gc [flags]
Flags:
--clean-tmux Clean stale ao-rpi tmux sessions without active run/worktree (default true)
-h, --help help for gc
--include-dirty Also clean worktrees with uncommitted changes (unsafe)
--prune Run 'git worktree prune' after cleanup (default true)
--stale-after duration Only clean worktrees/sessions older than this age (default 24h0m0s)
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
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 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 compile
Compile makes the existing AgentOps knowledge compiler available through the ao CLI.
ao compile [flags]
Flags:
--batch-size int Max changed files per LLM prompt (prevents single-giant-prompt on large corpora) (default 25)
--compile-only Skip mine and defrag; run compile plus lint
--defrag-only Only run mechanical defrag cleanup
--force Recompile all source artifacts regardless of hashes
--force-repair Actually delete orphans during --repair. Without --force-repair, --repair runs dry.
--full Run the full mine, compile, lint, and defrag cycle
--gold Publish the sanitized OKF gold wiki to .ao/wiki after the compile cycle (default true)
-h, --help help for compile
--incremental Compile only changed source artifacts (default true)
--lint-only Only lint the existing compiled wiki
--max-batches int Cap number of compile batches per invocation (0 = unlimited)
--mine-only Only mine new knowledge signal
--output-dir string Compiled wiki output directory (default ".agents/compiled")
--quiet Suppress human progress output
--repair Remove orphaned fallback stubs from .agents/compiled/ (files with no inbound wikilink traffic)
--reset Delete .agents/compiled/ and .hashes.json before compiling (force full rebuild)
--runtime string LLM runtime override for headless compilation (codex-cli, ollama, claude, openai)
--since string Mine lookback window for full and mine-only modes (default "26h")
--sources string Source .agents root to compile (default ".agents")
ao corpus
Commands that inspect the local .agents/ corpus quality.
ao corpus [command]
Subcommands:
ao corpus capture
Write an artifact to a corpus root via the typed BC1
ao corpus capture --path <relpath> [--body <text>] [--body-file <file>] [--body-stdin] [--root <dir>] [--meta k=v ...] [flags]
Flags:
--body string body text (mutually exclusive with --body-file and --body-stdin)
--body-file string read body from file
--body-stdin read body from stdin
-h, --help help for capture
--meta stringArray metadata key=value (repeatable)
--path string relative path within root (required)
--root string corpus root (default: .agents/learnings/)
ao corpus classify
Ensure every learning record under
ao corpus classify <dir> [flags]
Flags:
--apply Write the changes (default: dry run, report only)
-h, --help help for classify
--json Emit the report as JSON
ao corpus fitness
Compute the corpus-quality fitness vector for the current .agents/
ao corpus fitness [flags]
Flags:
-h, --help help for fitness
--json Emit the fitness vector as JSON
ao corpus inject
Read knowledge from a corpus root via the typed BC1
ao corpus inject [--query <text>] [--root <path>] [--limit N] [flags]
Flags:
-h, --help help for inject
--limit int max items to emit (0 = all) (default 10)
--query string ranking query (empty = all items, score 0)
--root string corpus root (default: .agents/learnings/)
ao corpus restore
Untars a snapshot produced by ao corpus snapshot. By default refuses to overwrite an
ao corpus restore [flags]
Flags:
--from string Explicit snapshot tarball path
-h, --help help for restore
--into string Destination directory (default: .agents) (default ".agents")
--json Emit the result as JSON to stdout
--latest Pick the newest tarball in the snapshot dir
--overwrite Replace an existing destination directory (with .bak rescue)
ao corpus scan
Scan a file or directory of RENDERED public text (markdown/json/txt/html)
ao corpus scan <path> [flags]
Flags:
-h, --help help for scan
--json Emit the scan report as JSON (per-file hits)
ao corpus snapshot
Writes the entire .agents/ tree as a tar.gz to a durable directory outside the repo,
ao corpus snapshot [flags]
Flags:
-h, --help help for snapshot
--json Emit the manifest as JSON to stdout
--output-dir string Override snapshot dir (default: $AGENTOPS_CORPUS_SNAPSHOT_DIR or ~/.agentops/corpus-snapshots)
ao defrag
Defrag performs mechanical cleanup of the knowledge base:
ao defrag [flags]
Flags:
--dedup Flag learnings with >80% content similarity
-h, --help help for defrag
--no-snapshot Skip the automatic corpus snapshot taken before a destructive prune
--output-dir string Directory for defrag report JSON (default ".agents/defrag")
--prune Find orphaned learnings not referenced in patterns or research
--quiet Suppress progress output
--stale-days int Days after which an unreferenced learning is considered stale (default 30)
ao findings
Manage promoted finding artifacts under .agents/findings/.
ao findings [command]
Subcommands:
ao findings export
Export finding artifacts to another repo or findings directory
ao findings export <id...> [flags]
Flags:
--all Export every local finding
--force Overwrite destination files if they already exist
-h, --help help for export
--to string Destination repo root or .agents/findings directory
ao findings list
List active findings
ao findings list [query] [flags]
Flags:
--all Include retired and superseded findings
-h, --help help for list
--limit int Maximum findings to return (default 20)
ao findings pull
Pull finding artifacts from another repo or findings directory
ao findings pull <id...> [flags]
Flags:
--all Pull every source finding
--force Overwrite local files if they already exist
--from string Source repo root or .agents/findings directory
-h, --help help for pull
ao findings retire
Retire a finding artifact
ao findings retire <id> [flags]
Flags:
--by string Retired-by marker (defaults to current user or ao findings retire)
-h, --help help for retire
ao findings stats
Summarize local finding artifact inventory
ao findings stats [flags]
ao forge
The forge command extracts knowledge candidates from various sources.
ao forge [command]
Subcommands:
ao forge batch
Find and process pending transcripts in bulk.
ao forge batch [flags]
Flags:
--dir string Specific directory to scan (default: all Claude project dirs)
--extract Trigger extraction after forging
-h, --help help for batch
--max int Maximum transcripts to process (0 = all)
ao forge markdown
Parse markdown (.md) files and extract knowledge candidates.
ao forge markdown <path-or-glob> [flags]
Flags:
-h, --help help for markdown
--queue Queue for learning extraction at next session start
--quiet Suppress all output (for hooks)
ao forge review
Review draft session pages in .agents/ao/sessions/ and promote
ao forge review [flags]
Flags:
--dry-run Show what would be promoted without writing
--eval string Evaluate review decisions against a labeled JSON manifest without writing
-h, --help help for review
--reviewer-endpoint string Ollama HTTP endpoint for --reviewer-model (fallback: $AGENTOPS_LLM_ENDPOINT or http://localhost:11434)
--reviewer-model string LLM model tag for Tier 2 reviewer decisions (e.g. gemma2:9b)
--sessions-dir string Directory containing session pages (default: .agents/ao/sessions)
ao forge transcript
Parse Claude Code JSONL transcript files and extract knowledge candidates.
ao forge transcript <path-or-glob> [flags]
Flags:
-h, --help help for transcript
--last-session Process only the most recent transcript
--legacy-local-llm Allow legacy local Ollama/Gemma fallback for --tier=1 when no AgentWorker queue is configured
--llm-endpoint string Legacy Ollama HTTP endpoint for --tier=1 (fallback: $AGENTOPS_LLM_ENDPOINT or http://localhost:11434)
--max-chars int Per-chunk character budget for --tier=1 legacy local LLM mode (default: conservative built-in budget)
--model string Legacy local LLM model tag for --tier=1 (e.g. gemma2:9b)
--queue Queue session for learning extraction at next session start
--quiet Suppress all output (for hooks)
--tier int Tier 1 transcript processing: enqueue to configured Dream worker; local Ollama fallback requires --legacy-local-llm
--typed OPT-IN (value-gated, default off): route knowledge through the native typed extractor to emit learning.v1 records; falls back to the heuristic path if the LLM backend is unavailable
ao harvest
Walks all .agents/ directories across the workspace, extracts learnings,
ao harvest [flags]
Flags:
-h, --help help for harvest
--include string Artifact types to include (comma-separated) (default "learnings,patterns,research")
--max-file-size int Skip files larger than this (bytes) (default 1048576)
--max-promotions int Advisory volume gate: emit a stderr WARN when promotions exceed this count (0 disables; AO_MAX_PROMOTIONS env var as fallback). Never blocks. (default 500)
--min-confidence float Minimum confidence for promotion (default 0.5)
--output-dir string Directory for harvest catalog output (default ".agents/harvest")
--promote-to string Promotion destination for high-value artifacts (default ~/.agents/learnings)
--quiet Suppress progress output
--roots string Base directories to scan (comma-separated) (default ~/gt)
ao inject
Inject searches and outputs relevant knowledge for explicit or JIT context.
ao inject [context] [flags]
Flags:
--apply-decay Apply confidence decay before ranking
--bead string Bead ID for work-scoped knowledge injection
--context string Context query for filtering (alternative to positional arg)
--for string Skill name — assembles context per skill's context declaration
--format string Output format: markdown, json (default "markdown")
-h, --help help for inject
--index-only Output compact knowledge index table instead of full content
--max-tokens int Maximum tokens to output (default 1500)
--no-cite Disable citation recording
--predecessor string Path to predecessor handoff file for context injection
--profile Include .agents/profile.md identity artifact in output
--quarantine-flagged Quarantine flagged learnings from quality report
--session string Session ID for citation tracking (auto-generated if empty)
--session-type string Session type for scoring boost (career, research, debug, implement, brainstorm)
--utility-weight utility: Multiplier on utility's contribution to ranking (0=disable, 1=default, >1=emphasize). Reads utility: frontmatter; closes the eval-verdict-compiler loop. (default 1)
ao knowledge
Knowledge turns a mature .agents corpus into operator-ready surfaces.
ao knowledge [command]
Subcommands:
ao knowledge activate
Run the full knowledge activation outer loop
ao knowledge activate [flags]
Flags:
--goal string Optional goal for briefing compilation during activation
-h, --help help for activate
ao knowledge beliefs
Refresh the belief book from promoted evidence
ao knowledge beliefs [flags]
ao knowledge brief
Compile a goal-time briefing
ao knowledge brief [flags]
Flags:
--goal string Goal to compile into a briefing
-h, --help help for brief
ao knowledge gaps
Report thin topics, promotion gaps, and next mining work
ao knowledge gaps [flags]
ao knowledge playbooks
Refresh playbook candidates from healthy topics
ao knowledge playbooks [flags]
Flags:
-h, --help help for playbooks
--include-thin Include thin topics when building playbook candidates
ao lookup
Lookup retrieves full content of specific knowledge artifacts.
ao lookup [id] [flags]
Flags:
--bead string Filter by source bead ID
--cite string Citation type to record for returned artifacts: retrieved, reference, applied (default "retrieved")
--gold Retrieve from the sanitized OKF gold wiki (.ao/wiki) instead of the raw .agents/ corpus
-h, --help help for lookup
--json JSON output
--limit int Maximum results to return (default 3)
--no-cite Skip citation recording
--pointers Compact pointers only (type · title · path · score) — no bodies; the token-cheap mode for decision-point pulls
--query string Search query for relevance matching
--session string Session ID for citation tracking
ao membrane
Operate the self-improving membrane (epic age-cwo).
ao membrane [command]
Subcommands:
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 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
--json Emit the recalled escapes as JSON
ao mind
Scan, normalize, link, and index .agents/ markdown into an Obsidian knowledge graph.
ao mind [command]
Subcommands:
ao mind all
Run full pipeline (normalize → link → index)
ao mind all [flags]
ao mind graph
Show graph statistics
ao mind graph [flags]
ao mind index
Rebuild the graph index
ao mind index [flags]
ao mind link
Insert wikilinks between related artifacts
ao mind link [flags]
ao mind normalize
Add/fix YAML frontmatter on .agents/ markdown
ao mind normalize [flags]
ao mind scan
Show what needs normalization
ao mind scan [flags]
ao mine
Mine scans all reachable data sources for patterns and insights
ao mine [flags]
Flags:
--emit-work-items Append actionable mine findings to .agents/rpi/next-work.jsonl for evolve to pick up
-h, --help help for mine
--output-dir string Directory for mine output JSON (default ".agents/mine")
--quiet Suppress progress output
--since string How far back to look (e.g. 26h, 7d) (default "26h")
--sources string Comma-separated sources to mine (git, agents, code, events) (default "git,agents,code")
ao patterns
Maintenance commands for the .agents/patterns/ directory.
ao patterns [command]
Subcommands:
ao patterns repair-filenames
Walk .agents/patterns/*.md, detect filenames whose hyphenated segments
ao patterns repair-filenames [flags]
Flags:
--apply Perform renames (default: dry-run, no disk writes)
--dir string Patterns directory to repair (default: <cwd>/.agents/patterns)
-h, --help help for repair-filenames
--quiet Suppress per-rename output
ao retrieval-bench
Measure Precision@K and MRR against a curated corpus of learning artifacts.
ao retrieval-bench [flags]
Flags:
--corpus string Path to benchmark corpus directory
--global Include ~/.agents/learnings/ (cross-rig aggregated store, requires --live)
-h, --help help for retrieval-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 search
Search workspace session history and repo-local AgentOps knowledge.
ao search <query> [flags]
Flags:
--cass Require upstream cass session-history search
--cite string Optional citation type to record for matching repo-local artifacts: retrieved, reference, applied
-h, --help help for search
--limit int Maximum results to return (default 10)
--local Force repo-local AgentOps search only
--session string Session ID for citation tracking (defaults to the active runtime session)
--type string Filter by type: session(s), learning(s), pattern(s), finding(s), research, compiled, vault-source(s), decision(s), knowledge
--use-sc Try Smart Connections semantic search first (requires Obsidian)
ao sessions
Manage derived session pages under .agents/ao/sessions without touching source transcripts.
ao sessions [command]
Subcommands:
ao sessions index
Maintain derived session pages under .agents/ao/sessions.
ao sessions index [flags]
Flags:
-h, --help help for index
--prune-orphans Delete derived session pages whose source_jsonl no longer exists
--sessions-dir string Directory containing derived session pages (default: .agents/ao/sessions)
ao sessions spawn
Read a session template, expand variables, run init steps, and create
ao sessions spawn <template-path> [flags]
Flags:
--date string Override date for template expansion (default: today, YYYY-MM-DD)
--dry-run Print expanded template and init steps without executing
-h, --help help for spawn
--no-tmux Run init steps but skip tmux session creation
ao state
Manage the durable AgentOps state-memory contract.
ao state [command]
Subcommands:
ao state admit
Admit one independently reviewed Finding candidate into .ao/accepted
ao 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 state candidate
Inspect inert .ao state candidates
ao state candidate [command]
ao state candidate validate
Validate an inert .ao Finding candidate and print its digest
ao state candidate validate <path> [flags]
ao state doctor
Diagnose state memory health
ao state doctor [flags]
ao state review-request
Emit the digest-bound review request for a Finding candidate
ao state review-request <candidate> [flags]
ao state validate
Validate state memory JSON files against their schemas
ao state validate <file> [file...] [flags]
ao state verify
Verify .ao state schemas, fixtures, accepted findings, and ledger rows
ao state verify [flags]
Flags:
--all Verify all .ao state authority surfaces
-h, --help help for verify
ao trace
Trace the provenance of an artifact back to its source transcript.
ao trace <artifact-path> [flags]
Flags:
--graph Show ASCII provenance graph
-h, --help help for trace
ao wiki
ao wiki is the experimental unified surface for the wiki bounded context.
ao wiki [command]
Subcommands:
ao wiki add
Copy supported source files (.md/.txt — what the ingest processes) into the
ao wiki add <file|dir>... [flags]
Flags:
-h, --help help for add
--path string Workspace path (default: the active workspace)
ao wiki doctor
Report on the wiki corpus directory and the persistent index.
ao wiki doctor [flags]
Flags:
--base string Corpus base directory (default: current directory)
-h, --help help for doctor
ao wiki gold
ao wiki gold is the raw-lead-to-gold bridge of the knowledge flywheel.
ao wiki gold [flags]
Flags:
--confidence-floor float override the promotion confidence floor (default 0.70)
--dry-run report what would be promoted without writing
-h, --help help for gold
--json emit stats as JSON
--out string output directory for the OKF gold wiki (default ".ao/wiki")
ao wiki index
Scan the .agents/ corpus and update the persistent JSONL document index.
ao wiki index [flags]
Flags:
--base string Corpus base directory (default: current directory)
--gold Index the OKF gold wiki (.ao/wiki) instead of the raw .agents/ corpus
-h, --help help for index
ao wiki init
Create an OpenKB-style wiki workspace at [path] (default: current directory).
ao wiki init [path] [flags]
Flags:
-h, --help help for init
--language string Primary language for the wiki (recorded in config) (default "en")
--model string Model the wiki is initialized for (recorded in config)
ao wiki inject
Assemble just-in-time .agents/ context.
ao wiki inject [flags]
ao wiki lint
Run the OpenKB-style structural health check over the active wiki workspace:
ao wiki lint [flags]
Flags:
--fix Apply safe deterministic repairs (strip dangling wikilinks); read-only without this flag
-h, --help help for lint
--json Emit JSON
--path string Workspace path (default: the active workspace)
--pipeline-stage Run the legacy WikiPipeline LINT stage instead of the structural health check
--vault string Vault root (default: current directory)
ao wiki list
Enumerate every compiled wiki page (summaries, concepts, entities, ...) plus
ao wiki list [flags]
Flags:
-h, --help help for list
--json Emit JSON
--path string Workspace path (default: the active workspace)
--type string Filter to one frontmatter type (e.g. concept, entity, summary)
ao wiki promote
Promote mature wiki pages into authored content.
ao wiki promote [flags]
Flags:
-h, --help help for promote
--vault string Vault root (default: current directory)
ao wiki publish
ao wiki publish is the membrane gate over the gold wiki.
ao wiki publish [flags]
Flags:
--bead string bead whose CONFIRMED verdict for HEAD authorizes real publish (required without --dry-run)
--confidence-floor float override the promotion confidence floor
--dry-run compute + leak-scan the candidate without publishing
--expect-digest string fail closed unless the recomputed digest matches this (publish exactly what dry-run reviewed)
-h, --help help for publish
--json emit the candidate report as JSON
ao wiki query
Answer a pending wiki question into wiki/synthesis/.
ao wiki query [flags]
Flags:
-h, --help help for query
--vault string Vault root (default: current directory)
ao wiki recompile
Re-run the ingest/compile stage over the active wiki workspace, distilling
ao wiki recompile [flags]
Flags:
--all Recompile the whole workspace (default true)
--dry-run List sources that would be recompiled without writing
-h, --help help for recompile
--path string Workspace path (default: the active workspace)
--refresh-schema Also rewrite the workspace config/schema
ao wiki remove
Remove a registered source (by id or raw filename) and its derived wiki
ao wiki remove <doc> [flags]
Flags:
--dry-run Report artifacts that would be removed without deleting
-h, --help help for remove
--keep-raw Leave the raw/ source file in place
--path string Workspace path (default: the active workspace)
ao wiki search
Rank documents in the wiki index against a free-text query.
ao wiki search <query> [flags]
Flags:
--base string Corpus base directory (default: current directory)
--gold Search the OKF gold wiki (.ao/wiki) instead of the raw .agents/ corpus
-h, --help help for search
--limit int Maximum results to print (default 20)
--reindex Rebuild the index before searching
ao wiki status
Report per-type page counts and a structural-health summary (defect totals by
ao wiki status [flags]
Flags:
-h, --help help for status
--json Emit JSON
--path string Workspace path (default: the active workspace)
ao wiki use
With
ao wiki use [path] [flags]
ao agent
Emit a runtime-specific Agent definition (Managed Agents payload or
ao agent [command]
Subcommands:
ao agent bundle
Stitch the selected AgentOps skills + the ao tool surface into an
ao agent bundle [flags]
Flags:
-h, --help help for bundle
--json Emit machine-readable JSON (always JSON for now; reserved for parity)
--out string Write the bundle to this path instead of stdout
--runtime string Target runtime: managed | codex-ntm (required)
--sandbox string Sandbox placement: self-hosted | cloud
--skills string Comma-separated skill names (default: session-bootstrap,standards,validation,provenance)
ao agents
Tooling for the .agents/ knowledge surface that backs the
ao agents [command]
Subcommands:
ao agents doctor
Combine ao agents inspect and ao agents lint into a single
ao agents doctor [flags]
Flags:
--agents-dir string Path to the .agents/ directory under inspection (default ".agents")
--contract string Path to the .agents/ write-surfaces contract doc (default "docs/contracts/agents-write-surfaces.md")
-h, --help help for doctor
--json Emit machine-readable JSON
--script string Path to the lint script (default "scripts/check-agents-write-surfaces.sh")
--skills-dir string Path to the skills/ directory used for skill-owned-subdir cross-check (default "skills")
--strict Exit non-zero on any orphan or undocumented surface
ao agents inspect
Read the .agents/ write-surface contract and emit a structured
ao agents inspect [flags]
Flags:
--contract string Path to the .agents/ write-surfaces contract doc (default "docs/contracts/agents-write-surfaces.md")
-h, --help help for inspect
--json Emit machine-readable JSON
ao agents lint
Wrap scripts/check-agents-write-surfaces.sh and surface its
ao agents lint [flags]
Flags:
-h, --help help for lint
--json Forward --json to the lint script
--script string Path to the lint script (default "scripts/check-agents-write-surfaces.sh")
ao chaos-test
Run a read-only smoke test of the tick membrane
ao chaos-test [flags]
ao close
Close a bead and persist the explicit ledger/evidence paths
ao close <id> <commit-message> <evidence-ref> [paths...] [flags]
ao converge
Run a bounded convergence loop: dispatch a non-mutating judge panel, apply the
ao converge [flags]
Flags:
-h, --help help for converge
--kill-dir string directory whose .agents/rpi/KILL switch aborts the bounded loop at a round boundary (default ".")
--max-rounds int maximum fix->re-run rounds before NOT-CONVERGED (default 5)
--min-contexts int distinct non-author judge contexts required to converge (default 2)
--require-cross-family optional strengthener: additionally require >=2 model families in the PASS quorum
ao council-gate
Fail-closed two-plus judge verdict aggregation
ao council-gate <verdict1> <verdict2> [...] [flags]
ao extract
Check for pending session extractions and output a prompt for Claude to process.
ao extract [flags]
Flags:
--all Process all pending entries
--bead string Bead ID to tag extracted learnings with
--clear Clear pending queue without processing
-h, --help help for extract
--max-content int Maximum characters of session content to include (default 3000)
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 guard-status
Verify guard hook and validator launcher installation
ao guard-status [flags]
ao help
Help provides help for any command in the application.
ao help [command] [flags]
ao install-guards
Install repo-local git guard hooks
ao install-guards [flags]
ao mcp
Model Context Protocol surface for out-of-session Claude loops (Managed
ao mcp [command]
Subcommands:
ao mcp serve
Emit the curated MCP tool surface (--print-tools) consumable by
ao mcp serve [flags]
Flags:
-h, --help help for serve
--json Machine-readable JSON (always JSON for --print-tools; reserved for parity)
--print-tools Emit the curated tool surface as JSON and exit
ao next-work
Commands that act on the carry-forward next-work queue that /post-mortem
ao next-work [command]
Subcommands:
ao next-work materialize
Read .agents/rpi/next-work.jsonl and create one durable bead per
ao next-work materialize [flags]
Flags:
--dry-run Show what would be created without creating beads or mutating the queue
--file string Path to next-work.jsonl (default: <cwd>/.agents/rpi/next-work.jsonl)
-h, --help help for materialize
--json Emit a machine-readable JSON summary
--materialized-by string Actor recorded in provenance metadata (default "next-work-materialize")
--source-epic string Only materialize items whose batch source_epic equals this value
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] [--converge] [--author-family <fam>] [--context <s>] [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 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 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 refinery
Watch main, run the full gate on each new commit, and on a
ao refinery [command]
Subcommands:
ao refinery once
Evaluate main HEAD once
ao refinery once [flags]
ao refinery run
Run the refinery loop until interrupted
ao refinery run [flags]
Flags:
-h, --help help for run
--interval duration poll interval (default 5m0s)
ao registry
Query the unified registry
ao registry [command]
Subcommands:
ao registry list
List registry entries
ao registry list [flags]
Flags:
-h, --help help for list
--type string Filter by surface type (skills, hooks, stores, jobs, evals, cli, cadence)
ao rehydrate
Rehydrate emits a lane's re-bootstrap brief from the most recent handoff
ao 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 scenario
Create, list, and validate holdout scenarios stored in .agents/holdout/.
ao scenario [command]
Subcommands:
ao scenario add
Author a schema-compliant holdout scenario in .agents/holdout/.
ao 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 scenario init
Initialize .agents/holdout/ directory for scenario storage
ao scenario init [flags]
ao scenario list
List holdout scenarios
ao scenario list [flags]
Flags:
-h, --help help for list
--status string Filter by status (active, draft, retired)
ao scenario validate
Validate holdout scenarios against schema
ao scenario validate [flags]
ao scope
Declare which directories are in scope for the current work session.
ao scope [command]
Flags:
-h, --help help for scope
--json Emit JSON output
--lock string Override scope-lock path (defaults to $AO_SCOPE_LOCK or .agents/scope.lock)
Subcommands:
ao scope freeze
Freeze one or more directories (additive)
ao scope freeze <dir> [<dir>...] [flags]
ao scope status
Show current scope-lock state
ao scope status [flags]
ao scope unfreeze
Unfreeze one (or all if no arg) directories
ao scope unfreeze [<dir>...] [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 dependency graph (A --> B means A consumes B) from
ao skills graph [flags]
Flags:
--format string Graph output format (mermaid) (default "mermaid")
-h, --help help for graph
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 turn
The 'turn' command group operates on Evidenced Turns — the ag-lmdx
ao turn [command]
Subcommands:
ao turn verify
Evaluate the legible Definition-of-Done predicate for one bead's
ao turn verify <bead> [flags]
Flags:
--allow-self Waive the no-self-grading invariant (permit judge_id == author_id) for the inline fallback; default OFF
--graph string Path to the provenance trace-graph JSONL (node/edge records) for orphan detection
-h, --help help for verify
--input string Path to the turn-input JSON file (state log + scenario coverage) (required)
--json Emit the full Verdict object as JSON
--ledger string Path to the provenance EDGE ledger JSONL (default: docs/provenance/ledger.jsonl)
ao verdict-gate
Reject verdicts without commands and independent judge identity
ao verdict-gate <file|-> [flags]
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 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)