{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"CLI Agent Workflows","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":"cli-agent-workflows","__idx":0},"children":["CLI Agent Workflows"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"discover-capabilities","__idx":1},"children":["Discover capabilities"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An agent can inspect the installed command contract instead of relying on a prompt-time copy:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"cheqi schema\ncheqi schema receipts submit\ncheqi schema receipts submit-download\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each schema includes flags, types, defaults, enum values, and a JSON Schema for the response."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Many successful responses include a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nextStep"]}," object:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"command\": [\"receipt\", \"validate\"],\n  \"requiredFlags\": [\"session\"],\n  \"optionalFlags\": [],\n  \"hint\": \"Validate locally before finalizing.\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"flow-1-build-incrementally","__idx":2},"children":["Flow 1: build incrementally"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use an explicit session ID for every call so concurrent agents never share implicit state:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"cheqi session create \\\n  --session agent-a \\\n  --currency EUR \\\n  --document-number INV-001 \\\n  --card-par YOUR_CARD_PAR\n\ncheqi receipt add-product \\\n  --session agent-a \\\n  --name \"Coffee beans\" \\\n  --price-incl 12.10 \\\n  --vat 21 \\\n  --sku SKU-COFFEE-001\n\ncheqi receipt validate --session agent-a\ncheqi receipt preview --session agent-a\nCHEQI_API_KEY=sk_... cheqi receipt finalize --session agent-a\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The draft is stored at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".cheqi/sessions/agent-a.json"]},". All commands before finalization are local. Finalization matches the current identification details, encrypts locally, and issues the definitive receipt."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To inspect delivery routing before adding products:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"CHEQI_API_KEY=sk_... cheqi session match \\\n  --session agent-a \\\n  --card-par YOUR_CARD_PAR\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The route is resolved again during finalization so issuance does not depend on a stale match response."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"flow-2-submit-a-complete-receipt","__idx":3},"children":["Flow 2: submit a complete receipt"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the agent already has a complete SDK 2.2.1 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ReceiptPayload"]},", skip local sessions:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"CHEQI_API_KEY=sk_... cheqi receipts submit \\\n  --match-by card_par \\\n  --match-value YOUR_CARD_PAR \\\n  --receipt ./receipt.json\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"flow-3-create-a-download-receipt","__idx":4},"children":["Flow 3: create a download receipt"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When customer matching is not required, issue an end-to-end encrypted download directly:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"CHEQI_API_KEY=sk_... cheqi receipts submit-download \\\n  --receipt ./receipt.json \\\n  --payment-type CASH\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"integration-guidance","__idx":5},"children":["Integration guidance"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Parse ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ok"]}," first and read either ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}," accordingly."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Branch on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.code"]},", not the human-readable message."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Retry only when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.retryable"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Supply credentials through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHEQI_API_KEY"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHEQI_ACCESS_TOKEN"]}," so secrets do not appear in command histories or process arguments."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Capture standard error separately when using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--verbose"]},"; standard output remains one JSON envelope."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Give each concurrent workflow a unique session ID."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Follow ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nextStep.command"]}," when present, supplying the listed required flags from agent context."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"choosing-cli-sdk-or-mcp","__idx":6},"children":["Choosing CLI, SDK, or MCP"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/sdk/javascript"},"children":["JavaScript SDK"]}," when Cheqi is embedded in a Node.js application."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use the CLI when the caller can run shell commands and benefits from a ready-made JSON tool surface."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/mcp/overview"},"children":["MCP server"]}," when the agent operates through an MCP host."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The CLI wraps the JavaScript SDK and keeps matching, receipt serialization, and encryption within the merchant-controlled process."]}]},"headings":[{"value":"CLI Agent Workflows","id":"cli-agent-workflows","depth":1},{"value":"Discover capabilities","id":"discover-capabilities","depth":2},{"value":"Flow 1: build incrementally","id":"flow-1-build-incrementally","depth":2},{"value":"Flow 2: submit a complete receipt","id":"flow-2-submit-a-complete-receipt","depth":2},{"value":"Flow 3: create a download receipt","id":"flow-3-create-a-download-receipt","depth":2},{"value":"Integration guidance","id":"integration-guidance","depth":2},{"value":"Choosing CLI, SDK, or MCP","id":"choosing-cli-sdk-or-mcp","depth":2}],"frontmatter":{"title":"CLI Agent Workflows","description":"End-to-end Cheqi CLI workflows and integration guidance for autonomous agents","seo":{"title":"CLI Agent Workflows"}},"lastModified":"2026-08-11T23:21:19.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/cli/agent-workflows","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}