CLI

drex-cli installs the drex command, which calls https://console.nace.ai from your shell. It is built on the Python SDK and covers Perception's five tools, uploads, jobs and saved schemas, plus drex decide for Drex's decision endpoint — see the CLI's Drex page for that.

pipx install drex-cli   # or: uv tool install drex-cli
drex login

drex login asks for a key and checks it against Drex. It then saves the key to ~/.drex/config.toml, readable only by you. DREX_API_KEY and DREX_BASE_URL take precedence over the file.

SourcesCopy Anchor Link

Every tool below takes a SOURCE argument, which is any of these:

• An https:// URL.
• A local file. It is uploaded to your workspace first.
• ws:<workspace_id>/<file_id>, the value drex upload prints.
• job:<id>, a finished parse job. Use it to reuse the parse instead of parsing again.

drex upload invoice.pdf --path invoices/invoice.pdf
# ws:0f8b7c2e-.../3a91c5...

Flags every tool sharesCopy Anchor Link

Parse, Split, Classify, Extract and Ground all take these, on top of each tool's own flags below:

Waiting and outputCopy Anchor Link

Status messages go to stderr, so stdout holds only the result; drex parse doc.pdf > doc.md captures only the document. drex exits with 0 on success, 1 when an API call or job fails, and 2 on a usage or configuration error. An error message shows the error type, the code and the request_id. See Errors.

ParseCopy Anchor Link

drex parse https://example.com/report.pdf --pages 1-3 --format markdown,blocks > report.md

See Parse.

SplitCopy Anchor Link

drex split https://example.com/packet.pdf \
  --class invoice:Invoice:"A supplier invoice" \
  --class receipt:Receipt:"A payment receipt"

See Split.

ClassifyCopy Anchor Link

drex classify https://example.com/invoice.pdf \
  --class invoice:Invoice:"A supplier invoice" \
  --class contract:Contract:"A signed agreement between two parties" \
  --granularity page

Takes the same --class / --classes flags as Split, plus:

See Classify.

ExtractCopy Anchor Link

drex extract https://example.com/invoice.pdf --schema invoice.schema.json

Where invoice.schema.json is:

{
  "type": "object",
  "properties": {
    "invoice_number": { "type": "string" },
    "total": { "type": "number" }
  },
  "required": ["invoice_number", "total"]
}

Point it at a finished parse instead to avoid parsing and paying for the document twice:

drex parse https://example.com/invoice.pdf -o id
# 6f1a2b3c-...
drex extract job:6f1a2b3c-... --schema invoice.schema.json

See Extract. --schema only takes an inline JSON Schema; using a saved schema's id isn't exposed by this command yet (see Save a reusable extraction schema).

GroundCopy Anchor Link

drex ground https://example.com/report.pdf \
  --target "total=1,200.50" \
  --target "signer=Jane Smith"

See Ground.

List, read and delete jobsCopy Anchor Link

drex jobs --operation parse
drex job <id> --wait
drex file <id> parse-images/<ref> --save page-1.png
drex cancel <id>

See Jobs and results.

Save a reusable extraction schemaCopy Anchor Link

Save a JSON Schema once, then reuse it across extracts without sending it inline. Saved schemas can't be edited; add a version instead.

drex schema-create invoice --schema invoice.schema.json --description "Invoice header fields"
drex schemas
drex schema <schema_id>
drex schema-version-add <schema_id> --schema invoice-v2.schema.json
drex schema-versions <schema_id>
drex schema-version <schema_id> 2