Auto-generated by
scripts/generate-cli-reference.sh. Do not edit manually. Re-run the script to update.
--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
Run an interactive demonstration of AgentOps capabilities.
ao demo [flags]
Flags:
--concepts Just explain core concepts
-h, --help help for demo
--quick 2-minute quick overview
Set up a repository for AgentOps: directories, gitignore, and optional hooks.
ao init [flags]
Flags:
--full With --hooks, explicitly request full coverage (legacy explicit flag)
-h, --help help for init
--hooks Also register hooks (full 12-event coverage by default; equivalent to ao hooks install --full)
--minimal-hooks With --hooks, install SessionStart + SessionEnd + Stop hooks (lightweight)
--stealth Use .git/info/exclude instead of .gitignore
Initialize AgentOps in your current project.
ao quick-start [flags]
Flags:
-h, --help help for quick-start
--minimal Minimal setup (just directories)
--no-beads Skip beads initialization
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)
List learnings that have been marked as anti-patterns.
ao anti-patterns [flags]
Display a visual badge showing knowledge flywheel health status.
ao badge [flags]
Manage constraints compiled from promoted findings.
ao constraint [command]
Subcommands:
Change constraint status from draft to active
ao constraint activate <id> [flags]
List all constraints with status
ao constraint list [flags]
Change constraint status from active to retired
ao constraint retire <id> [flags]
List constraints compiled >90 days ago without recent citation
ao constraint review [flags]
Scan learnings and patterns for potential contradictions using keyword overlap heuristics.
ao contradict [flags]
Curate manages the knowledge curation pipeline: catalog artifacts,
ao curate [command]
Subcommands:
Catalog a knowledge artifact
ao curate catalog <path> [flags]
Show curation pipeline status
ao curate status [flags]
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)
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
Run health checks on your AgentOps installation.
ao doctor [flags]
Flags:
-h, --help help for doctor
--json Output results as JSON
Knowledge flywheel operations and status.
ao flywheel [command]
Subcommands:
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")
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")
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
Returns structured JSON combining:
ao flywheel nudge [flags]
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")
Manage human review gates for bronze-tier candidates.
ao gate [command]
Subcommands:
Approve a bronze-tier candidate for promotion.
ao gate approve <candidate-id> [flags]
Flags:
-h, --help help for approve
--note string Optional approval note
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")
List bronze-tier candidates awaiting human review.
ao gate pending [flags]
Reject a candidate with a required reason.
ao gate reject <candidate-id> [flags]
Flags:
-h, --help help for reject
--reason string Required rejection reason
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
--uncited-days int Archive provisional/candidate learnings with zero citations older than this many days when used with --curate (default 60)
Track and report on knowledge flywheel metrics.
ao metrics [command]
Subcommands:
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
Record that an artifact was cited in this session.
ao metrics cite <artifact-path> [flags]
Flags:
-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: recall, reference, applied (default "reference")
--vendor string Model vendor attribution: claude, codex
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
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")
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
Manage knowledge candidates in quality pools.
ao pool [command]
Subcommands:
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")
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")
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
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
Move legacy knowledge captures from .agents/knowledge/*.md into
ao pool migrate-legacy [flags]
Flags:
-h, --help help for migrate-legacy
--pending-dir string Pending directory for migrated captures (default ".agents/knowledge/pending")
--source-dir string Source directory containing legacy markdown captures (default ".agents/knowledge")
Move a staged candidate to the knowledge base (.agents/learnings/ or .agents/patterns/).
ao pool promote <candidate-id> [flags]
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)
Show detailed information about a pool candidate.
ao pool show <candidate-id> [flags]
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)
Display the current state of AgentOps knowledge base.
ao status [flags]
Display the version, build information, and runtime details.
ao version [flags]
Run a comprehensive vibe-check analysis on your repository.
ao vibe-check [flags]
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")
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:
Create a PROGRAM.md template
ao autodev init [objective] [flags]
Flags:
--force Overwrite an existing program file
-h, --help help for init
Show the parsed PROGRAM.md contract
ao autodev show [flags]
Validate PROGRAM.md structure
ao autodev validate [flags]
Codex lifecycle commands for the AgentOps knowledge flywheel.
ao codex [command]
Subcommands:
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)
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)
-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
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)
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
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)
-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
Run the v2 autonomous improvement loop.
ao evolve [goal] [flags]
Flags:
--auto-clean Run stale RPI cleanup before each phased cycle
--auto-clean-stale-after duration Only auto-clean runs older than this age (default 24h0m0s)
--bd-sync-policy string Legacy bd landing checkpoint policy: auto|always|never (auto/always run 'bd export -o /dev/null' on current bd releases) (default "auto")
--cleanup-prune-branches Run legacy branch cleanup during supervisor cleanup
--cleanup-prune-worktrees Run git worktree prune during supervisor cleanup (default true)
--command-timeout duration Timeout for supervisor external commands (git/bd/gate scripts) (default 20m0s)
--compile Enable Compile producer cadence before queue selection
--compile-defrag Run defrag sweep after Compile mine producer tick
--compile-interval duration Minimum interval between Compile producer ticks (0 = every cycle) (default 30m0s)
--compile-since string Lookback window for Compile mine producer (default "26h")
--cycle-delay duration Delay between completed cycles
--cycle-retries int Automatic retry count per cycle after a failed attempt
--detached-branch-prefix string Branch prefix used by detached HEAD self-heal (default "codex/auto-rpi")
--detached-heal Auto-create/switch to a named branch when HEAD is detached
--dream-first Run Dream knowledge sub-cycle before code cycles
--dream-only Knowledge compounding only, no code cycles
--dream-timeout string Timeout for the Dream sub-cycle (default "30m")
--ensure-cleanup Run stale-run cleanup after each cycle (cleanup guarantee)
--failure-policy string Cycle failure policy: stop|continue (default "stop")
--gate-fast-script string Fast validation gate script path (default "scripts/validate-go-fast.sh")
--gate-policy string Quality/security gate policy: off|best-effort|required (default "off")
--gate-security-script string Security gate script path (default "scripts/security-gate.sh")
-h, --help help for evolve
--kill-switch-path string Supervisor kill-switch file path checked at cycle boundaries (absolute or repo-relative) (default ".agents/rpi/KILL")
--landing-branch string Landing target branch (empty resolves origin/HEAD, then current branch, then main)
--landing-commit-message string Commit message template for landing policies that commit (default "chore(rpi): autonomous cycle {{cycle}}")
--landing-lock-path string Landing lock file path for synchronized integration (absolute or repo-relative) (default ".agents/rpi/landing.lock")
--landing-policy string Landing policy after successful cycle: off|commit|sync-push (default "off")
--lease Acquire a single-flight supervisor lease lock before running
--lease-path string Lease lock file path (absolute or repo-relative) (default ".agents/rpi/supervisor.lock")
--lease-ttl duration Lease heartbeat TTL for supervisor lock metadata (default 2m0s)
--max-cycles int Maximum cycles (0 = unlimited, stop when queue empty)
--ralph Enable Ralph-mode preset for unattended external loop supervision (implies supervisor defaults with safe nonstop settings)
--repo-filter string Only process queue items targeting this repo (empty = all)
--retry-backoff duration Backoff between cycle retry attempts (default 30s)
--supervisor Enable autonomous supervisor mode (lease lock, self-heal, retries, gates, cleanup) (default true)
Software-factory operator surface for AgentOps.
ao factory [command]
Subcommands:
Start the software-factory operator lane for a concrete goal.
ao factory start [flags]
Flags:
--goal string Goal to brief and use as the startup query
-h, --help help for start
--limit int Maximum artifacts to surface per category during startup (default 3)
--no-maintenance Skip safe close-loop maintenance on start
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, applied, all) (default "retrieved")
-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
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
--json Output as JSON
--timeout int Check timeout in seconds (default 240)
Subcommands:
Run goal checks and produce a snapshot
ao goals measure [flags]
Flags:
--directives Output directives as JSON (skip gate checks)
--goal string Measure a single goal by ID
-h, --help help for measure
Validate GOALS.yaml structure and wiring
ao goals validate [flags]
Compare snapshots for regressions
ao goals drift [flags]
Export latest snapshot as JSON (for CI)
ao goals export [flags]
Show goal measurement history
ao goals history [flags]
Flags:
--goal string Filter history to a specific goal
-h, --help help for history
--since string Show entries since date (YYYY-MM-DD)
Add a new goal
ao goals add <id> <check-command> [flags]
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)
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)
Run and report meta-goals only
ao goals meta [flags]
Migrate goals between formats.
ao goals migrate [flags]
Flags:
-h, --help help for migrate
--to-md Convert GOALS.yaml to GOALS.md format
Remove goals referencing nonexistent files
ao goals prune [flags]
Manage directives
ao goals steer [command]
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")
Move a directive to a new position
ao goals steer prioritize <number> <new-position> [flags]
Remove a directive by number
ao goals steer remove <number> [flags]
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
Dream is AgentOps' private overnight operator mode.
ao overnight [command]
Subcommands:
Inspect and operate a local Tier 1 Dream curator such as Ollama/Gemma.
ao overnight curator [command]
Run the local curator pending-log compactor
ao overnight curator compact [flags]
Flags:
--apply Apply pending-log compaction
--dry-run Preview pending-log compaction without writing
-h, --help help for compact
Explain local curator setup problems
ao overnight curator diagnose [flags]
Flags:
-h, --help help for diagnose
--json Render curator diagnosis as JSON
Enqueue an allowlisted local curator job
ao overnight curator enqueue [flags]
Flags:
--chunk-end int End chunk index for ingest-claude-session jobs
--chunk-start int Start chunk index for ingest-claude-session jobs
-h, --help help for enqueue
--kind string Job kind to enqueue: ingest-claude-session, lint-wiki, or dream-seed
--source string Source path for ingest-claude-session jobs
Write a bounded needs-review escalation event
ao overnight curator event [flags]
Flags:
--budget int Maximum downstream event budget (default 1)
--desired-action string Requested bounded action for Tier 2 review
-h, --help help for event
--note string Optional operator note
--severity string Event severity: info, warn, high, or critical
--source string Event source, for example gemma or local-soc
--target string Escalation target (default "dream-council")
Report local curator queue, worker, and model health
ao overnight curator status [flags]
Flags:
-h, --help help for status
--json Render curator status as JSON
Read a Dream report from summary.json and render it as JSON, YAML, or
ao overnight report [flags]
Flags:
--from string Directory containing summary.json, or the summary.json file itself
-h, --help help for report
Inspect the current machine, detect available Dream runtimes and scheduler
ao overnight setup [flags]
Flags:
--apply Persist the detected Dream config and generate scheduler assistance artifacts
--at string Preferred local Dream run time in HH:MM (used for scheduler assistance)
-h, --help help for setup
--keep-awake Persist keep-awake on for Dream runs
--no-keep-awake Persist keep-awake off for Dream runs
--runner strings Dream runner to persist (repeatable: --runner codex --runner claude)
--scheduler string Scheduler mode to persist (auto, manual, launchd, cron, systemd, task-scheduler) (default "auto")
Start a private overnight Dream run against the local repository.
ao overnight start [flags]
Flags:
--checkpoint-max-mb int Max total MB of checkpoint storage per run (default 512)
--creative-lane Enable the bounded wildcard lane when Dream Council is running
--goal string Optional goal to include in the morning report and briefing step
-h, --help help for start
--keep-awake Force keep-awake assistance on for this run
--long-haul Enable the opt-in long-haul Dream controller after the default short path
--long-haul-budget string Maximum extra time the long-haul controller may spend after the short path (default "1h")
--max-iterations int Cap iteration count (0 = budget-bounded only)
--no-keep-awake Disable keep-awake assistance for this run
--output-dir string Directory for overnight artifacts (defaults to dream.report_dir)
--plateau-epsilon float Plateau threshold: |delta| below this counts as plateau (default 0.01)
--plateau-window int Plateau window K (consecutive sub-epsilon deltas required to halt) (default 2)
--queue string Operator-pinned nightly priorities (markdown file)
--run-timeout string Maximum duration for the overnight run (defaults to dream.run_timeout)
--runner strings Dream runner to execute (repeatable: --runner codex --runner claude)
--warn-only First-N-runs mode: warn on plateau/regression, don't halt. Default true; flip to false once thresholds are calibrated. (default true)
Dream's warn-only ratchet protects the first 2-3 production runs
ao overnight warn-only [command]
Reset .agents/overnight/warn-only-budget.json to a fresh state.
ao overnight warn-only reset [flags]
Flags:
-h, --help help for reset
--initial int Initial rescue ceiling (defaults to 3)
--json Emit the reset result as JSON instead of human-readable text
Track progress through the phased RPI workflow.
ao ratchet [command]
Subcommands:
Check if prerequisites are satisfied for a workflow step.
ao ratchet check <step> [flags]
Show the next pending step in the RPI workflow.
ao ratchet next [flags]
Flags:
--epic string Filter by epic ID
-h, --help help for next
Find and output the current spec artifact path.
ao ratchet spec [flags]
Display the current state of the ratchet chain.
ao ratchet status [flags]
Flags:
--chain string Filter by chain ID
--epic string Filter by epic ID
-h, --help help for status
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)
Record promotion of an artifact to a higher tier.
ao ratchet promote <artifact> [flags]
Flags:
-h, --help help for promote
--to int Target tier (0-4, required) (default -1)
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)
Record that a step was intentionally skipped.
ao ratchet skip <step> [flags]
Flags:
-h, --help help for skip
--reason string Reason for skipping (required)
Search for artifacts across all locations.
ao ratchet find <pattern> [flags]
Trace an artifact back through the ratchet chain.
ao ratchet trace <artifact> [flags]
Migrate chain from legacy YAML format to JSONL.
ao ratchet migrate [flags]
Add schema_version: 1 to existing .agents/ artifacts.
ao ratchet migrate-artifacts [path] [flags]
Commands for automating the RPI lifecycle.
ao rpi [command]
Subcommands:
Cancel active RPI orchestration runs via a CLI kill switch.
ao rpi cancel [flags]
Flags:
--all Cancel all active runs discovered under current/sibling roots
--dry-run Show what would be cancelled without sending signals
-h, --help help for cancel
--run-id string Cancel one active run by run ID
--signal string Signal to send: TERM|KILL|INT (default "TERM")
Detect and clean up stale RPI phased runs.
ao rpi cleanup [flags]
Flags:
--all Clean up all stale runs
--dry-run Show what would be done without making changes
-h, --help help for cleanup
--prune-branches Delete legacy RPI branches (rpi/*, codex/auto-rpi-*)
--prune-worktrees Run 'git worktree prune' after cleanup
--run-id string Clean up a specific run by ID
--stale-after duration Only clean runs older than this age (0 disables age filtering)
Execute RPI cycles in a loop, consuming from next-work.jsonl.
ao rpi loop [goal] [flags]
Flags:
--auto-clean Run stale RPI cleanup before each phased cycle
--auto-clean-stale-after duration Only auto-clean runs older than this age (default 24h0m0s)
--bd-sync-policy string Legacy bd landing checkpoint policy: auto|always|never (auto/always run 'bd export -o /dev/null' on current bd releases) (default "auto")
--cleanup-prune-branches Run legacy branch cleanup during supervisor cleanup
--cleanup-prune-worktrees Run git worktree prune during supervisor cleanup (default true)
--command-timeout duration Timeout for supervisor external commands (git/bd/gate scripts) (default 20m0s)
--compile Enable Compile producer cadence before queue selection
--compile-defrag Run defrag sweep after Compile mine producer tick
--compile-interval duration Minimum interval between Compile producer ticks (0 = every cycle) (default 30m0s)
--compile-since string Lookback window for Compile mine producer (default "26h")
--cycle-delay duration Delay between completed cycles
--cycle-retries int Automatic retry count per cycle after a failed attempt
--detached-branch-prefix string Branch prefix used by detached HEAD self-heal (default "codex/auto-rpi")
--detached-heal Auto-create/switch to a named branch when HEAD is detached
--ensure-cleanup Run stale-run cleanup after each cycle (cleanup guarantee)
--failure-policy string Cycle failure policy: stop|continue (default "stop")
--gate-fast-script string Fast validation gate script path (default "scripts/validate-go-fast.sh")
--gate-policy string Quality/security gate policy: off|best-effort|required (default "off")
--gate-security-script string Security gate script path (default "scripts/security-gate.sh")
-h, --help help for loop
--kill-switch-path string Supervisor kill-switch file path checked at cycle boundaries (absolute or repo-relative) (default ".agents/rpi/KILL")
--landing-branch string Landing target branch (empty resolves origin/HEAD, then current branch, then main)
--landing-commit-message string Commit message template for landing policies that commit (default "chore(rpi): autonomous cycle {{cycle}}")
--landing-lock-path string Landing lock file path for synchronized integration (absolute or repo-relative) (default ".agents/rpi/landing.lock")
--landing-policy string Landing policy after successful cycle: off|commit|sync-push (default "off")
--lease Acquire a single-flight supervisor lease lock before running
--lease-path string Lease lock file path (absolute or repo-relative) (default ".agents/rpi/supervisor.lock")
--lease-ttl duration Lease heartbeat TTL for supervisor lock metadata (default 2m0s)
--max-cycles int Maximum cycles (0 = unlimited, stop when queue empty)
--ralph Enable Ralph-mode preset for unattended external loop supervision (implies supervisor defaults with safe nonstop settings)
--repo-filter string Only process queue items targeting this repo (empty = all)
--retry-backoff duration Backoff between cycle retry attempts (default 30s)
--supervisor Enable autonomous supervisor mode (lease lock, self-heal, retries, gates, cleanup)
Send a message to an active tmux-backed RPI phase session.
ao rpi nudge [message] [flags]
Flags:
--all-workers Send nudge to every worker session for the phase
-h, --help help for nudge
--message string Nudge message to send
--phase int Phase number to target (1-3; defaults to run's current phase)
--run-id string Run ID to target (defaults to latest phased state)
--worker int Send nudge to one worker (for example: 1)
Run multiple RPI epics concurrently, each in an isolated git worktree.
ao rpi parallel [goals...] [flags]
Flags:
--gate-script string Validation script to run after all merges (e.g., scripts/ci-local-release.sh)
-h, --help help for parallel
--manifest string Path to epic manifest file (JSON)
--merge-order string Comma-separated epic names for merge order (default: manifest order or arg order)
--no-merge Skip auto-merge (leave worktrees for manual review)
--phase-timeout duration Timeout per epic (kills subprocess if exceeded) (default 1h30m0s)
--runtime-cmd string Runtime command for phased sessions (default: claude)
--tmux Spawn epics in tmux windows for interactive visibility
Orchestrate the full RPI lifecycle using 3 consolidated phases.
ao rpi phased <goal> [flags]
Flags:
--auto-clean-stale Run stale-run cleanup before starting phased execution
--auto-clean-stale-after duration Only clean stale runs older than this age when auto-clean is enabled (default 24h0m0s)
--budget string Override phase budgets in seconds (<phase>:<seconds>, comma-separated), e.g. discovery:300,validation:120
--discovery-artifact string Path to a pre-validated discovery artifact (markdown) used to skip Phase 1 when combined with --from=implementation
--fast-path Force fast path (--quick for gates)
--from string Start from phase (discovery, implementation, validation; aliases: research, plan, pre-mortem, crank, vibe, post-mortem) (default "discovery")
-h, --help help for phased
--interactive Enable human gates at research and plan phases
--live-status Stream phase progress to a live-status.md file
--max-retries int Maximum retry attempts per gate (default: 3) (default 3)
--mixed Enable cross-vendor mixed-model execution (planner and reviewer from different vendors)
--no-budget Disable all phase budgets and run without time-box transitions
--no-dashboard Disable auto-opening the web dashboard
--no-test-first Opt out of strict-quality spec-first execution (do not pass --test-first to /crank)
--no-worktree Disable worktree isolation (run in current directory)
--phase-timeout duration Maximum wall-clock runtime per phase (0 disables timeout) (default 1h30m0s)
--runtime string Phase runtime mode: auto|direct|stream|tmux (default "auto")
--runtime-cmd string Runtime command used for phase prompts (Claude uses '-p'; Codex uses 'exec') (default "claude")
--stall-timeout duration Maximum time without progress before declaring stall (0 disables) (default 10m0s)
--stream-startup-timeout duration Maximum time to wait for first stream event before falling back to direct execution (0 disables) (default 45s)
--swarm-first Default each phase to swarm/agent-team execution; fall back to direct execution if swarm runtime is unavailable (default true)
--test-first Default to strict-quality spec-first execution by passing --test-first to /crank (default true)
--tmux-workers int When --runtime tmux, number of worker sessions spawned per phase (default 1)
Start a production RPI orchestration run or stream its live dashboard.
ao rpi serve [goal | run-id] [flags]
Flags:
-h, --help help for serve
--no-open Do not open browser automatically
--orchestrate Treat first argument as a goal and run full RPI orchestration
--port int Port to listen on (default 7799)
--run-id string Run ID to watch explicitly (must match rpi-<8-12 hex> or <12 hex>)
--runtime string Phase runtime mode for orchestration: auto|direct|stream|tmux
--runtime-cmd string Runtime command for orchestration phase prompts (Claude uses '-p'; Codex uses 'exec')
Display active and recent RPI phased runs.
ao rpi status [flags]
Flags:
-h, --help help for status
--watch Poll every 5s and redraw (Ctrl-C to exit)
Read normalized per-run C2 events from events.jsonl.
ao rpi stream [flags]
Flags:
--follow Follow for newly appended events
--format string Output format: human|json|sse (default "human")
-h, --help help for stream
--run-id string Run ID to stream (defaults to latest phased state)
Verify integrity of the RPI ledger.
ao rpi verify [flags]
Session lifecycle operations.
ao session [command]
Subcommands:
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)
Generate shell completion scripts for ao.
ao completion [bash|zsh|fish]
View and manage AgentOps configuration.
ao config [command]
Flags:
-h, --help help for config
--show Show resolved configuration with sources
Subcommands:
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)
The hooks command manages runtime hooks that automate the CASS knowledge flywheel.
ao hooks [command]
Subcommands:
Generate hooks configuration for the CASS knowledge flywheel (Claude Code format).
ao hooks init [flags]
Flags:
--format string Output format: json, shell (default "json")
-h, --help help for init
Install ao hooks to ~/.claude/settings.json.
ao hooks install [flags]
Flags:
--dry-run Show what would be installed without making changes
--force Overwrite existing ao hooks
--full Install all hook events from hooks.json with scripts copied to ~/.agentops/
-h, --help help for install
--source-dir string Path to agentops repo checkout (for --full script installation)
Display the current hooks configuration from ~/.claude/settings.json (Claude Code runtime).
ao hooks show [flags]
Test that all hook dependencies are available and working.
ao hooks test [flags]
Flags:
--dry-run Show test steps without running hooks
-h, --help help for test
Manage repo-root MEMORY.md for cross-runtime access
ao memory [command]
Subcommands:
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
Manage the session notebook (MEMORY.md)
ao notebook [command]
Subcommands:
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")
Plans manages the plan manifest at .agents/plans/manifest.jsonl.
ao plans [command]
Subcommands:
Diff compares the plan manifest against beads reality.
ao plans diff [flags]
List shows all plans in the manifest.
ao plans list [flags]
Flags:
-h, --help help for list
--project string Filter by project path
--status string Filter by status (active, completed, abandoned, superseded)
Register adds a plan to the manifest.jsonl for discovery.
ao plans register <plan-path> [flags]
Flags:
--beads-id string Beads issue/epic ID this plan implements
-h, --help help for register
--name string Human-readable plan name
--project string Project path this plan applies to
Search plans by name or project
ao plans search <query> [flags]
Sync pulls plan metadata from beads to prevent drift.
ao plans sync [flags]
Update a plan's status or metadata
ao plans update <plan-path> [flags]
Flags:
--beads-id string Update beads ID
-h, --help help for update
--status string New status for the plan
Commands that help maintain the bd issue tracker alongside the main
ao beads [command]
Subcommands:
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
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
Reads a closed bead via 'bd show ' and writes its closure reason
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")
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")
Reads a bead description via 'bd show ' and checks every file
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)
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
-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 (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")
Commands that inspect the local .agents/ corpus quality.
ao corpus [command]
Subcommands:
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
Defrag performs mechanical cleanup of the knowledge base:
ao defrag [flags]
Flags:
--dedup Flag learnings with >80% content similarity
-h, --help help for defrag
--oscillation-sweep Flag evolve goals alternating improved/fail >=3 consecutive cycles
--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)
Manage promoted finding artifacts under .agents/findings/.
ao findings [command]
Subcommands:
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
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)
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
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
Summarize local finding artifact inventory
ao findings stats [flags]
The forge command extracts knowledge candidates from various sources.
ao forge [command]
Subcommands:
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)
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)
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 (default: $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)
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
--llm-endpoint string Ollama HTTP endpoint for --tier=1 (default: $AGENTOPS_LLM_ENDPOINT or http://localhost:11434)
--max-chars int Per-chunk character budget for --tier=1 local LLM mode (default: conservative built-in budget)
--model string 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, otherwise use local LLM with --model
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)
--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)
Inject searches and outputs relevant knowledge for session startup.
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)
Knowledge turns a mature .agents corpus into operator-ready surfaces.
ao knowledge [command]
Subcommands:
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
Refresh the belief book from promoted evidence
ao knowledge beliefs [flags]
Compile a goal-time briefing
ao knowledge brief [flags]
Flags:
--goal string Goal to compile into a briefing
-h, --help help for brief
Report thin topics, promotion gaps, and next mining work
ao knowledge gaps [flags]
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
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")
-h, --help help for lookup
--json JSON output
--limit int Maximum results to return (default 3)
--no-cite Skip citation recording
--query string Search query for relevance matching
--session string Session ID for citation tracking
Scan, normalize, link, and index .agents/ markdown into an Obsidian knowledge graph.
ao mind [command]
Subcommands:
Run full pipeline (normalize → link → index)
ao mind all [flags]
Show graph statistics
ao mind graph [flags]
Rebuild the graph index
ao mind index [flags]
Insert wikilinks between related artifacts
ao mind link [flags]
Add/fix YAML frontmatter on .agents/ markdown
ao mind normalize [flags]
Show what needs normalization
ao mind scan [flags]
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")
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-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)
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)
Manage derived session pages under .agents/ao/sessions without touching source transcripts.
ao sessions [command]
Subcommands:
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)
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
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)
Help provides help for any command in the application.
ao help [command] [flags]
Create, list, and validate holdout scenarios stored in .agents/holdout/.
ao scenario [command]
Subcommands:
Initialize .agents/holdout/ directory for scenario storage
ao scenario init [flags]
List holdout scenarios
ao scenario list [flags]
Flags:
-h, --help help for list
--status string Filter by status (active, draft, retired)
Validate holdout scenarios against schema
ao scenario validate [flags]