{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Cheqi CLI","description":"Complete documentation for integrating Cheqi's digital receipt platform","keywords":["cheqi","digital receipts","api","sdk","java","javascript"],"llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"cheqi-cli","__idx":0},"children":["Cheqi CLI"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Cheqi CLI (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@cheqi/cli"]},") is an agent-friendly command-line interface for the Cheqi receipt flow. Version ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0.3.2"]}," uses JavaScript SDK ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2.2.1"]}," to resolve delivery routes, encrypt the definitive merchant-supplied receipt locally, and issue it without a server-side receipt-template step."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Source code and releases: ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/cheqi-io/cli"},"children":["cheqi-io/cli"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"installation","__idx":1},"children":["Installation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The CLI requires Node.js 20 or newer."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"npm install --global @cheqi/cli@0.3.2\ncheqi version\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can also run it without a global installation:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"npx @cheqi/cli@0.3.2 version\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"receipt-workflows","__idx":2},"children":["Receipt workflows"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The CLI supports three workflows:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Incremental sessions"]}," use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session ..."]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["receipt ..."]}," commands to build a receipt across multiple calls. Drafts are stored under ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".cheqi/sessions/<session-id>.json"]}," in the current working directory."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Matched direct submission"]}," uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["receipts submit"]}," to issue a complete definitive receipt JSON document in one call."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Direct download issuance"]}," uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["receipts submit-download"]}," to create a client-encrypted download without customer matching."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The incremental flow is a good default when a script or agent gathers receipt data over time:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"cheqi session create \\\n  --session order-42 \\\n  --currency EUR \\\n  --document-number INV-001 \\\n  --card-par YOUR_CARD_PAR\n\ncheqi receipt add-product \\\n  --session order-42 \\\n  --name \"Coffee beans\" \\\n  --price-incl 12.10 \\\n  --vat 21\n\ncheqi receipt validate --session order-42\nCHEQI_API_KEY=sk_... cheqi receipt finalize --session order-42\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["receipt finalize"]}," resolves the route immediately before issuing the receipt. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session match"]}," earlier when you want to inspect the route and recipient count before finalization; finalization does not rely on that potentially stale response."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/cli/agent-workflows"},"children":["Agent Workflows"]}," for complete examples."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"response-envelope","__idx":3},"children":["Response envelope"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful command returns:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"ok\": true,\n  \"data\": {},\n  \"meta\": {\n    \"durationMs\": 12,\n    \"version\": \"0.3.2\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A failed command returns:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"ok\": false,\n  \"error\": {\n    \"code\": \"SESSION_NOT_FOUND\",\n    \"message\": \"No Cheqi session found for order-42.\",\n    \"retryable\": false,\n    \"details\": {\n      \"sessionId\": \"order-42\"\n    }\n  },\n  \"meta\": {\n    \"durationMs\": 4,\n    \"version\": \"0.3.2\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ok"]}," field is authoritative and matches the process exit code: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0"]}," for success and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]}," for failure. Standard output contains only the JSON envelope. With ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--verbose"]},", diagnostics go to standard error and do not corrupt parsed output."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configuration","__idx":4},"children":["Configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Network commands accept flags or equivalent environment variables. Flags take precedence."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Setting"},"children":["Setting"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Flag"},"children":["Flag"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Environment variable"},"children":["Environment variable"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Default"},"children":["Default"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Environment"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--env <sandbox|test|production>"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHEQI_ENV"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sandbox"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Custom API endpoint"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--endpoint <url>"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHEQI_API_ENDPOINT"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["selected environment"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Download receipt origin"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--download-base-url <url>"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHEQI_DOWNLOAD_BASE_URL"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["selected environment"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["API key"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--api-key <key>"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHEQI_API_KEY"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["OAuth access token"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--access-token <token>"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHEQI_ACCESS_TOKEN"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request timeout in seconds"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--timeout <n>"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHEQI_TIMEOUT_SECONDS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["30"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use exactly one credential for each network command: an API key or an OAuth access token. Supplying neither returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTH_REQUIRED"]},"; supplying both returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTH_CONFLICT"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Local commands such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session create"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["receipt add-product"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["receipt preview"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["receipt validate"]}," do not need credentials."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"agent-oriented-behavior","__idx":5},"children":["Agent-oriented behavior"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cheqi schema"]}," describes all commands, flags, enum values, and response schemas at runtime."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Stable error codes let callers branch without parsing human messages."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["retryable"]}," error field distinguishes transient failures from invalid input."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Operational responses include a structured ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nextStep"]}," when another command is expected."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Explicit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--session"]}," values isolate concurrent receipt drafts."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":6},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/cli/commands"},"children":["Command Reference"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/cli/agent-workflows"},"children":["Agent Workflows"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/sdk/javascript"},"children":["JavaScript SDK"]}]}]}]},"headings":[{"value":"Cheqi CLI","id":"cheqi-cli","depth":1},{"value":"Installation","id":"installation","depth":2},{"value":"Receipt workflows","id":"receipt-workflows","depth":2},{"value":"Response envelope","id":"response-envelope","depth":2},{"value":"Configuration","id":"configuration","depth":2},{"value":"Agent-oriented behavior","id":"agent-oriented-behavior","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"CLI Overview","description":"Install and configure the Cheqi CLI for encrypted receipt issuance from shells and autonomous agents","seo":{"title":"Cheqi CLI"}},"lastModified":"2026-08-11T23:21:19.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/cli/overview","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}