Receipt CLI

The CLI supports both Universal Receipt and the original seller-specific Agent API commands. Universal commands call the same catalogue, quote, policy, purchase, transaction, and wallet services as the root MCP server.

The unpublished 0.1.3 source candidate requires Node.js 20 or newer and does not require Bun or a TypeScript runtime:

npx -y @receiptprotocol/[email protected] --help
npx -y @receiptprotocol/[email protected] setup openclaw --help
npx -y @receiptprotocol/[email protected] setup openclaw --ref <code>

receipt auth login
receipt discover "search the web" --ranking cheapest
receipt quote <offer-version-id> --args-json '{"query":"OpenAI"}'
receipt purchase <quote-id> --yes
receipt account status
receipt policy show
receipt transactions list
receipt transactions get <transaction-id>
receipt verify ./receipt.json

receipt quote always prints seller, action, price ceiling, policy outcome, and expiry before a paid command can run. It does not reserve funds or contact the provider. receipt purchase requires --yes, reuses one idempotency key across retries, opens Receipt-hosted approval URLs, and resumes the exact purchase after a one-time approval or standing connection allowance executes.

The legacy receipt wallet, receipt tools, and receipt receipts commands remain available for compatibility. Refresh credentials stay in macOS Keychain; access credentials remain memory-only.

OpenClaw setup

Start the referral-bound OpenClaw activation flow with:

receipt setup openclaw --ref <code>

Use --dry-run to validate the public capability card and setup plan without changing OpenClaw or starting OAuth. --no-open-browser leaves owner authorization to the displayed URL, --yes acknowledges OpenClaw's skill installation risk prompt, and --json emits the stable machine-readable envelope. Run receipt setup openclaw --help for the complete command help.

Offline Open Receipt verification

receipt verify parses and verifies an Open Receipt v0.1 event or bundle entirely on the local machine. It does not call Receipt's verification API.

receipt verify ./receipt.json
receipt verify ./receipt.json --issuer-metadata ./cached-issuer.json
receipt verify ./receipt-bundle.json --require-complete-chain

An embedded public key proves the mathematical signature, but does not pin the claimed issuer identity. Supply issuer metadata obtained through a trusted path to pin that identity. The command reports signature validity, event hash, parent-chain status, key source, and issuer-trust status separately.

@receiptprotocol/cli is the macOS-first command-line client for the Receipt Agent API at https://receiptprotocol.com.

Security model

• Exactly one generic-password entry is used: service com.receiptprotocol.cli, account default.
• That entry contains only the rotating refresh token; no access-token Keychain entry exists.
• Access tokens live in process memory only.
• Refresh rotation uses Keychain's atomic security add-generic-password -U update.
• A user-local filesystem lock serializes Keychain read, refresh exchange, and rotated-token replacement across concurrent CLI processes.
• Definitively rejected refresh credentials are removed from Keychain; transient network failures leave them intact.
• Tokens, device codes, and authorization headers are never written to output.
• Logout revokes the server session before deleting the Keychain item.

Local development

bun install
bun run check
bun link
receipt --help

JSON commands return { "ok": true, "command": "...", "data": ... }. Errors return a stable error code and exit code. Paid calls require --yes and automatically use one UUID idempotency key for every attempt in that logical invocation.

Production smoke test

This is intentionally excluded from automated tests and makes a real paid receipt_labs.demo_echo call using the logged-in Keychain session:

bun run smoke:production

Do not run it from CI.