Perception
Flags every tool shares
Parse, Split, Classify, Extract and Ground each create a job. They take these flags, except that Ground takes neither -p, --pages nor --mode. They take them on top of each tool's own flags below and --json and --timeout from Flags every API command takes:
| Flag | What it does |
|---|---|
--file-name NAME | For an https:// source: the file's name, whose extension picks the parser. See URLs. |
--upload-path PATH | For a local file: its path in your workspace. See Local files. |
--on-conflict {reject,new_version} | For a local file: what to do when a different file has that path. See Local files. |
-p, --pages SPEC | 1-based pages to read, inclusive: 3 or 1-5,8. Default: every page. At most 200 ranges and 500 pages. Not on ground, not with a job: source on parse or extract, and not for a workbook on split or classify. |
--mode {low,medium,high} | How much effort parsing takes (parse_mode, default low). Not on ground. medium and high parse again, so not with a job: source. |
--option KEY=VALUE | Any other request field. Repeatable. See Request fields. |
--options JSON | Request fields as a JSON object: inline, @FILE, a path, or - for stdin. |
--wait-seconds N | Ask Drex to hold the create open up to N seconds, 0 to 60. A job that finishes by then comes back with its result in the same call. |
--idempotency-key KEY | Up to 200 characters. The same key and body return the same job and bill once; the same key with a different body is refused with 409 idempotency_conflict. |
Running a command again. Without --idempotency-key, nace sends a new key on each run:
- Retries inside one run return the same job.
- Running the command again creates, and bills, a new job.
- After a
503 job_pending,naceprints the key it sent. Rerun with--idempotency-keyset to it to resume that job. See Retry safely. - A slow retryable failure can use the remaining retries, including after the create held the request open. See Retries and timeouts.
The charge id. nace doesn't print the create's x-drex-document-job header, Drex's id for the charge. The job's idempotency_key field holds the same id, and -o json prints it: quote it when you contact support.
Request fields
The request is built in three layers, each winning over the one before:
--options: the base request.- Each
--option, applied on top. - The flags above, and each tool's own flags.
A dotted key sets a field inside another, such as output.table_format. A value is read as JSON when it can be, so true is a yes/no and [...] a list; anything else is text. Quote JSON for the shell. Some examples, on nace parse:
| You write | What it does |
|---|---|
--option output.table_format=markdown | Writes tables in the Markdown as Markdown, instead of HTML. |
--option 'output.formats=["markdown","text"]' | Returns the document as Markdown and as plain text. |
--option output.include_images=true | Adds a crop link to each figure, for PDF and image sources. Needs blocks in the formats, as by default. |
--option name="March invoices" | Gives the job a display name, which nace jobs lists. |
--option 'name="2026"' | Names the job 2026. Quoted as a JSON string, so it's sent as text, not the number 2026. |
These keys work like the flags beside them, and the flag wins when you give both:
| Key | What it does |
|---|---|
wait_seconds | Holds the create open until the job finishes, up to that many seconds, as --wait-seconds does. |
idempotency_key | Makes a rerun return the same job instead of starting, and billing, a new one, as --idempotency-key does. |
classes | Sets Split's and Classify's classes, as --class and --classes do. |
schema, schema_id, schema_version | Sets Extract's schema, as -s and --schema-id do. |
instructions | Gives Extract its instructions, as --instructions does. |
targets | Sets the quotes Ground looks for, as --target and --targets do. |
source | Refused with exit 2: pass the document as SOURCE, with --file-name for a URL. |
Every other key goes into the request body as given, such as --option name="March invoices" for the job's display name, or project_id, a UUID you mint to group jobs. Each tool's options are on its page: Parse, Split, Classify, Extract and Ground.
Waiting and output
A tool creates the job, waits for it and prints its output. Stderr shows job <id> <status> when it's created and when it finishes. nace reads the job every second at first, then less often, up to every 10 seconds; reading a job is free.
| Flag | What it does |
|---|---|
--async | Print only the job id and return at once. -o, --save and --json don't apply. |
--wait-timeout SECONDS | How long to wait for the job (default 600). Past it, the command prints the job id on stdout (the whole job with -o json) and exits 1, and the job keeps running: read it later with nace job <id> --wait. |
--watch | Print progress events to stderr first, as status · message · key=value ..., leaving out any part an event doesn't have. |
-o, --output {auto,md,json,result,payload,id} | What to print, from the table below. Default auto. |
--save PATH | Write the output to PATH instead of stdout, and print saved <path> on stderr. - means stdout. |
-o | Prints |
|---|---|
auto | A parse's Markdown, or its text when you asked only for text (except a large document's full content; see Large documents and workbooks). Any other result as JSON. |
md | A parse's Markdown, or its text. A job with neither exits 1. |
json | The whole job: job_id, kind, status, result, error, credits and the rest, leaving out top-level fields that are null. --json is the same and wins over -o. |
result | Only the job's result, as JSON. |
payload | The same as result. |
id | Only the job id. --save doesn't apply. |
No result. A job that hasn't finished, failed, or whose result has expired has no result, so auto and result print the whole job instead, with result_state saying why an expired one has none.
A job that fails or is cancelled while you wait:
- Stderr shows
error: [<code>] job <id> <status>: <message>, such aserror: [job_cancelled] job <id> cancelled: Deleted by the caller.for a jobnace cancelstopped. [<code>]appears only when the job has an error code, and<message>isno error detailwhen it has no message.- Stdout stays empty unless you asked for
-o json, and the command exits1.
Saving fails. A --save file that can't be written prints the output to stdout and exits 1.
--watch reads the job's event stream until it ends: when the job does, or after about five minutes.
- Only then does the
--wait-timeoutclock start. - If the stream drops, stderr shows
(event stream ended: ...)and the wait goes on.