Exit codes of the other commands

Exit	Meaning
0	success
1	the daemon answered with a Problem (standard error shows its code and detail), begin refused, a claim number could not be resolved (nothing was sent), resume --pack does not fit its budget even at level 5, or a command that needs a token found none (standard error names the places looked at; nothing was sent)
2	usage error (including a label-like --evidence value that is not a run label), or a token that cannot be sent because it contains a line break; nothing was sent
3	the daemon is unreachable
4	the response violates the contract
5	memprove ledger verify only: the check ran and a record does not hold
6	the response is larger than the CLI accepts (16 MiB for a Task Capsule, 1 MiB otherwise)

A 400 Problem always carries a detail that names the field or parameter and the rule it breaks; the CLI prints it after the code on standard error and never repeats a token or a value from your request. A 401 or 403 has no detail, except 403 role_forbidden, one fixed sentence that says what a sub_agent Session may not write and who does it instead. A 409 capsule_tampered on a read means a stored record the read needs is missing, does not decode, or does not recompute, or the Project’s state database is not bound to it; its retryable is false. Do not retry it: run memprove ledger verify. Only 503 service_not_ready is worth a retry.

memprove ledger verify

memprove ledger verify                         # the Project of the current context
memprove ledger verify --project <PROJECT_ID>  # another Project; wins over the context

Inside a Workspace with a current context no --project is needed; an explicit --project wins; with neither it is a usage error (exit 2). It recomputes the Project’s Event chain and every Evidence, Snapshot and Checkpoint digest, writes nothing, and prints a report: how many records it checked of each kind (events, tasks, checkpoints, snapshots, evidence), the chain-head digest, whether the ledger is consistent (valid), and, when it is not, the first record that does not hold (first_failure: record type, ID, Project sequence, reason). It exits 0 when valid is true (the command exits 0; 5 means a record does not hold). It exits 5, not 1, when the check ran and a record does not hold; exit 1 means the daemon refused the request, so a script can tell “the ledger is damaged” from “the request failed”. A row the check cannot read is a finding too, never an error. The check cannot see a truncated chain tail or a whole-chain recomputation by the same OS user; an external anchor for the chain head is not part of this version.

From docs/guide.md at 2625064cbf0a · Markdown