--json on a read emits the raw object. Parse that. Human tables are for people.
Inspection verbs never create a database. Record first, or init / capture / serve / seed.
Every read accepts --db <path> or --pg <dsn> / $ASSAY_PG_DSN. Pass one, not both.
Common filters: --principal --session --task --project --since --until.
Look
| Command | |
|---|---|
assay show | Rollup: span count, tokens by phase, cost |
assay top --by principal|task|session | Highest-cost groups |
assay tail -n 20 | Latest spans, one line each |
assay turns | Decrypted timeline + cost. Debug |
assay transcripts list | Session index |
assay transcripts show | One sitting |
assay search "…" | What was said |
assay type | Spend per kind of work |
assay products | Path-product, both readings |
assay objectives | Tree + window counts |
assay unplaced | Sittings with no winning objective |
assay scopes | Where writes landed |
assay waste | Recoverable spend |
assay roi | Cost per outcome, yield, declared ROI |
assay outcomes | Result rows |
assay export --focus | FOCUS cost CSV, one row per span |
assay dashboard | Local console |
assay pricing check | Unpriced tripwire |
Fill
| Command | |
|---|---|
assay init | Config, empty store, content key |
assay capture claude-code|grok|codex|opencode | Harness logs |
assay capture --adapter | Custom harness |
assay sweep / sweep on / off | Timer + one-shot sweep |
assay seed | Deterministic synthetic corpus (creates the db) |
assay serve --tenants | OTLP door |
assay outcomes record | Append one outcome |
Label and correct
| Command | |
|---|---|
assay labelling on|off|run|session-end | Corpus labels |
assay declare | Type / objective / scopes, local door |
assay type run | Annotate type (heuristic, or --judge) |
assay classify run | Span work-type overlays |
assay value run | Valuation overlays |
assay attribute products | Path-product overlay |
assay attribute scopes | Write-scope overlay |
assay attribute objectives | Place on the tree |
assay attribute backfill | Bind outcomes to spend |
assay reprice run / ttl | Append cost corrections. Never edits a span. --dry-run first |
Network
| Command | |
|---|---|
assay pricing watch | The one network verb. Fetches public rate documents. Does not open the store. |
assay reconcile anthropic | Ledger vs Anthropic admin cost report |
Dangerous
| Command | |
|---|---|
assay shred --yes | Destroy one principal’s content key. Irreversible. |
assay transcripts prune | Age-based retention of turn rows |
assay transcripts reseal | Key-rotation rewrite of ciphertext only |
shred exits non-zero on a refused or partial erasure. Treat that as failure.
Config and version
--config-file / $ASSAY_CONFIG. --strict-config in CI. See Config.