chio receipt

List, explain, audit, and checkpoint the signed receipts the kernel writes for each decision, refusals included.

On this page

chio receipt

Query and list receipts from the receipt store.

Command synopsistext

chio receipt [OPTIONS] <COMMAND>

chio receipt list List receipts with optional filters. Output: one JSON receipt per line (JSON Lines).
chio receipt health Report receipt-store write health and durability status.
chio receipt flush Flush pending receipt writes to durable storage, bounded by a timeout.
chio receipt audit Run the full receipt-log audit: claim-log projection validation plus a complete checkpoint-chain verification (the deep check).
chio receipt retention Inspect or repair the receipt-store retention state.
chio receipt checkpoint Inspect or advance the receipt-checkpoint chain.
chio receipt explain Explain why a receipt was allowed or denied.
chio receipt verify Verify receipt signatures, the signer pin, and action hashes offline, one JSON receipt per line.
chio receipt verify-process-response Bind a process response to a frozen request and an independently selected context; verifies the receipt, the result content, and the decision.
chio receipt verify-native-start Verify a released native launch against its signed policy and external pins; does not establish target death, call completion, or a terminal outcome.

chio receipt list

List receipts with optional filters. Output: one JSON receipt per line (JSON Lines).

Command synopsistext

chio receipt list [OPTIONS]

--capability <CAPABILITY> Filter by capability ID.
--tool-server <TOOL_SERVER> Filter by tool server ID.
--tool-name <TOOL_NAME> Filter by tool name.
--outcome <OUTCOME> Filter by decision outcome (allow, deny, cancelled, incomplete).
--since <SINCE> Filter: receipts with timestamp >= this Unix seconds value.
--until <UNTIL> Filter: receipts with timestamp <= this Unix seconds value.
--min-cost <MIN_COST> Filter: minimum cost in minor currency units (only financial receipts).
--max-cost <MAX_COST> Filter: maximum cost in minor currency units (only financial receipts).
--cost-currency <COST_CURRENCY> Currency for cost filters as a three-letter uppercase code.
--limit <LIMIT> Maximum number of receipts per page. Default 50.
--cursor <CURSOR> Cursor for pagination (seq value to start after).
--tenant <TENANT> Tenant read boundary for the listing. The reading path fails closed when neither --tenant nor --admin-all is supplied.
--admin-all Explicitly read across all tenants as an administrative operation.
--agent <AGENT> Agent to select, by the name you gave it (fixer) or its DID; resolved to the agent’s subject key from the operator’s agents.
--order <ORDER> Order of the listing. Default oldest. Values oldest, newest.

chio receipt health

Report receipt-store write health and durability status.

Command synopsistext

chio receipt health [OPTIONS]

chio receipt flush

Flush pending receipt writes to durable storage, bounded by a timeout.

Command synopsistext

chio receipt flush [OPTIONS]

--timeout-ms <TIMEOUT_MS> Maximum time to wait for the flush to complete, in milliseconds. Default 5000.

chio receipt audit

Run the full receipt-log audit: claim-log projection validation plus a complete checkpoint-chain verification (the deep check).

Command synopsistext

chio receipt audit [OPTIONS]

--repair OFFLINE on-disk repair: revalidate the on-disk receipt chain on a local connection before reporting. Run this with the kernel STOPPED. A running kernel keeps its verified head in-memory in a separate process that the CLI cannot reach, so this does NOT clear a live poisoned writer; restart the kernel to reseed a clean head from the validated on-disk state.

chio receipt retention

Inspect or repair the receipt-store retention state.

Command synopsistext

chio receipt retention [OPTIONS] <COMMAND>

chio receipt retention repair

Repair a receipt store bricked by a retention rotation that left orphaned claim-log rows: remove the rows whose source receipts were archived and deleted, restoring a writable, reopenable store. Fail-closed.

Command synopsistext

chio receipt retention repair [OPTIONS] --archive <ARCHIVE>

--archive <ARCHIVE> Archive file that holds the co-archived claim-log rows to validate the removal against. Required.

chio receipt checkpoint

Inspect or advance the receipt-checkpoint chain.

Command synopsistext

chio receipt checkpoint [OPTIONS] <COMMAND>

chio receipt checkpoint status Report the current receipt-checkpoint chain status.
chio receipt checkpoint create Create the next receipt checkpoint, signed by the kernel keypair.
chio receipt checkpoint verify Verify the integrity of the receipt-checkpoint chain.

chio receipt checkpoint status

Report the current receipt-checkpoint chain status.

Command synopsistext

chio receipt checkpoint status [OPTIONS]

--max-batch <MAX_BATCH> Maximum number of receipts to consider per checkpoint batch. Default 1024.

chio receipt checkpoint create

Create the next receipt checkpoint, signed by the kernel keypair.

Command synopsistext

chio receipt checkpoint create [OPTIONS]

--kernel-seed-file <KERNEL_SEED_FILE> Kernel checkpoint signing-seed file.
--max-batch <MAX_BATCH> Maximum number of receipts to include in the checkpoint batch. Default 1024.

chio receipt checkpoint verify

Verify the integrity of the receipt-checkpoint chain.

Command synopsistext

