---
title: "CLI reference"
description: "Every assay verb, grouped by what you are doing."
---

```bash
assay --help
assay <command> --help
```

`--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](/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

```bash
assay --version
assay init --global
```

`--config-file` / `$ASSAY_CONFIG`. `--strict-config` in CI. See [Config](/config).