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. |
Without --idempotency-key, nace sends a new key on each run. Retries inside one run return the same job, but running the command again creates, and bills, a new one. When a create fails with 503 job_pending, nace prints the key it sent: rerun with --idempotency-key set to it to resume that job. See Retry safely. A create that fails after holding the request open for 30 seconds or more isn't retried at all; see Retries and timeouts.
nace doesn't print the create's x-drex-document-job header, Drex's id for the charge. The job's idempotency_key field, which -o json prints, holds the same id: quote it when you contact support.
Request fields
--options gives the base request, each --option is applied on top of it, and the flags above and each tool's own flags win over both.
- A dotted key nests:
--option output.table_format=markdownsends{"output": {"table_format": "markdown"}}. - A value is parsed as JSON when it can be. Lists, numbers and booleans therefore need JSON, quoted for the shell:
--option 'output.formats=["markdown","text"]',--option output.include_images=true. Any other value is sent as a string. To send a string that would parse as JSON, such as42ortrue, give it as a JSON string:--option 'KEY="42"'.
These keys are taken out of the body and used like their flags:
| Key | Where it goes |
|---|---|
wait_seconds | The wait_seconds query parameter. --wait-seconds wins. |
idempotency_key | The Idempotency-Key header. --idempotency-key wins. |
classes | Split's and Classify's classes, when there's no --class or --classes. |
schema, schema_id, schema_version | Extract's schema, when there's no -s or --schema-id. |
instructions | Extract's instructions. --instructions wins. |
targets | Ground's targets, when there's no --target or --targets. |
source | Refused with exit 2: the source is always 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 .... |
-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, under the ndi CLI's name for it. |
id | Only the job id. --save doesn't apply. |
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. When a job you wait for fails or is cancelled, stderr shows error: [<code>] job <id> <status>: <message>, such as error: [job_cancelled] job <id> cancelled: Deleted by the caller. for a job nace cancel stopped. [<code>] appears only when the job has an error code, and <message> is no error detail when it has no message. Stdout stays empty unless you asked for -o json, and the command exits 1. 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-timeout clock start. If the stream drops, stderr shows (event stream ended: ...) and the wait goes on.