> ## Documentation Index
> Fetch the complete documentation index at: https://docs.okrapdf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reference

> Current auth, environment variables, and global CLI options.

## Envelope format

When stdout is not a TTY (and always with `--json`), every command emits a structured JSON envelope that unifies success and failure:

```json theme={null}
{
  "ok": true,
  "command": "context resolve",
  "result": {},
  "cost": { "usd": null },
  "citations": [],
  "next_actions": []
}
```

On failure, the same top-level shape is used with `"ok": false` and additional fields:

```json theme={null}
{
  "ok": false,
  "command": "collections publish",
  "error": "confirmation_required",
  "message": "Public publish asserts that you own or are licensed to publish this content.",
  "cost": { "usd": null },
  "citations": [],
  "next_actions": [
    {
      "cmd": "okra collections publish earnings --confirm-rights",
      "why": "Confirm the public publish rights gate explicitly."
    }
  ]
}
```

### Field reference

| Field          | Description                                                                    |
| -------------- | ------------------------------------------------------------------------------ |
| `ok`           | `true` on success, `false` on failure.                                         |
| `command`      | The command name as executed (e.g. `context resolve`).                         |
| `result`       | Command-specific payload on success.                                           |
| `error`        | Stable, **machine-readable** error code on failure (never a freeform message). |
| `message`      | Human-readable explanation of the failure.                                     |
| `cost`         | Estimated cost, when available (`usd` field).                                  |
| `citations`    | Any source citations returned by the command.                                  |
| `next_actions` | Suggested follow-up commands that an agent can run directly.                   |

### Error codes and exit codes

* `error` is always a stable machine code (e.g. `confirmation_required`, `human_review_required`, `engine_not_available`). Freeform messages go in `message`, not `error`.
* Commands that fail with `"ok": false` return a **non-zero** exit code.
* When a command succeeds, the exit code is zero.

### Agent stop-gates

Agents must **stop** when `error` is either `confirmation_required` or `human_review_required`, show the `message` to a human, and only rerun a `next_actions[].cmd` after explicit approval. Do not add confirmation flags (e.g. `--confirm-rights`, `--yes`, `--attest`) without human input.

### Enabling JSON output

```bash theme={null}
# Automatic when stdout is not a TTY
okra context resolve "https://example.com/report.pdf" | jq .

# Force JSON in an interactive terminal
okra upload ./report.pdf --json
okra upload ./report.pdf -o json
```

## Global options

```text theme={null}
okra --help
okra --version
okra --json
okra --quiet
okra --output result.json
```

| Flag              | Description                                  |
| ----------------- | -------------------------------------------- |
| `--json`          | Emit machine-readable JSON where supported.  |
| `--quiet`         | Suppress progress and human-readable output. |
| `--output <file>` | Write output to a file instead of stdout.    |
| `--version`       | Print the installed package version.         |

## Auth

```bash theme={null}
okra auth login
okra auth set-key okra_sk_YOUR_KEY
okra auth status
okra auth whoami
okra auth token
okra auth logout
```

## Primary commands

```bash theme={null}
okra upload ./report.pdf
okra extract ./invoice.pdf --schema ./schema.json
okra chat "Summarize this document" --doc doc-abc123
okra read doc-abc123 --pages 1-5
okra list
okra delete doc-abc123
okra collection query earnings "What changed quarter over quarter?"
```

## Noun-first agent surface

The agent contract uses stable resource nouns that match API resources and the `/v1/resources` catalog. Legacy ergonomic verbs (e.g. `upload`, `read`, `chat`, `extract`, `parse`, `audit`, `redact`, `render`) remain compatible, but the preferred agent surface is:

* `resources`
* `documents`
* `files`
* `jobs`
* `agents`
* `workflows`
* `collections`

Run `okra resources list` to discover every API noun and verb, and `okra <noun> --help` for a resource's subcommands.

## Grounded context commands

Before (or instead of) a full parse, the `context` commands navigate a source and retrieve bounded, cited context:

```bash theme={null}
okra context structure doc-abc123          # navigable sections, page ranges, artifacts
okra context tables doc-abc123             # detected tables with columns + page hints
okra context get "termination clause" --source-id doc-abc123
okra context ask "What is the guaranteed fee?" --source-id doc-abc123
```

## Environment variables

| Variable        | Description                                        |
| --------------- | -------------------------------------------------- |
| `OKRA_API_KEY`  | API key used by authenticated commands.            |
| `OKRA_BASE_URL` | API origin. Defaults to `https://api.okrapdf.com`. |
| `OKRA_QUIET`    | Set to `1` for quiet mode.                         |