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

> Auth, output formats, environment variables, and global options.

## Auth

```bash theme={null}
okra auth login -k okra_YOUR_KEY
okra auth set-key okra_YOUR_KEY   # non-interactive (CI/scripting)
okra auth logout
okra auth whoami
okra auth status
okra auth token                   # print key for piping
```

## Elements

```bash theme={null}
okra elements list <job-id>
okra elements get <element-id>
okra elements export <job-id> -t tables -f csv
okra elements export <job-id> -t tables -f json
okra elements export <job-id> -t tables -f md
okra elements export <job-id> -t figures -f png
okra elements count <job-id>
okra elements toc <job-id>
okra elements review status <job-id>
```

## Output formats

Most read/list commands support `-o` output formatting:

| Format  | Description                                            |
| ------- | ------------------------------------------------------ |
| `table` | Pretty-printed table (default)                         |
| `json`  | JSON output for scripting                              |
| `csv`   | CSV output (supported by `jobs list`, `elements list`) |

```bash theme={null}
okra jobs list -o json
```

File-export commands use different flags:

| Command                | File format flag                                   | Output path flag   | JSON result flag       |
| ---------------------- | -------------------------------------------------- | ------------------ | ---------------------- |
| `okra jobs export`     | `-f, --format` (`markdown`, `xlsx`, `docx`)        | `-o, --out`        | `--output-format json` |
| `okra elements export` | `-f, --format` (`csv`, `json`, `md`, `png`, `jpg`) | `-d, --output-dir` | `-o, --output`         |

## Global options

| Flag              | Description                                                                                 |
| ----------------- | ------------------------------------------------------------------------------------------- |
| `--json [fields]` | JSON output. Optionally pass comma-separated field names to filter (like `gh --json`).      |
| `--jq <expr>`     | Pipe JSON output through a [jq](https://jqlang.github.io/jq/) expression. Implies `--json`. |
| `-q, --quiet`     | Suppress spinners and info messages. Ideal for piping.                                      |
| `-V, --verbose`   | Enable verbose diagnostics (retry logs, debug info).                                        |
| `--no-color`      | Disable colored output.                                                                     |
| `-v, --version`   | Print version.                                                                              |

### `--json` field filtering

Select only the fields you need — output stays pipe-clean (no pagination footer, no spinners on stdout).

```bash theme={null}
# Single field
okra jobs list --json filename

# Multiple fields
okra jobs list --json job_id,status,filename

# Combine with --jq
okra jobs list --json job_id,status --jq '.[] | select(.status == "completed") | .job_id'

# Equals syntax also works
okra jobs list --json=job_id,filename
```

<Info>
  `--json` without field names returns all fields. Pagination footers and human-readable chrome are suppressed in JSON mode so output is always valid JSON.
</Info>

## Environment variables

| Variable                       | Description                                   |
| ------------------------------ | --------------------------------------------- |
| `OKRA_API_KEY`                 | API key (required)                            |
| `OKRA_BASE_URL`                | Base URL (default: `https://okrapdf.com`)     |
| `OKRA_OUTPUT_FORMAT`           | Default output format: `table`, `json`, `csv` |
| `OKRA_VLM`                     | Default VLM model                             |
| `OKRA_QUIET`                   | Set to `1` for quiet mode                     |
| `OKRA_VERBOSE`                 | Set to `1` for verbose diagnostics            |
| `DOCUMENT_AGENT_SHARED_SECRET` | Shared secret for `--agent canvas`            |