mirror of
https://github.com/boshu2/agentops.git
synced 2026-09-14 15:08:13 +08:00
Bo
2d9f740977
Four defects observed live in a fresh-install smoke test of the `ao`
CLI: two in `ao gate check`, one in `ao doctor`, one in `ao init`. Each
is fixed at its root and pinned by L2 tests driven through the real
entry points in fixture repos.
## 1. `ao gate check` in a zero-commit repo died raw
**Observed** — in a repository between `git init` and the first commit:
```
gates: detect changed files: git show --name-only --pretty=format: HEAD: exit status 128
```
**Fix** (`cli/internal/gates/changedfiles.go`) —
`GitChangedFiles.Changed` translates the failure into the
`ErrUnbornHead` sentinel with a remedy. Translation runs only on the
failure path (the happy path keeps its single git invocation) and only
for HEAD-resolving scopes. Two probes keep the neighbouring causes
distinct: `rev-parse --git-dir` separates "not a git repository",
`rev-parse --verify HEAD` separates "bad revision in an explicit range".
`--scope staged` is excluded on purpose — `git diff --cached` works
before the first commit, which is why the message points there.
Live, after the fix:
```
ao gate: gate check: gates: detect changed files: no commits yet (unborn HEAD): scope "head"
needs a commit to compare against — make an initial commit, or run with an explicit scope
such as --scope staged after 'git add'
```
**Tests** (`changedfiles_test.go`, `gates_test.go`) — unborn-HEAD
fixture across `head`/`worktree`/`upstream`/`range`:
`errors.Is(ErrUnbornHead)`, no leaked git exit status, remedy text
present. Plus: the advertised `--scope staged` escape hatch actually
returns the staged set; two negative witnesses (non-repo, nonexistent
range base) keep git's own error; an orchestrator-level test proves the
message survives the `gates: detect changed files: %w` wrap.
## 2. Gate failed shellcheck on AgentOps' own installed skill scripts,
with an unusable repair hint
**Observed** — after `ao init` and a first commit in a user's own repo,
`shell.shellcheck-changed` FAILED on
`.agents/skills/cass/scripts/multi_machine_search.sh` (matched by the
`**/*.sh` glob), and the repair text read `inspect native gate
shell.shellcheck-changed in cli/internal/gates` — a path that does not
exist on a machine that installed the CLI.
**Fix A — scope** (`gates/routing.go`, `gates/orchestrator.go`,
`checks/native_inline.go`): paths under `.agents/skills/`,
`.claude/skills/`, `.codex/skills/`, `.gemini/skills/`,
`.cursor/skills/`, `.pi/skills/`, `agent/skills/` are installed copies
owned by their upstream source, never repository source. They are
dropped from the change set once, in the orchestrator, so routing and
every check's `RunContext` describe the same in-scope set; the native
checks' own `origin/main...HEAD` fallback applies the same filter so
Full mode cannot re-admit them. The agentops repository tracks nothing
under those prefixes (`git ls-files` → 0), so the exclusion cannot hide
a first-party change from a gate.
**Fix B — hints** (`gates/gates.go`, `checks/native_inline.go`): the
derived native-check hint now names the gate ID and the published docs
(`GateDocsURL`) instead of a Go source path, and all four native checks
carry an explicit plain-language remedy. Script-backed hints are
unchanged by design — `ScriptRunner` returns a first-class
not-applicable SKIP outside the agentops repo, so their `bash
scripts/...` rerun addresses a reader who has the checkout by
construction.
Live, after the fix — installed copies pass, a first-party file still
fails:
```
FAIL shell.shellcheck-changed | selected: changed file "scripts/deploy.sh" matched "**/*.sh"
| repair: run 'shellcheck -S warning <file>' on each reported shell file and fix the
warnings (install shellcheck if it is missing)
```
**Tests** (`checks/native_inline_test.go`, `gates/routing_test.go`,
`gates/gates_test.go`) — L2 through the real registry + real
orchestrator + real git + real shellcheck: a fixture repo whose only
shellcheck-triggering files are installed skill copies exits 0;
**negative witness** — the same bad script under `scripts/` still exits
1, so the filter narrows scope rather than defanging the gate. Plus a
routing-layer selection test with the same witness, a
path-classification table including near-misses (`skills/`,
`vendor/.claude/skills/`, `.agents/ao/learnings/`), and a registry-wide
invariant that no native check's effective repair hint names a
source-checkout path.
## 3. `ao doctor` gave installed users checkout-only advice and could
overcount broken links
**Observed** — audience `installed-user` was told to run `ao skills link
--dry-run` "from the AgentOps checkout" (they have none, and the command
fails closed outside one), alongside a "2 broken" count that a
dangling-symlink sweep did not corroborate.
**Fix** (`cli/internal/adapters/doctor/legacy.go`):
- *Advice*: the no-checkout branch now names the affected root and the
dangling count, and gives a remedy performable from where the reader
stands — remove the dangling links, then reinstall skills the way they
were installed (plugin, brew, or npx).
- *Counting*: `countLiveSkillLinks` derived brokenness from a single
`os.Stat(<link>/SKILL.md)` probe, which fails for **three** unrelated
reasons — the link dangles, the link resolves to something that is not a
skill package (a shared reference dir, or a plain file), or the target
is unreadable — and reported all three as broken. That conflation is the
overcount. It now returns a tri-state census: `Broken` means **dangling
and only dangling** (exactly what `find -L <root> -maxdepth 1 -type l`
prints), `Foreign` is a link that resolves but names no skill package,
`Live` is a working skill. Non-symlink entries (a plugin's real
directory) are counted in no bucket.
Live, after the fix — and the two reported links are genuinely dangling,
which the new wording now makes checkable:
```
! Skill Links 48 live portable skill link(s), 2 dangling (target no longer exists) under
/Users/…/.agents/skills; remove the dangling link(s), then reinstall skills
the way you installed them (plugin, brew, or npx)
```
**Tests** (`legacy_test.go`) — installed-user detail/Fix contain no
checkout-only command and *do* name the root, the count, and a remedy; a
fixture holding live + dangling + foreign-dir + foreign-file + real-dir
entries pins the exact census `{Live:2, Broken:1, Foreign:2}`; a
cross-check computes the dangling count independently (not via
production code) and asserts doctor's `Broken` equals it — the test that
closes the "doctor says N, find says fewer" contradiction.
## 4. `ao init` scaffolded `.agents/ao/**` with no ignore guidance
**Observed** — after one loop the tree was full of untracked scratch and
every user had to invent the same `.gitignore` rules by hand.
**Policy decision** (`cli/internal/initapp/initapp.go`): `ao init`
appends one commented, marker-delimited block to the working directory's
`.gitignore`, creating the file if absent. It ignores only machine-local
scratch — `.agents/ao/index/` (derived), `.agents/ao/sessions/`
(private), `.agents/ao/provenance/` (per-machine, merge-hostile),
`__pycache__/`. It **deliberately does not** ignore
`.agents/ao/intents/` or `.agents/ao/verdicts/`: whether loop evidence
belongs in version control is the consumer repository's policy, and
AgentOps owns no policy there (product boundary). Delete the block to
track everything.
The block targets the working directory rather than the enclosing git
root, so its relative patterns match the `.agents/ao/**` the same run
just created. Idempotency keys on the begin marker, not the body — a
user who trims the lines inside has made a local decision, and a second
init reports and respects it. Documented in the command's `Long` help
and the regenerated `cli/docs/COMMANDS.md`.
**Tests** (`initapp_test.go`, `commands/init/module_test.go`) — init
twice in a fresh dir leaves the marker present exactly once, both at the
app layer and L2 through the cobra command; existing `.gitignore`
content is preserved verbatim with no glued last line; an edited block
is left untouched; dry-run writes nothing and announces the append; help
documents both what is ignored and what is deliberately trackable. The
pre-existing assertion that init never touches ignore state was replaced
by a narrower one — no repository is initialized — since the ignore
block is now the intended behavior.
---
## Verification
- `cd cli && go build ./... && go vet ./... && go test ./...` → **2947
passed in 73 packages**, exit 0 (captured to a file; not piped).
- `golangci-lint run` → no issues.
- `bash scripts/regen-all.sh --check` → all generated projections
current (`cli/docs/COMMANDS.md` regenerated via
`scripts/generate-cli-reference.sh`).
- All four defects re-smoked end-to-end against a freshly built binary
in a throwaway repo.
Write scope stayed inside `cli/**` plus the generated
`cli/docs/COMMANDS.md`. No `skills/**`, `AGENTS.md`, or
`docs/architecture/**` changes.
31 KiB
31 KiB
ao CLI Reference
Auto-generated by
scripts/generate-cli-reference.sh. Do not edit manually. Re-run the script to update.
Global Flags
--config string Config file (default: ~/.agents/ao/config.yaml)
--dry-run Show what would happen without executing
-h, --help help for ao
--json Output as JSON (shorthand for -o json)
-o, --output string Output format (json, table, yaml) (default "table")
-v, --verbose Enable verbose output
--version version for ao
Commands
ao demo
Show the AgentOps product boundary:
ao demo [flags]
Flags:
--concepts explain the product boundary
-h, --help help for demo
--quick show the compact one-pass example
ao init
Create local evidence and verdict directories, then add one commented,
ao init [flags]
ao quick-start
AgentOps is a small semantic evidence layer around agent work.
ao quick-start [flags]
ao capabilities
Print the machine-readable contract for the whole ao CLI as JSON.
ao capabilities [flags]
ao doctor
Run health checks on your AgentOps installation.
ao doctor [command]
Flags:
--dry-run With --fix: print the plan, change nothing
--explain string Expand a single finding by id
--fix Apply fixers for findings (routes through mutate())
-h, --help help for doctor
--json Output results as JSON
--online Enable network probes (default: offline-only)
--only strings Scope to a subset of detectors or subsystems
--quick Run only fast-path detectors (< 200ms)
--robot Alias for --json with structured wrapper
--robot-triage Emit the mega-command triage JSON
--severity string Minimum severity to emit (P0|P1|P2|P3) (default "P3")
--since string Diff findings against an earlier run
--skip strings Inverse of --only
Subcommands:
ao doctor capabilities
Print the machine-readable doctor contract (JSON)
ao doctor capabilities [flags]
ao doctor diff
Show what --fix would change (read-only)
ao doctor diff [flags]
Flags:
-h, --help help for diff
--only strings Scope the fix-plan preview to finding ids or subsystems (comma-separated), mirroring --fix --only
ao doctor explain
Expand a single finding with full evidence
ao doctor explain <finding-id> [flags]
ao doctor fix
Run detectors, then apply fixers (backs up before every mutation)
ao doctor fix [flags]
ao doctor gc
Prune old runs (requires --yes and --before )
ao doctor gc [flags]
Flags:
--before string Prune runs started before this date (YYYY-MM-DD)
-h, --help help for gc
--yes Confirm pruning (required)
ao doctor health
Cheap one-line liveness summary
ao doctor health [flags]
ao doctor ls
List runs in .doctor/runs/
ao doctor ls [flags]
ao doctor robot-docs
Print the paste-ready agent handbook (Markdown)
ao doctor robot-docs [flags]
ao doctor undo
Restore from .doctor/runs//backups/ (run-id may be 'latest')
ao doctor undo <run-id> [flags]
Flags:
--dry-run Print the restore plan; do not execute
-h, --help help for undo
--strict Refuse if any backup is missing or hash-mismatched (default true)
ao gate
Run ordinary deterministic repository checks.
ao gate [command]
Subcommands:
ao gate check
Run the declarative deterministic check registry.
ao gate check [flags]
Flags:
--fail-fast stop after the first blocking check failure
--fast explicitly select the default fast changed-surface subset
--full run every registered deterministic check
--github-annotations emit GitHub Actions annotations for check results
-h, --help help for check
--json emit the machine-readable JSON report
--require-workflow-parity fail if the workflow references unregistered blocking scripts
--scope string changed-file scope: head|staged|worktree|upstream|range:<base>..<head> (default "head")
--workflow-coverage include workflow-to-registry coverage in the report
--workflow-path string workflow used for optional coverage comparison (default ".github/workflows/validate.yml")
ao redact
Read text on stdin, apply the canonical secret redactor (the same
ao redact [flags]
ao robot-docs
Print a paste-ready, agent-targeted handbook for the whole ao CLI.
ao robot-docs [flags]
ao status
Display the content-addressed intent and verdict evidence stored by AgentOps.
ao status [flags]
ao version
Display the version, build information, and runtime details.
ao version [flags]
ao 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.
ao eval outcomes [command]
ao eval outcomes compile
Compile a holdout-safe Outcomes rubric payload from a locked Task + criteria
ao eval outcomes compile <input.json> [flags]
ao eval outcomes ingest
Ingest an Outcomes score payload into the one council verdict record
ao eval outcomes ingest <score.json> [flags]
Flags:
--burn-ledger string path to a JSON HoldoutBurnLedger; when set, a holdout-split score registers a burn and is REFUSED if the (suite,gt) quota is exhausted (gate #3 runtime enforcement), persisted across invocations
--expect-judge-hash string refuse the ingest if the score's judge_content_hash does not match this value (gate #2 rubric-drift parity)
-h, --help help for ingest
--manifest-out string also write an eval-run.v1 manifest to <dir>/<run-id>/manifest.json so the verdict pipeline feeds the Knowledge Flywheel (closes the Outcomes→Flywheel loop)
--run-id string run id for the --manifest-out manifest; defaults to the score's run_id, then source_task_id (sanitized to the eval-run.v1 pattern)
ao eval run
Run a deterministic eval suite.
ao eval run <suite.json> [flags]
Flags:
--baseline string compare the run against a baseline run record
--baseline-mode string skill-on | skill-off | both — runs the suite once with skills loaded, once with hooks suppressed, or both for a delta scorecard (default "skill-on")
--context-mode string none | ab — run context-off/context-on legs over isolated AO_AGENTS_DIR roots (default "none")
--context-off-agents-dir string AO_AGENTS_DIR root for the context-off leg (defaults to suite fixtures)
--context-on-agents-dir string AO_AGENTS_DIR root for the context-on leg (defaults to suite fixtures)
--delta-out string write delta scorecard JSON to path (with --baseline-mode=both or --context-mode=ab)
-h, --help help for run
--out string write eval run record to path
--run-id string stable run id to use in the run record
--runtime string runtime override (static, mock, shell, claude, codex)
ao eval scenario
Create, list, validate, and evaluate holdout scenarios stored in .agents/holdout/.
ao eval scenario [command]
ao eval scenario add
Author a holdout scenario from a goal description
ao eval scenario add <goal> [flags]
Flags:
--expected-outcome string Expected observable outcome (default: inferred from goal)
-h, --help help for add
--narrative string Narrative description (default: inferred from goal)
--source string Scenario source (human, agent, prod-telemetry) (default "human")
--status string Scenario status (active, draft, retired) (default "draft")
--threshold float Satisfaction threshold in [0,1] (default 0.8)
ao eval scenario evaluate
Evaluate directive-linked scenarios and record satisfaction results
ao eval scenario evaluate [flags]
Flags:
--all Evaluate every directive's linked scenarios
--directive string Evaluate only the directive with this stable Directive ID
-h, --help help for evaluate
--json Emit the machine-readable evaluation report
--run-id string run_id recorded in the results artifact (default "ao-scenario-evaluate")
--timeout duration Per-check execution timeout (default 2m0s)
ao eval scenario init
Initialize .agents/holdout/ directory for scenario storage
ao eval scenario init [flags]
ao eval scenario list
List holdout scenarios
ao eval scenario list [flags]
Flags:
-h, --help help for list
--status string Filter by status (active, draft, retired)
ao eval scenario validate
Validate holdout scenarios against schema
ao eval scenario validate [flags]
ao eval scenario-ab
Run a knowledge-reuse holdout scenario with vs. without the gold pull (the discriminating A/B)
ao eval scenario-ab [flags]
Flags:
--control-only Run only the without-gold control arm and fail on ceiling/no-headroom
-h, --help help for scenario-ab
--output string Write the ScenarioDeltaScorecard JSON to this path
--scenario string Path to the scenario.v1 JSON file (required)
--timeout duration Per-arm timeout (0 = default 5m)
--token-budget int Fail the gate if summed arm token cost exceeds this (0 = default 200000)
ao eval scenario-moat
Aggregate moat-eligible scenario A/B scorecards into a publication verdict
ao eval scenario-moat [flags]
Flags:
-h, --help help for scenario-moat
--output string Write the MoatClaimResult JSON to this path
--scorecard stringArray Path to a ScenarioDeltaScorecard JSON (repeatable)
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
Open a new Run manifest for ; refuses on gate failure
ao eval task run <task-id> [flags]
Flags:
--allow-weak-labels Allow runs against confidence=weak ground-truth rows (gate #7)
--cross-spec Allow ModelSpec drift (gate #4)
--dry-run Run gates and exit without writing a Run manifest
--ground-truth string Ground-truth row id (head of supersession chain)
--harness string Harness id (recorded into manifest)
--harness-dir string Path to harness source dir for snapshot + gate #8
-h, --help help for run
--inspect-command string Inspect command recorded into the Run manifest (not executed yet)
--inspect-version string Inspect AI version stamped into manifest (default "0.3.216")
--model-spec string ModelSpec id, resolved from <evals-root>/models/<id>/spec.yaml
--n-samples int Override Suite.n_samples
--quick Mark Run as quick_session=true (excluded from --vs auto-baseline pool)
--rig-id string Rig identifier stamped into the Run manifest
--sample-split string Sample split (dev|holdout); default from suite
--seeds string Comma-separated seeds (>=3, per §4)
--suite string Suite id or path to suite.yaml (required)
ao eval task show
Print a registered Task summary
ao eval task show <task-id> [flags]
ao gc
Prepare and qualify the stock Gas City maintainer pack without owning a pack.
ao gc [command]
Subcommands:
ao gc check
Verify a prepared maintainer runtime read-only
ao gc check [flags]
Flags:
--city string Gas City root directory (required)
--gc-bin string Gas City 1.4 binary (default: gc on PATH)
-h, --help help for check
--pack-dir string resolved official gascity pack root (normally auto-detected)
--rig string rig directory inside the city (required)
--skills-source string AgentOps skills directory to link from (default: enclosing checkout, then installed skills root)
ao gc prepare
Stage the contained maintainer runtime and skill links for a rig
ao gc prepare [flags]
Flags:
--city string Gas City root directory (required)
--gc-bin string Gas City 1.4 binary (default: gc on PATH)
-h, --help help for prepare
--pack-dir string resolved official gascity pack root (normally auto-detected)
--rig string rig directory inside the city (required)
--skills-source string AgentOps skills directory to link from (default: enclosing checkout, then installed skills root)
ao gc recover-affinity
Clear stale required session-affinity assignments (dry-run by default)
ao gc recover-affinity [flags]
Flags:
--apply apply the recovery; the default is a read-only dry run
--city string Gas City root directory (required)
--gc-bin string Gas City 1.4 binary (default: gc on PATH)
-h, --help help for recover-affinity
--pack-dir string resolved official gascity pack root (normally auto-detected)
--rig string rig directory inside the city (required)
ao goals
Track, measure, and validate project fitness goals.
ao goals [command]
Flags:
--file string Path to goals file (auto-detects GOALS.md then GOALS.yaml)
-h, --help help for goals
--timeout int Check timeout in seconds (default 240)
Subcommands:
ao goals measure
Run goal checks and produce a snapshot
ao goals measure [flags]
Aliases:
measure, m
Flags:
--directives Output directives as JSON (skip gate checks)
--exclude-tag string Skip goals whose Tags include this value (e.g. long-cycle)
--goal string Measure a single goal by ID
-h, --help help for measure
--scenarios-only Evaluate only executable-spec scenario satisfaction; skip shell gate-command execution
--total-timeout int Overall measurement timeout in seconds (0 disables)
ao goals validate
Validate GOALS.yaml structure and wiring
ao goals validate [flags]
Aliases:
validate, v
ao goals drift
Compare snapshots for regressions
ao goals drift [flags]
Aliases:
drift, d
ao goals export
Export latest snapshot as JSON (for CI)
ao goals export [flags]
Aliases:
export, e
ao goals history
Show goal measurement history
ao goals history [flags]
Aliases:
history, h
Flags:
--goal string Filter history to a specific goal
-h, --help help for history
--since string Show entries since date (YYYY-MM-DD)
ao goals meta
Run and report meta-goals only
ao goals meta [flags]
ao goals render
Render the executable-spec layer as BDD/Gherkin text.
ao goals render [flags]
Flags:
-h, --help help for render
--out string Write Gherkin to this file instead of stdout
ao goals scenarios
Inspect the executable-spec scenarios linked to GOALS.md directives.
ao goals scenarios [flags]
Flags:
--directive int Filter by directive display number
--directive-id string Filter listing to one directive by stable Directive ID
-h, --help help for scenarios
--lint Lint the directive↔scenario link graph instead of listing
--strict With --lint, exit non-zero on warnings as well as errors
ao session
Inspect or export session evidence
ao session [command]
Subcommands:
ao session bootstrap
Report local orientation files without starting runtimes, probing
ao session bootstrap [flags]
Flags:
-h, --help help for bootstrap
--json Emit JSON
ao session handoff
Write a small handoff artifact without selecting work, claiming it,
ao session handoff [summary] [flags]
Flags:
--collect Collect best-effort read-only Git observations
--continuation string Caller-supplied continuation note
--dry-run Print the artifact without writing it
--goal string Caller-supplied goal
-h, --help help for handoff
ao session rehydrate
Read a handoff without consuming it, claiming work, or choosing a next action.
ao session rehydrate [flags]
Flags:
-h, --help help for rehydrate
--json Emit the stored artifact as JSON
ao completion
Generate shell completion scripts for ao.
ao completion [bash|zsh|fish|powershell]
ao config
View and manage AgentOps configuration.
ao config [flags]
Flags:
-h, --help help for config
--show Show resolved configuration with sources
ao provenance
Append and inspect generic, evidence-backed relationships between
ao provenance [command]
Subcommands:
ao provenance add
Append one schema-valid, hash-chained provenance edge linking a source
ao provenance add <from-id> <to-id> [flags]
Flags:
--evidence string Optional evidence pointer (path, commit, CI run URL, event id)
--from-type string Source node type (for example decision, artifact, or observation) (default "decision")
-h, --help help for add
--json Emit the sealed edge as JSON
--relation string Typed PROV-O relation (required), e.g. wasGeneratedBy
--to-type string Target node type (for example decision, artifact, or observation) (default "artifact")
--trust-tier string Trust tier (authored|inferred|mined) (default "authored")
--ts string Override the UTC RFC3339 timestamp (defaults to now)
ao provenance export
Read docs/provenance/ledger.jsonl, canonically sort its edges by
ao provenance export [flags]
Flags:
-h, --help help for export
--json Emit a single indented JSON array instead of JSONL
--verify Verify the re-chained export and print only a one-line summary
ao provenance list
Read the provenance edges recorded in docs/provenance/ledger.jsonl, in
ao provenance list [flags]
Flags:
--from-id string Filter to edges whose from_id matches
-h, --help help for list
--json Emit machine-readable JSON
--relation string Filter to edges with this relation
ao provenance mine-session
Parse a Claude Code or Codex session transcript and emit the per-inference
ao provenance mine-session --file <session.jsonl> [flags]
Flags:
--file string Path to the session transcript (.jsonl) to mine (required)
-h, --help help for mine-session
--json Emit events as JSONL on stdout (default true)
--state string Path to the incremental watermark state JSON (created/updated; omit for a full one-shot mine)
ao provenance position
Report the ledger record count and latest hash without inferring lifecycle state.
ao provenance position [flags]
Flags:
-h, --help help for position
--json Emit machine-readable JSON
ao provenance show
Read the provenance ledger and show every edge whose from_id or to_id
ao provenance show <node-id> [flags]
Flags:
-h, --help help for show
--json Emit machine-readable JSON
ao provenance trace
Audit a provenance trace-graph for orphans: engineered artifact nodes
ao provenance trace [flags]
Flags:
--graph string Path to the JSONL trace-graph to audit (required)
-h, --help help for trace
--json Emit each finding as one JSON object per line
--orphans Audit for artifact nodes with no inbound provenance edge
--strict Exit non-zero when any orphan exists
ao provenance verify
Read docs/provenance/ledger.jsonl exactly as committed and verify its
ao provenance verify [flags]
Flags:
-h, --help help for verify
--json Emit the machine-readable verify result as JSON
ao skills
Tooling for the skills/ source-of-truth and its skills-codex/
ao skills [command]
Subcommands:
ao skills check
Walk skills/ and skills-codex/, validating each skill's YAML
ao skills check [flags]
Flags:
-h, --help help for check
--json Emit machine-readable JSON
--skill string Restrict the audit to a single skill name
--strict Exit non-zero on any finding (CI mode)
ao skills consumers
Print the skills whose consumes[] list includes — i.e. who
ao skills consumers <skill> [flags]
Flags:
-h, --help help for consumers
--json Emit machine-readable JSON
ao skills find
Score every skills//SKILL.md against a free-text intent and
ao skills find <intent> [flags]
Flags:
-h, --help help for find
--json Emit machine-readable JSON on stdout
--limit int Maximum number of results to return (default 5)
ao skills graph
Render the skill execution/delegation graph (A --> B means A declares
ao skills graph [flags]
Flags:
--format string Graph output format (mermaid|json) (default "mermaid")
-h, --help help for graph
ao skills link
Scan skills/ and create a live-tier symlink for every skill dir that has
ao skills link [flags]
Flags:
--dest string Link into this single dir instead of the auto-detected roots (default: ~/.agents plus every installed runtime)
-h, --help help for link
--json Emit machine-readable JSON
ao skills list
Filter the generated skill catalog by hexagonal role, produced or
ao skills list [flags]
Flags:
--consumes string Filter to skills that consume this port/sibling
-h, --help help for list
--json Emit machine-readable JSON
--practice string Filter to skills that apply this practice
--produces string Filter to skills that produce this port/artifact
--role string Filter by hexagonal_role (domain, driving-adapter, ...)
--user-invocable string Filter by user-invocability (true|false)
ao skills producers
Print the skills whose produces[] list includes — i.e. who
ao skills producers <output> [flags]
Flags:
-h, --help help for producers
--json Emit machine-readable JSON
ao skills resolve
Walk skills/ and resolve the corpus toward MECE:
ao skills resolve [flags]
Flags:
-h, --help help for resolve
--json Emit machine-readable JSON
--strict Exit non-zero when ME overlaps are found (CI dedup gate)
ao skills unlink
The clean uninstall inverse of ao skills link. Scan each runtime's
ao skills unlink [flags]
Flags:
--dest string Sweep this single dir instead of the auto-detected roots (default: ~/.agents plus every installed runtime)
-h, --help help for unlink
--json Emit machine-readable JSON
ao workflows
Tooling for the top-level workflows/ source-of-truth: the Claude-harness
ao workflows [command]
Subcommands:
ao workflows link
Scan the agentops checkout's workflows/ directory and create a symlink in
ao workflows link [flags]
Flags:
-h, --help help for link
--into string Link into this single dir instead of <cwd-git-root>/.claude/workflows
--json Emit machine-readable JSON
ao workflows unlink
The clean uninstall inverse of ao workflows link. Sweep the target
ao workflows unlink [flags]
Flags:
-h, --help help for unlink
--into string Sweep this single dir instead of <cwd-git-root>/.claude/workflows
--json Emit machine-readable JSON
ao flywheel
Knowledge flywheel operations and status.
ao flywheel [command]
Subcommands:
ao flywheel compare
Compare retrieval quality between primary and shadow namespaces.
ao flywheel compare [flags]
Flags:
-h, --help help for compare
--shadow string Shadow namespace to compare against primary (default "shadow")
ao flywheel status
Display comprehensive flywheel health status.
ao flywheel status [flags]
Flags:
--days int Period in days for metrics calculation (default 7)
-h, --help help for status
--namespace string Citation namespace to evaluate (primary by default) (default "primary")
ao help
Help provides help for any command in the application.
ao help [command] [flags]