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

# Chat

> Ask questions about documents — or anything — from the command line.

## Chat

`okra chat` is the unified entry point for all chat. It routes automatically based on what you pass:

```bash theme={null}
# General question (no document)
okra chat "what is a 10-K filing?"

# Single document
okra chat "how many pages?" --doc ocr-abc123

# Multi-document comparison
okra chat "compare revenue" --doc ocr-abc123,ocr-def456

# Collection
okra chat "summarize key metrics" -c "TSMC 2024 Filings"
```

| Flag                      | Description                                           |
| ------------------------- | ----------------------------------------------------- |
| `--doc <ids>`             | Comma-separated job IDs (`ocr-*`)                     |
| `-c, --collection <name>` | Collection name or ID                                 |
| `-m, --message <text>`    | Message (alternative to positional)                   |
| `--schema <json>`         | JSON Schema for structured output                     |
| `--model <model>`         | Model override                                        |
| `--share`                 | Generate a public share link                          |
| `--agent <type>`          | Agent type: `canvas` (LLM-driven canvas manipulation) |
| `--tools <type>`          | Tool mode (coming soon)                               |
| `-q, --quiet`             | Suppress spinners (just the answer)                   |

## Routing

| What you pass                  | Mode         | Backend                                  |
| ------------------------------ | ------------ | ---------------------------------------- |
| No `--doc`, no `-c`            | General chat | Fireworks (no document context)          |
| `--doc ocr-XXX` (single)       | Single-doc   | DocumentAgent DO `/completion`           |
| `--doc ocr-XXX,ocr-YYY`        | Multi-doc    | Lead agent + DO fan-out                  |
| `-c my-collection`             | Multi-doc    | Same as above, resolves collection first |
| `--doc ocr-XXX --agent canvas` | Canvas agent | CanvasAgent DO `/canvas/completion`      |

## General chat

Ask anything without a document — helpful for finance questions, OCR concepts, or quick lookups.

```bash theme={null}
okra chat "what is EBITDA?"
okra chat "explain the difference between 10-K and 10-Q filings"
```

## Single-document chat

Query a specific extracted document. The agent has tools to search text, query tables, and retrieve pages.

```bash theme={null}
okra chat "what was total revenue?" --doc ocr-abc123
okra chat "list all tables on page 5" --doc ocr-abc123
```

## Multi-document chat

Compare across documents. The lead agent fans out queries to each document and synthesizes results.

```bash theme={null}
okra chat "compare the risk factors" --doc ocr-abc123,ocr-def456

# Or use a collection
okra chat "what are the common themes?" -c "Q4 Reports"
```

## Canvas agent (`--agent canvas`)

Use `--agent canvas` for LLM-driven canvas manipulation — the agent can read and modify the document canvas using tool calls.

```bash theme={null}
okra chat "highlight all revenue figures" --doc ocr-abc123 --agent canvas
okra chat "redact PII on page 3" --doc ocr-abc123 --agent canvas
```

Requires `DOCUMENT_AGENT_SHARED_SECRET` to be set. Streams tool calls and text deltas to the terminal, with cost and tool-call count reported at the end.

<Info>
  `--agent canvas` only supports single-document mode. The first `--doc` ID is used if multiple are provided.
</Info>

## Structured output (`--schema`)

Pass a JSON Schema to get structured JSON responses. Works with single-doc mode.

```bash theme={null}
# Inline schema
okra chat "get company info" --doc ocr-abc123 \
  --schema '{"type":"object","properties":{"companyName":{"type":"string"}}}'

# Quiet mode — pure JSON, no spinners
okra chat "get company info" --doc ocr-abc123 \
  --schema '{"type":"object","properties":{"companyName":{"type":"string"}}}' \
  --quiet
```

```json theme={null}
{
  "companyName": "Stock Code 00700 - Hong Kong Listed Equity Issuer"
}
```

<Tip>
  Combine `--schema` with `--quiet` for pipeline-friendly output you can pipe straight into `jq`.
</Tip>

## Parallel sessions

Run multiple single-doc queries in parallel — each runs independently.

```bash theme={null}
QUESTION="What was total revenue for FY2023?"

for jobId in ocr-abc1 ocr-abc2 ocr-abc3; do
  okra chat "$QUESTION" --doc "$jobId" > "results/${jobId}.json" &
done
wait
```

## Legacy syntax

The old `send` subcommand still works:

```bash theme={null}
okra chat send ocr-abc123 -m "What tables are in this document?"
```

<Info>
  Prefer the new syntax: `okra chat "question" --doc ocr-abc123`
</Info>