Receipts

An APAI receipt is the local proof record for an install attempt. It records the package, version, source, target platform, install mode, approval state, risk level, rollback command, wrapped-install source evidence, and the integrity evidence collected before any receipt write.

In v0.1, APAI verifies the live registry source, package manifest, install card checksum, payload manifest, checksum-pinned payload artifact bytes when declared, and local heuristic audit before writing a local receipt. prompt-preflight-starter, costguard, mcp-audit, agent-passport, coding-safe-mode, doc-brief, and private-workspace-policy declare checksum-pinned package-store artifacts. Remaining seed packages still declare no payload files. Locally pinned payload manifests can write verified artifacts only into the APAI package store and only when the operator passes --allow-package-writes. The current receipt commands are for evidence, troubleshooting, and agent handoff.

A non-dry-run local install writes a receipt under the resolved APAI state home. Use verification flags when you want the receipt to contain registry, package-manifest, wrapped-install, install-card, payload-manifest, payload artifact gate, artifact fetch, and scanner-finding evidence.

apai install coding-safe-mode --target local_cli --verify-source --verify-manifest --verify-card --verify-payload

# Receipt: ~/.apai/receipts/rcpt_00MP78O7XTFHCMJJ6VG32F0KHM.json
# Install ID: rcpt_00MP78O7XTFHCMJJ6VG32F0KHM

For tests, demos, and agent runs, route state into a sandbox with --home <path> or the APAI_HOME environment variable.

Use apai receipts list to see local receipt metadata without opening the receipt files manually. It returns newest receipts first with payload artifact gate status, artifact fetch status, scanner-finding counts, and does not create missing directories.

apai receipts list
apai receipts list --limit 5
apai receipts list --format json
apai receipts list --home C:\temp\apai-demo --format json

Use apai receipts show <install-id> when you know the install id and want the receipt summary or full JSON payload. The CLI only accepts safe rcpt_... ids, not arbitrary paths. The text summary includes payload artifact gate evidence, artifact fetch evidence, and the scanner-finding count recorded during install.

apai receipts show rcpt_00MP78O7XTFHCMJJ6VG32F0KHM
apai receipts show rcpt_00MP78O7XTFHCMJJ6VG32F0KHM --format json

Use apai receipts verify before treating a receipt as evidence in an agent handoff. This command is local-only and no-network. It checks that the stored receipt has the current v0.1 schema, install metadata, optional wrapped-install argv evidence, wrapped-install no-execution evidence, registry source evidence, install-card evidence, package-manifest evidence, payload-manifest evidence, payload artifact gate evidence, artifact fetch evidence, scanner findings, and either no-op or verified package-store payload execution evidence.

apai receipts verify rcpt_00MP78O7XTFHCMJJ6VG32F0KHM
apai receipts verify rcpt_00MP78O7XTFHCMJJ6VG32F0KHM --format json

The command returns a non-zero exit code when the receipt is missing or the local evidence is incomplete.

Use apai rollback with an install id when you want APAI to evaluate the exact receipt before undoing anything. In v0.1, rollback completes as a verified no-op when the receipt proves no package payload files were written. For verified package-store receipts, it can remove only files recorded under ~/.apai/packages/<slug>/<version>/. Arbitrary paths, modified files, wrapped installer writes, and unverified receipts block for manual review instead of deleting files.

apai rollback coding-safe-mode --install-id rcpt_00MP78O7XTFHCMJJ6VG32F0KHM
apai rollback coding-safe-mode --install-id rcpt_00MP78O7XTFHCMJJ6VG32F0KHM --dry-run
apai rollback coding-safe-mode --install-id rcpt_00MP78O7XTFHCMJJ6VG32F0KHM --format json

Non-dry-run rollback attempts write local evidence under ~/.apai/rollbacks/. Dry runs report what would be removed without writing rollback evidence or deleting package-store files.

apai state inspect gives a future agent one compact local state report: resolved paths, registry-cache status, receipt count, and recent receipt and rollback receipt summaries. Receipt summaries include payload mode, payload artifact gate, artifact fetch status, and scanner-finding counts. It is also read-only.

apai state inspect
apai state inspect --format json --receipt-limit 10 --rollback-limit 10
apai state inspect --home C:\temp\apai-demo --format json

Pair this with apai doctor --check-live when you need both local state and live endpoint health.

• Install Receipt Spec: receipt fields and privacy boundaries.
• Getting Started: first install walkthrough.
• Honest Status: what is shipped, scaffolded, stubbed, or not built.