Reference

Envelope format

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

{
  "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:

{
  "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

# 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

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

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

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:

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.

Getting Started

Documents

Jobs

Collections

Reference

Envelope format

Field reference

Error codes and exit codes

Agent stop-gates

Enabling JSON output

Global options

Auth

Primary commands

Noun-first agent surface

Grounded context commands

Environment variables

​Envelope format

​Field reference

​Error codes and exit codes

​Agent stop-gates

​Enabling JSON output

​Global options

​Auth

​Primary commands

​Noun-first agent surface

​Grounded context commands

​Environment variables

Envelope format

Field reference

Error codes and exit codes

Agent stop-gates

Enabling JSON output

Global options

Auth

Primary commands

Noun-first agent surface

Grounded context commands

Environment variables