# Cheqi CLI

The Cheqi CLI (`@cheqi/cli`) is an agent-friendly command-line interface for the Cheqi receipt flow. Version `0.4.0` uses JavaScript SDK `2.5.0` to resolve delivery routes, encrypt the definitive merchant-supplied receipt locally, and issue it without a server-side receipt-template step.

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.

Source code and releases: [cheqi-io/cli](https://github.com/cheqi-io/cli)

## Installation

The CLI requires Node.js 20 or newer.

```bash
npm install --global @cheqi/cli@0.4.0
cheqi version
```

You can also run it without a global installation:

```bash
npx @cheqi/cli@0.4.0 version
```

## Receipt workflows

The CLI supports three workflows:

- **Incremental sessions** use `session ...` and `receipt ...` commands to build a receipt across multiple calls. Drafts are stored under `.cheqi/sessions/<session-id>.json` in the current working directory.
- **Matched direct submission** uses `receipts submit` to issue a complete definitive receipt JSON document in one call.
- **Direct download issuance** uses `receipts submit-download` to create a client-encrypted download without customer matching.


The incremental flow is a good default when a script or agent gathers receipt data over time:

```bash
cheqi session create \
  --session order-42 \
  --currency EUR \
  --document-number INV-001 \
  --card-par YOUR_CARD_PAR

cheqi receipt add-product \
  --session order-42 \
  --name "Coffee beans" \
  --price-incl 12.10 \
  --vat 21

cheqi receipt validate --session order-42
CHEQI_API_KEY=sk_... cheqi receipt finalize --session order-42
```

`receipt finalize` resolves the route immediately before issuing the receipt. Use `session match` earlier when you want to inspect the route and recipient count before finalization; finalization does not rely on that potentially stale response.

See [Agent Workflows](/cli/agent-workflows) for complete examples.

## Response envelope

A successful command returns:

```json
{
  "ok": true,
  "data": {},
  "meta": {
    "durationMs": 12,
    "version": "0.4.0"
  }
}
```

A failed command returns:

```json
{
  "ok": false,
  "error": {
    "code": "SESSION_NOT_FOUND",
    "message": "No Cheqi session found for order-42.",
    "retryable": false,
    "details": {
      "sessionId": "order-42"
    }
  },
  "meta": {
    "durationMs": 4,
    "version": "0.4.0"
  }
}
```

The `ok` field is authoritative. Exit code `0` means success, `4` means a
retryable failure, `3` means authentication failed, and `2` means a command or
flag was invalid. Other failures exit `1`. Standard output contains only the
JSON envelope. With `--verbose`, diagnostics go to standard error and do not
corrupt parsed output.

## Recover an uncertain submission

If `receipt finalize` returns `RECEIPT_PENDING`, run it again with the same
session ID. The CLI resumes the original match using the saved receipt. If
`receipts submit` returns `RECEIPT_PENDING`, keep the original JSON and
`matchId`, then run:

```bash
CHEQI_API_KEY=sk_... cheqi receipts resume \
  --match-id MATCH_ID \
  --receipt ./receipt.json
```

Do not create another receipt while the original submission is uncertain. For
a session whose digital match has expired, add `--fallback download` to
`receipt finalize --session <id>` to use a prepared download when one is
available. See the [command reference](/cli/commands#receipt-finalize) for the
route-specific details.

## Configuration

Network commands accept flags or equivalent environment variables. Flags take precedence.

| Setting | Flag | Environment variable | Default |
|  --- | --- | --- | --- |
| Environment | `--env <sandbox|test|production>` | `CHEQI_ENV` | `sandbox` |
| Custom API endpoint | `--endpoint <url>` | `CHEQI_API_ENDPOINT` | selected environment |
| Download receipt origin | `--download-base-url <url>` | `CHEQI_DOWNLOAD_BASE_URL` | selected environment |
| API key | `--api-key <key>` | `CHEQI_API_KEY` | — |
| OAuth access token | `--access-token <token>` | `CHEQI_ACCESS_TOKEN` | — |
| Request timeout in seconds | `--timeout <n>` | `CHEQI_TIMEOUT_SECONDS` | `30` |


Use exactly one credential for each network command: an API key or an OAuth access token. Supplying neither returns `AUTH_REQUIRED`; supplying both returns `AUTH_CONFLICT`.

Local commands such as `session create`, `receipt add-product`, `receipt preview`, and `receipt validate` do not need credentials.

## Agent-oriented behavior

- `cheqi schema` describes all commands, flags, enum values, and response schemas at runtime.
- Stable error codes let callers branch without parsing human messages.
- The `retryable` error field distinguishes transient failures from invalid input.
- Operational responses include a structured `nextStep` when another command is expected.
- Explicit `--session` values isolate concurrent receipt drafts.


## Next steps

- [Command Reference](/cli/commands)
- [Agent Workflows](/cli/agent-workflows)
- [JavaScript SDK](/sdk/javascript)