chio receipt checkpoint verify [OPTIONS]

chio receipt explain

Explain why a receipt was allowed or denied.

Command synopsistext

chio receipt explain [OPTIONS] <RECEIPT_ID>

<RECEIPT_ID> Receipt ID. Use a sentinel (e.g. bilateral) when reading a bilateral artifact via --input-file; the receipt_id is informational for that path. Required.
--input-file <INPUT_FILE> Optional JSON file containing one receipt, or a BilateralCoSignArtifacts document.
--depth <DEPTH> Maximum parent depth to render. Default 8.
--fanout-limit <FANOUT_LIMIT> Maximum fanout siblings to render per level. Default 32.
--inspect-bilateral Emit a structural inspection trace of the bilateral envelope. Note: this trace does NOT perform Ed25519 signature verification. For real verification, use the kernel-resident chio_federation::bilateral_dsse::verify_dsse_envelope against pinned passport keys.
--tenant <TENANT> Tenant read boundary for the explanation. The reading path fails closed when neither --tenant nor --admin-all is supplied.
--admin-all Explicitly read across all tenants as an administrative operation.

Additional behavior

When --input-file points at a BilateralCoSignArtifacts JSON document (the federation signature-slice API emission with both a dualSignedReceipt and a dsseEnvelope), the renderer auto-detects the bilateral shape and prints both the non-section-6-conformant DualSignedReceipt section (NON-SECTION-6-CONFORMANT per B4) and the DSSE signature-slice section. It does not claim strict Chio DSSE section 6 predicate conformance.

Pass --inspect-bilateral to additionally emit a structural **inspection trace** of the envelope (structural / schema checks only). Ed25519 signature verification is NOT performed: the CLI does not carry the org A / org B passport public keys, so the trace makes no cryptographic-verification claim. --explain-bilateral is retained as an alias.

Example from the first-call project

Run from the first-call example project. For evidence verification, first export the evidence package.

first-call · receipt-explaintranscript

$ RECEIPT=$(chio --receipt-db .chio/receipts.db receipt list --admin-all \
    | jq -r 'select(.decision.verdict == "allow") | .id')
$ chio --receipt-db .chio/receipts.db receipt explain "$RECEIPT" --admin-all

receipt: 5f61461c24462125fb4c6220847b787c2917c0898cfe6c2a043d4a0eba2dd1de
schema: chio.receipt.v1
identity: 5f61461c24462125fb4c6220847b787c2917c0898cfe6c2a043d4a0eba2dd1de
decision: allow
policy_hash: 69e943b96e9ce64d0264bb56bf8930e77bd4e68adf68fcf1395790dae03e6b55
scope_diff: requested scope vs granted scope is not embedded in this receipt
parents: 0

exit 0in my-agent

chio receipt verify

Verify receipt signatures, the signer pin, and action hashes offline, one JSON receipt per line.

Command synopsistext

chio receipt verify [OPTIONS] --input <INPUT> --trusted-kernel-pubkey <TRUSTED_KERNEL_PUBKEY>

--input <INPUT> One original JSON receipt per line. Blank lines are ignored. Required.
--trusted-kernel-pubkey <TRUSTED_KERNEL_PUBKEY> Independently trusted kernel public key (raw bytes or algorithm-aware hex). Required.

Additional behavior

Does not re-evaluate policy or establish log inclusion or completeness.

chio receipt verify-process-response

Bind a process response to a frozen request and an independently selected context; verifies the receipt, the result content, and the decision.

Command synopsistext

chio receipt verify-process-response [OPTIONS] --response <RESPONSE> --request <REQUEST> --context <CONTEXT> --trusted-kernel-pubkey <TRUSTED_KERNEL_PUBKEY>

--response <RESPONSE> Process response to verify. Required.
--request <REQUEST> The frozen request the response must answer. Required.
--context <CONTEXT> JSON object with runtime_id, process_id, and capability_id from the host. Required.
--trusted-kernel-pubkey <TRUSTED_KERNEL_PUBKEY> Independently trusted kernel public key. Required.

chio receipt verify-native-start

Verify a released native launch against its signed policy and external pins; does not establish target death, call completion, or a terminal outcome.

Command synopsistext

chio receipt verify-native-start [OPTIONS] --signed-policy <SIGNED_POLICY> --enforcement <ENFORCEMENT> --server-id <SERVER_ID> --trusted-policy-signer <TRUSTED_POLICY_SIGNER> --expected-receipt-id <EXPECTED_RECEIPT_ID> --expected-target-sha256 <EXPECTED_TARGET_SHA256>

--signed-policy <SIGNED_POLICY> Signed native-launch policy. Required.
--enforcement <ENFORCEMENT> One original enforcement receipt, in JSON. Required.
--server-id <SERVER_ID> Server the launch belongs to. Required.
--trusted-policy-signer <TRUSTED_POLICY_SIGNER> Independently trusted policy signer, as algorithm-aware public-key hex. Required.
--expected-receipt-id <EXPECTED_RECEIPT_ID> Receipt id the enforcement receipt must carry. Required.
--expected-target-sha256 <EXPECTED_TARGET_SHA256> SHA-256 of the target executable the launch must have run. Required.