CLI Agent Workflows

The Cheqi CLI is designed to be driven reliably by scripts and autonomous agents. It has explicit session isolation, machine-readable schemas, stable error codes, and structured next-step hints.

An agent can inspect the installed command contract instead of relying on a prompt-time copy:

cheqi schema
cheqi schema receipts submit
cheqi schema receipts submit-download

Each schema includes flags, types, defaults, enum values, and a JSON Schema for the response.

Many successful responses include a nextStep object:

{
  "command": ["receipt", "validate"],
  "requiredFlags": ["session"],
  "optionalFlags": [],
  "hint": "Validate locally before finalizing."
}

Use an explicit session ID for every call so concurrent agents never share implicit state:

cheqi session create \
  --session agent-a \
  --currency EUR \
  --document-number INV-001 \
  --card-par YOUR_CARD_PAR

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

cheqi receipt validate --session agent-a
cheqi receipt preview --session agent-a
CHEQI_API_KEY=sk_... cheqi receipt finalize --session agent-a

The draft is stored at .cheqi/sessions/agent-a.json. All commands before finalization are local. Finalization matches the current identification details, encrypts locally, and issues the definitive receipt.

To inspect delivery routing before adding products:

CHEQI_API_KEY=sk_... cheqi session match \
  --session agent-a \
  --card-par YOUR_CARD_PAR

The route is resolved again during finalization so issuance does not depend on a stale match response.

When the agent already has a complete SDK 2.2.1 ReceiptPayload, skip local sessions:

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

Use --receipt - to read JSON from standard input. The CLI validates the definitive payload but does not infer missing totals, tax treatment, identifiers, or line values.

When customer matching is not required, issue an end-to-end encrypted download directly:

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

The returned downloadUrl contains the AES content key in its URL fragment. Treat the complete URL as sensitive: deliver or render it as a QR code for the customer and avoid server-side logging.

• Parse ok first and read either data or error accordingly.
• Branch on error.code, not the human-readable message.
• Retry only when error.retryable is true.
• Supply credentials through CHEQI_API_KEY or CHEQI_ACCESS_TOKEN so secrets do not appear in command histories or process arguments.
• Capture standard error separately when using --verbose; standard output remains one JSON envelope.
• Give each concurrent workflow a unique session ID.
• Follow nextStep.command when present, supplying the listed required flags from agent context.

• Use the JavaScript SDK when Cheqi is embedded in a Node.js application.
• Use the CLI when the caller can run shell commands and benefits from a ready-made JSON tool surface.
• Use the MCP server when the agent operates through an MCP host.

The CLI wraps the JavaScript SDK and keeps matching, receipt serialization, and encryption within the merchant-controlled process.