# Cheqi CLI

The Cheqi CLI (`@cheqi/cli`) is an agent-friendly command-line interface for the Cheqi receipt flow. Version `0.3.2` uses JavaScript SDK `2.2.1` 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.3.2
cheqi version
```

You can also run it without a global installation:

```bash
npx @cheqi/cli@0.3.2 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.3.2"
  }
}
```

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.3.2"
  }
}
```

The `ok` field is authoritative and matches the process exit code: `0` for success and `1` for failure. Standard output contains only the JSON envelope. With `--verbose`, diagnostics go to standard error and do not corrupt parsed output.

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