Cheqi CLI

The Cheqi CLI (@cheqi/cli) is an agent-friendly command-line interface for the Cheqi receipt flow. Version 0.3.2 uses JavaScript SDK 2.2.1 to resolve delivery routes, encrypt the definitive merchant-supplied receipt locally, and issue it without a server-side receipt-template step.

Every command writes one machine-readable JSON envelope to standard output. The CLI does not use interactive prompts, which makes it suitable for scripts, CI jobs, and autonomous agents.

Source code and releases: cheqi-io/cli

The CLI requires Node.js 20 or newer.

npm install --global @cheqi/cli@0.3.2
cheqi version

You can also run it without a global installation:

npx @cheqi/cli@0.3.2 version

The CLI supports three workflows:

• Incremental sessions use session ... and receipt ... commands to build a receipt across multiple calls. Drafts are stored under .cheqi/sessions/<session-id>.json in the current working directory.
• Matched direct submission uses receipts submit to issue a complete definitive receipt JSON document in one call.
• Direct download issuance uses receipts submit-download to create a client-encrypted download without customer matching.

The incremental flow is a good default when a script or agent gathers receipt data over time:

cheqi session create \
  --session order-42 \
  --currency EUR \
  --document-number INV-001 \
  --card-par YOUR_CARD_PAR

cheqi receipt add-product \
  --session order-42 \
  --name "Coffee beans" \
  --price-incl 12.10 \
  --vat 21

cheqi receipt validate --session order-42
CHEQI_API_KEY=sk_... cheqi receipt finalize --session order-42

receipt finalize resolves the route immediately before issuing the receipt. Use session match earlier when you want to inspect the route and recipient count before finalization; finalization does not rely on that potentially stale response.

See Agent Workflows for complete examples.

A successful command returns:

{
  "ok": true,
  "data": {},
  "meta": {
    "durationMs": 12,
    "version": "0.3.2"
  }
}

A failed command returns:

{
  "ok": false,
  "error": {
    "code": "SESSION_NOT_FOUND",
    "message": "No Cheqi session found for order-42.",
    "retryable": false,
    "details": {
      "sessionId": "order-42"
    }
  },
  "meta": {
    "durationMs": 4,
    "version": "0.3.2"
  }
}

The ok field is authoritative and matches the process exit code: 0 for success and 1 for failure. Standard output contains only the JSON envelope. With --verbose, diagnostics go to standard error and do not corrupt parsed output.

Network commands accept flags or equivalent environment variables. Flags take precedence.

Use exactly one credential for each network command: an API key or an OAuth access token. Supplying neither returns AUTH_REQUIRED; supplying both returns AUTH_CONFLICT.

Local commands such as session create, receipt add-product, receipt preview, and receipt validate do not need credentials.

• cheqi schema describes all commands, flags, enum values, and response schemas at runtime.
• Stable error codes let callers branch without parsing human messages.
• The retryable error field distinguishes transient failures from invalid input.
• Operational responses include a structured nextStep when another command is expected.
• Explicit --session values isolate concurrent receipt drafts.

• Command Reference
• Agent Workflows
• JavaScript SDK