# 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.

## Discover capabilities

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

```bash
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:

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

## Flow 1: build incrementally

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

```bash
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:

```bash
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.

## Flow 2: submit a complete receipt

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

```bash
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.

## Flow 3: create a download receipt

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

```bash
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.

## Integration guidance

- 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.


## Choosing CLI, SDK, or MCP

- Use the [JavaScript SDK](/sdk/javascript) 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](/mcp/overview) 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.