> ## Documentation Index > Fetch the complete documentation index at: https://docs.kentron.ai/llms.txt > Use this file to discover all available pages before exploring further. # Reading receipts and driving jobs > Resolve a run to a stream, read and fork its receipt chain, audit every chain for integrity, and operate the job queue, memory and session search from a checkout. From a checkout you can read any run's [receipt chain](/core/receipts-and-streams) — the ordered, hash-linked record of everything that happened in it — end to end, branch it at a chosen point, audit every chain in the database for integrity, and drive the work queue directly — enqueue a job, wait for it, steer it, follow up on it, abort it. The same commands reach agent memory and full-text search over past chat sessions. All of them belong to the [developer CLI](/cli/from-source/overview). None of the commands on this page exists in the released binary. ## How a target is resolved Every command that takes `` resolves it the same way: 1. If the value contains a `/`, it is used as a stream name **verbatim**. No lookup happens. 2. Otherwise the store's stream list is searched for an exact name match. 3. Failing that, it is searched for any stream ending in `/runs/`. If none of those match: ``` Unable to resolve run/stream '' ``` So `receipt trace agents/triage/runs/run_abc` addresses a stream directly, while `receipt trace run_abc` searches for it. ## Reading a chain ### `receipt trace` ```bash theme={null} receipt trace [--json] [--output-file ] ``` Prints one line per receipt. Text mode is the index right-aligned to four characters, the ISO timestamp, and the event type, which falls back to `unknown` when a receipt has none: ``` 0 2026-01-01T00:00:00.000Z task.requested 1 2026-01-01T00:00:03.120Z task.completed ``` JSON mode returns `{ "stream": "…", "receipts": [ { "index", "ts", "isoTs", "type" } ] }`. ### `receipt replay` ```bash theme={null} receipt replay [--output-file ] ``` Dumps the **full body** of every receipt as `{ "stream": "…", "receipts": [ … ] }`. `receipt replay` is always JSON. `--json` is accepted by the parser and then ignored — there is no text mode, whether or not you pass the flag. ### `receipt inspect` ```bash theme={null} receipt inspect [--output-file ] ``` Always JSON, and returns `{ "stream": "…", "count": , "head": }`. `head` is the **last** entry in the chain — the newest receipt, not the first one. If you are looking for what started a run, read index `0` with `receipt trace` or `receipt replay` instead. ### `receipt fork` ```bash theme={null} receipt fork --at [--name ] ``` Writes branch metadata pointing at a position in an existing chain. * `--at` is required (`--at is required`) and must be a finite, non-negative number (`--at must be a non-negative number`). It is floored. * `--at` past the end of the chain is rejected by the runtime with `Cannot fork at ; valid range is 0..`. * `--name` defaults to `/branches/fork__`. It prints `{ "ok": true, "stream": "…", "at": , "branch": "…" }`. ## Auditing every chain: `receipt dst` ```bash theme={null} receipt dst [] [--prefix ] [--context] [--json] [--limit ] [--strict] [--output-file ] ``` `receipt simulate` is an undocumented alias for the same command. It walks every stream in the receipt store — optionally narrowed to those whose name starts with a prefix, given positionally or with `--prefix` — and audits each one for three things: chain **integrity**, **replay**, and **determinism**. `--context` additionally audits the Factory task context packets (manifest, context pack, prompt, memory script). The report counts streams by kind. The kinds it recognises are: `factory.objective`, `job`, `agent.history`, `agent.control`, `eval.run`, `computer_use.session`, `generic` Streams are sorted failures first, then by descending receipt count, then by name, so the interesting ones are at the top of both output modes. ```json theme={null} { "scannedAt": "…", "dataDir": "…", "streamCount": 12, "kinds": { "factory.objective": 0, "job": 0, "agent.history": 0, "agent.control": 0, "eval.run": 0, "computer_use.session": 0, "generic": 0 }, "statusCounts": {}, "integrityFailures": 0, "replayFailures": 0, "deterministicFailures": 0, "streams": [] } ``` `--limit ` affects **text output only**; the text renderer shows 20 streams by default and appends `- ... more stream(s) omitted` when it truncates. The JSON report always contains every stream. ### `--strict` is the gate Without `--strict`, `receipt dst` reports failures and exits `0`. With `--strict`, it prints the report first and *then* throws when any of the integrity, replay or deterministic failure counts is non-zero — including the equivalent counts from the `--context` audit when you asked for one: ``` error: DST audit found receipt issues ``` That message goes to standard error and the process exits `1`. `--strict` is the flag to put in a check script. ## Driving jobs: `receipt jobs` ```bash theme={null} receipt jobs … ``` `list` is also the default when you give no subcommand. Anything unrecognised throws `Unknown jobs subcommand ''`. Every subcommand reads and writes the job queue in Postgres, so all of them work with no Resonate server running. Only `enqueue` also asks Resonate to dispatch the new job, and that request is fire-and-forget: with no broker reachable the job is still recorded as `queued`, the command still succeeds, and nothing starts the work. Every `jobs` and `abort` call opens a Resonate poll connection regardless, so with the broker down each one also prints a `Resonate poll disconnected; retrying` warning to standard error. ### `receipt jobs list` ```bash theme={null} receipt jobs [list] [--status queued|leased|running|completed|failed|canceled] [--limit ] [--output-file ] ``` `--limit` defaults to 50 and is clamped to 1…500; a non-numeric value falls back to 50. `--status` is passed straight through without validation. Output is always JSON: `{ "jobs": [ … ] }`. ### `receipt jobs enqueue` ```bash theme={null} receipt jobs enqueue [--lane chat|collect|steer|follow_up] [--payload-json ''] \ [--job-id ] [--max-attempts ] [--session-key ] [--singleton-mode allow|cancel|steer] ``` A missing agent id throws `agent id is required`. `--payload-json` defaults to `{}` and must parse as a JSON object: valid JSON that is not an object throws `--payload-json must be a JSON object`, and text that is not JSON at all surfaces the parser's own `JSON Parse error: …`. `--max-attempts` defaults to `2` and the backend clamps it to 1…8; a non-numeric value throws `--max-attempts must be a number` before anything is enqueued. Output is `{ "ok": true, "job": { … } }`. An invalid `--lane` or `--singleton-mode` value is **silently dropped** rather than rejected. The command then enqueues with the backend defaults — lane `collect` and singleton mode `allow` — so a typo produces a job that runs on the wrong lane with no error. Check the returned job object rather than assuming your flag took effect. ### `receipt jobs wait` ```bash theme={null} receipt jobs wait [--timeout-ms ] [--output-file ] ``` Polls every 200 ms with a default timeout of 15 000 ms. A missing id throws `job id is required`; an unknown one throws `job not found: `. Always JSON: `{ "job": { … } }`. ### `receipt jobs steer` and `receipt jobs follow-up` ```bash theme={null} receipt jobs steer [--payload-json ''] receipt jobs follow-up [--payload-json ''] ``` Each queues a `steer` or `follow_up` queue command against the job, attributed to `receipt-cli`. An unknown job throws `job not found: `. Output is `{ "ok": true, "jobId": "…", "commandId": "…" }`. ### `receipt jobs abort` and `receipt abort` ```bash theme={null} receipt jobs abort [--reason ] receipt abort [--reason ] ``` Both route to the same handler. `--reason` defaults to `abort requested`, and the command is attributed to `receipt-cli`. A missing id throws `job id is required`. ## Memory: `receipt memory` ```bash theme={null} receipt memory … receipt memory prefs … ``` A missing subcommand throws `memory subcommand is required`; an unknown one throws `Unknown memory subcommand ''`. ### Every call needs a scope and an actor All subcommands except `prefs` take a `` positional; without it they throw `memory scope is required`. All of them, `prefs` included, require an actor identity — a user id and an organization id, from flags or from the saved CLI session. The errors name the subcommand: ``` memory. requires --user-id or RECEIPT_CONNECT_USER_ID memory. requires --organization-id or RECEIPT_CONNECT_ORGANIZATION_ID ``` Under `prefs` the prefix is `memory.prefs.` instead. Because the saved session seeds `RECEIPT_CONNECT_USER_ID` and `RECEIPT_CONNECT_ORGANIZATION_ID`, signing in with `receipt login` is normally enough and you never pass the flags. Every call records an audit entry carrying the user id, organization id, `source: "cli"`, `actor: "cli"` and the command name. ### The subcommands | Subcommand | Syntax | Limits and required flags | | ----------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `read` | `receipt memory read ` | `--limit` default 20, clamped 1…500 | | `search` | `receipt memory search [query…]` | `--query ` or trailing text, required — `memory search requires --query or trailing query text`; `--limit` default 20, clamped 1…500 | | `summarize` | `receipt memory summarize [query…]` | `--query`; `--limit` default 20, clamped 1…500; `--max-chars` default 2 400, clamped 100…12 000 | | `commit` | `receipt memory commit [text…]` | `--text ` or trailing text, required — `memory commit requires --text or trailing text`; `--tags a,b,c` is comma-split and trimmed | | `diff` | `receipt memory diff ` | `--from-ts ` **required** — `memory diff requires --from-ts`; `--to-ts ` optional | `read`, `search`, `summarize` and `diff` are always JSON and honour `--output-file`. `commit` prints its JSON directly and ignores `--output-file`. ### `receipt memory prefs` ```bash theme={null} receipt memory prefs [list] [--scope layered|repo|global] [--repo-root ] [--output-file ] receipt memory prefs add [text…] [--text ] [--scope …] receipt memory prefs remove [--scope …] ``` The subcommand defaults to `list`; an unknown one throws `Unknown memory prefs subcommand ''`. `--scope` defaults to `layered` and takes three values: * `layered` — the repo scope first, then the global scope * `repo` — the repo scope only * `global` — the global scope only The repo scope key is derived from `--repo-root` or the detected git root. `list` returns `{ "scopes": [ … ], "entries": [ … ] }`. `add` requires `--text` or trailing text (`memory prefs add requires --text or trailing text`) and returns `{ "entry": … }`. `remove` requires an entry id (`memory prefs remove requires an entry id`) and rejects an unknown one with `Unknown preference entry ''`, returning `{ "removed": …, "entryId": "…", "scope": "…" }`. ## Session search: `receipt sessions` ```bash theme={null} receipt sessions search [query…] [--query ] [--limit ] [--repo-key ] [--profile ] [--session-stream ] [--output-file ] receipt sessions read [--limit ] [--output-file ] ``` `sessions` queries the projected session messages in Postgres directly and needs **no** actor identity. A missing subcommand throws `sessions subcommand is required`; an unknown one throws `Unknown sessions subcommand ''`. * `search` runs a Postgres full-text search and requires a query, from `--query` or trailing text (`sessions search requires --query or trailing query text`). `--limit` defaults to 10, clamped 1…100. Output is `{ "results": [ … ] }`. * `read` requires a target (`sessions read requires a chat id or session stream`). A target containing `/sessions/` is treated as a session stream; anything else is treated as a chat id. `--limit` defaults to 200, clamped 1…1 000. Output is `{ "messages": [ … ] }`. ## Prerequisites, by group | Commands | What they need | | -------------------------------------------------------- | ------------------------------------------------------------------------------ | | `trace`, `replay`, `inspect`, `fork`, `dst` / `simulate` | Postgres, via `ZERO_UPSTREAM_DB` | | `sessions` | Postgres | | `memory`, `memory prefs` | Postgres, plus an actor identity from flags or a saved session | | `jobs`, `abort` | Postgres. A reachable Resonate server only to dispatch what `enqueue` records. | | `setup`, `login`, `connect`, `workspace`, `tools`, `mcp` | Network and a reachable gateway. No Postgres. | | `whoami`, `logout` | Nothing but the local session file. No network, no Postgres. | Without a Postgres connection string the failure is: ``` Receipt Postgres storage requires ZERO_UPSTREAM_DB. ``` Every developer CLI command loads the runtime module at **import time**, before the handler for your command runs — and before the arguments are even dispatched, so `receipt help` and `receipt whoami` fail exactly like `receipt trace`. Two configuration problems therefore fail the command with an error that never mentions the command you typed: * A `.receipt/config.json` that is not a JSON object throws `Factory config must be a JSON object`. * With no config file and no git repository, resolving the runtime throws `Factory runtime config requires a git repository or RECEIPT_REPO_ROOT. cwd= failed: git -C rev-parse --is-inside-work-tree`. If a command fails before printing anything, look at your config file and your working directory, not at the stream or job you asked for. The [`.receipt/bin/receipt` wrapper](/cli/from-source/overview) avoids the second one: it changes to the repository root and exports `RECEIPT_REPO_ROOT` before it starts. Next step: [see how Factory turns an objective into tasks](/cli/from-source/factory-overview).