# CLI Command Reference

Every command returns the standard [JSON envelope](/cli/overview#response-envelope). The CLI can also describe its live command contract:

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

## Command groups

| Group | Commands | Network use | Purpose |
|  --- | --- | --- | --- |
| `session` | `create`, `match`, `status`, `reset` | `match` only | Manage a local receipt draft and optionally inspect recipient resolution. |
| `receipt` | `set`, `add-product`, `preview`, `validate`, `finalize` | `finalize` only | Edit, validate, and issue a session receipt. |
| `receipts` | `submit`, `submit-download` | yes | Issue a complete receipt document without a session. |
| meta | `schema`, `version`, `help` | no | Discover capabilities and inspect the installed version. |


## Shared network flags

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

| Flag | Required | Default |
|  --- | --- | --- |
| `--api-key <key>` or `--access-token <token>` | one credential | environment variables |
| `--env <sandbox|test|production>` | no | `sandbox` |
| `--endpoint <url>` | no | selected environment |
| `--download-base-url <url>` | no | selected environment |
| `--timeout <seconds>` | no | `30` |
| `--verbose` | no | `false` |


See [Configuration](/cli/overview#configuration) for the corresponding environment variables.

## Session commands

### `session create`

Create a local receipt draft.

| Flag | Required | Default |
|  --- | --- | --- |
| `--session <id>` | yes | — |
| `--currency <code>` | no | `EUR` |
| `--document-number <value>` | no | generated |
| `--issue-date <ISO-8601>` | no | current time |
| `--env <name>` | no | `sandbox` |
| `--endpoint <url>` | no | selected environment |
| one of `--card-par`, `--pairing-code`, `--payment-account-identifier`, `--email`, `--payment-type` | no | — |


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

### `session match`

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

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

### `session status`

Inspect local session state:

```bash
cheqi session status --session order-42
```

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

### `session reset`

Delete the named local session draft:

```bash
cheqi session reset --session order-42
```

## Receipt commands

### `receipt set`

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

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

### `receipt add-product`

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

| Flag | Required | Default |
|  --- | --- | --- |
| `--session <id>` | yes | — |
| product name or `--name <value>` | yes | — |
| `--price-incl <number>` or `--unit-price <number>` | one price | — |
| `--quantity <number>` | no | `1` |
| `--vat <number>` | no | `0` |
| `--tax-type <value>` | no | `VAT` |
| `--unit-code <UN/ECE code>` | no | `C62` |
| `--brand <value>` | no | — |
| `--sku <value>` | no | — |


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

### `receipt preview`

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

```bash
cheqi receipt preview --session order-42
```

### `receipt validate`

Validate the definitive receipt locally without a network call:

```bash
cheqi receipt validate --session order-42
```

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

### `receipt finalize`

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

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

## Direct commands

### `receipts submit`

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

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

### `receipts submit-download`

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

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

## Issuance response

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


## Meta commands

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


## Errors

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.