CLI Command Reference

Every command returns the standard JSON envelope. The CLI can also describe its live command contract:

cheqi schema
cheqi schema receipt add-product
cheqi receipts submit-download --help

session match, receipt finalize, receipts submit, and receipts submit-download accept:

See Configuration for the corresponding environment variables.

Create a local receipt draft.

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

Providing identification details at creation time lets receipt finalize perform matching and issuance later without a separate session match call.

Resolve a delivery route for an existing session. This network command requires one identification flag and one credential.

CHEQI_API_KEY=sk_... cheqi session match \
  --session order-42 \
  --card-par YOUR_CARD_PAR

The response includes routeFound, deliveryRouteType, matchId, expiresAt, and recipientCount. It also saves the identification details in the session. receipt finalize resolves the route again before issuance.

Inspect local session state:

cheqi session status --session order-42

The result includes match state, product count, totals, update time, and the next suggested command.

Delete the named local session draft:

cheqi session reset --session order-42

Update receipt-level fields with --document-number, --currency, --issue-date, or --note:

cheqi receipt set --session order-42 --document-number INV-002

Append a product line. Supply the name positionally or through --name.

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

With --price-incl, the CLI derives the net unit price and tax amount. With --unit-price, the supplied value is treated as the net price.

Return the complete local session, including identification details, receipt values, and calculated totals:

cheqi receipt preview --session order-42

Validate the definitive receipt locally without a network call:

cheqi receipt validate --session order-42

Success returns valid: true; invalid input returns RECEIPT_INVALID with structured details.

Resolve the current route, encrypt the definitive receipt locally, and issue it:

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

The session must contain identification details and a valid receipt. A prior session match call is optional.

Issue a complete receipt JSON file, or use --receipt - to read from standard input:

CHEQI_API_KEY=sk_... cheqi receipts submit \
  --receipt ./receipt.json \
  --match-by card_par \
  --match-value YOUR_CARD_PAR

Supported --match-by values are card_par, pairing_code, payment_account_identifier, email, and payment_type. For an anonymous matched fallback, use --match-by payment_type --match-value CASH (or CARD_PAYMENT / DIRECT_DEBIT).

The JSON must be a definitive SDK 2.2.1 ReceiptPayload. Supply issueDate, all totals, taxesApplied, and complete product values such as identifier, unitCode, subtotal, and total. The CLI validates and normalizes the payload but does not invent missing merchant values.

Create and upload a client-encrypted download receipt without customer matching:

CHEQI_API_KEY=sk_... cheqi receipts submit-download \
  --receipt ./receipt.json \
  --payment-type CASH

--payment-type accepts CARD_PAYMENT, CASH, or DIRECT_DEBIT and defaults to CASH. The result includes deliveryRouteType: "DOWNLOAD_FALLBACK" and downloadUrl. The URL fragment carries the decryption key; deliver the complete URL to the customer and do not log it server-side.

receipt finalize, receipts submit, and receipts submit-download return the same core fields:

• success and accepted
• deliveryRouteType
• status, matchId, and cheqiReceiptId when applicable
• createdAt and expiresAt when available
• downloadUrl and downloadId for a completed download fallback
• downloadEnvelopeRequired and emailReceiptRequired

• cheqi schema returns all command schemas; add a command path to narrow the result.
• cheqi version returns the installed CLI version.
• cheqi help and --help return the same machine-readable command descriptions.

CLI validation errors use stable codes including AUTH_REQUIRED, AUTH_CONFLICT, COMMAND_NOT_FOUND, ENV_UNSUPPORTED, FLAG_INVALID, FLAG_REQUIRED, INPUT_INVALID, RECEIPT_INVALID, SESSION_INVALID, and SESSION_NOT_FOUND.

Errors from the Cheqi API retain SDK context and can set retryable: true for transient failures. Branch on error.code and retryable, not the human-readable message.