Skip to content

The extractit command line

extractit (short name: xt) is one command with two halves:

  • local commands that run in process, without a server or a database: extractit parse, extractit FILE (the extraction itself) and extractit eval (T08 and T10);
  • remote commands that talk to an ExtractIt server through the Python SDK (T45): login, logout, whoami, workflows, run, runs, datasets, eval run, eval compare evr_… evr_… and import anyformat.

The full tree of remote commands is committed in cli/commands.json; a test compares it with the Typer application, so a command cannot appear or disappear unnoticed. Every command has --help with examples.

Credentials and profiles

extractit login --base-url https://dx.example.com          # prompts for the key (hidden)
echo "$DX_KEY" | extractit login --base-url https://dx.example.com --with-key
extractit whoami                                           # name, scopes, project, base URL
extractit logout

extractit login validates the key with GET /v1/me before saving anything. Profiles live in config.toml (the platform's config directory; DX_CONFIG points elsewhere) without the key. The key goes to the OS keyring when the optional keyring package is installed (pip install 'extractit[keyring]') and has a working backend; otherwise to credentials.toml next to config.toml, created with mode 0600. The key is never printed, logged or written to an output file.

Each setting is resolved separately with this precedence:

Setting 1. flag 2. environment 3. profile
server --base-url DX_BASE_URL base_url of the profile
API key --api-key DX_API_KEY keyring / credentials.toml

The profile is --profile, else DX_PROFILE, else default_profile of config.toml, else default. Prefer the environment to --api-key (a flag is visible in the process list).

Output

Data goes to stdout, everything else (progress, warnings, summaries) to stderr, so extractit … --json | jq stays clean. --json (global or per command) prints machine-readable JSON; otherwise tables are drawn with rich. NO_COLOR turns colour off. Shell completion: extractit --install-completion.

Exit codes

Code Meaning
0 success
1 failure: a run failed, an evaluation is below --fail-under, or --exit-code found differences
2 usage or validation error, including topology violations and a stale plan (PLAN_STALE)
3 authentication or permissions (HTTP 401/403, or no credentials)
4 network error or timeout (server unreachable, 5xx after the SDK's retries)
5 import with approximated or unsupported items under --strict
130 interrupted (Ctrl+C); runs already submitted keep going on the server

Change from the baseline

The baseline table reused 3 for two different cases; 5 is new. Scripts that test exit codes should follow this table.

First result in one command: extractit FILE

extractit invoice.pdf --field number:string --field date:date --field total:number
extractit invoice.pdf --schema invoice.schema.json --format table
extractit invoice.pdf -f total:number --remote          # on the server, no workflow

Short name

xt is the same command with fewer keystrokes: xt invoice.pdf --field total:number.

File or subcommand? The first argument decides. A subcommand of extractit (or of an installed extension) always wins. Otherwise, an existing path, -, an http(s):// URL, or a name that ends in a file extension (invoice.pdf, even if it does not exist yet) is a document and runs the extraction with all your arguments and options; any other word is a mistyped subcommand and fails with No such command and a suggestion, never as a file. extractit with no arguments shows the help. A file whose name is also a subcommand is passed with a path: extractit ./models --field …. Documents are read from files: - and URLs are routed to the extraction, which rejects them with exit code 2.

No workflow and no schema file are needed. --field name:type[:description] (short -f, repeatable) builds the schema on the command line; --schema stays for a file or a module:Class. Use one of the two, not both.

Type Meaning
string (text, str) text; a bare name is a string
number (float, decimal, money, amount) any number
integer (int) whole number
boolean (bool) yes/no
date, datetime ISO 8601 date or date-time
enum(EUR\|USD) one of the listed values
<type>[] a list, for example tags:string[]

The output is the JSON of the extraction (data, and per field evidence with the page and box that cite it, confidence, status), exactly what --schema prints. The field_id of each --field derives from its name, so the same fields always give the same schema (and the same parse and model cache keys).

  • In process (default): nothing leaves the machine; it uses the parse cache and the model backend of --model / DX_MODEL.
  • --remote: uploads the document to the server of your profile (extractit login, DX_BASE_URL, --base-url) with the one-shot POST /v1/extract?wait=N (see API ingest and one-shot runs). It creates no workflow; the run is an ordinary extract run, visible in the Studio and billed like any other. --timeout (default 120 s) is how long the CLI waits. --no-cache, --deterministic, --metadata, --notes and several files (a packet) are local-only and are rejected with exit code 2. --rules takes a JSON list (or {"rules": [...]}).

--remote is explicit on purpose: having a profile does not make extractit FILE upload documents. With --fail-on-review, exit code 3 means review pending; with --remote the same code 3 is also used for authentication errors (the message tells them apart).

To check an API key before running anything, see Key check.

Local mode

--local (or DX_MODE=local) forces local mode. Without a profile and without DX_BASE_URL the local commands are local anyway. extractit --local parse|extract|eval prints exactly what extractit parse|extract|eval prints (a test compares them with sockets disabled). Remote commands refuse local mode with exit code 2 and say so.

Workflows and runs are not available locally: the interpreter (T26) needs Postgres and DBOS. This is an accepted limitation. An import-linter contract forbids extractit.cli.local to import extractit.api, extractit.store or extractit.runtime.

Batches: extractit run

extractit run facturas@prod *.pdf --concurrency 8 --wait --out results.jsonl
extractit run facturas@dev inbox/ --wait          # directories are walked, hidden files skipped
  • FILES accepts files, directories and globs (quoted globs are expanded by extractit); the same path given twice is sent once.
  • Each file is sent with Idempotency-Key = sha256(sha256(file), workflow@alias): repeating the command returns the same runs (Idempotent-Replayed) and creates none.
  • At most --concurrency runs are in flight (submission and waiting hold one slot).
  • One JSONL line per file, written as each run finishes: file, run_id, status, data, cost_usd, error, replayed. Document content is only ever written as JSON data.
  • A run in waiting_review is reported as needs_review and is not a failure.
  • Exit 0 when every run finished (or was submitted, without --wait), 1 when any failed, 4 on timeout, 130 on Ctrl+C.

Runs

extractit runs list --status failed --limit 150     # follows the cursor until --limit
extractit runs watch run_01j…                        # node progress from SSE; exit code of the final status
extractit runs resume run_01j… --wait                # :resume; finished nodes show cache hit = true
extractit runs rerun run_01j… --version [email protected]   # new run with parent_run_id

Workflows as code

extractit workflows pull facturas -o facturas.json   # canonical JSON (draft, else latest)
$EDITOR facturas.json
extractit workflows plan facturas.json               # what would change + every violation
extractit workflows apply plan.json --publish prod --summary "stricter total" --bump minor
extractit workflows diff facturas@prod facturas.json --exit-code
  • Canonical JSON: keys sorted, nodes by id, edges by (source, target, branch), no ui (canvas positions; --with-ui keeps them), two-space indent and a final newline. pull, push and pull again leave the file byte-identical. Run pull once after creating a file by hand: the server writes default values and the x-dx.field_id of new fields.
  • plan resolves the workflow by the file's name (or --workflow), compares the file with the draft (else the latest published version) and reports create, update (a new revision of the draft) or no_changes. It calls POST :validate and lists every topology violation (rule, message, node_ids); with any it exits 2 and writes no plan. Otherwise it writes plan.json:

    Key Content
    action create, update or no_changes
    base_version_id, base_revision the draft (or version) the plan was computed from
    base_graph_hash sha256 of its canonical form
    patch RFC 6902 patch from the base to the file
    target, target_hash the document to write
    hash sha256 of the plan itself (a modified plan is refused)
  • apply writes with compare-and-swap: if the remote draft changed after the plan (another revision, another base, a new draft) it exits 2 with PLAN_STALE and modifies nothing; the draft is saved with If-Match: "v<base_revision>", so a concurrent writer also yields PLAN_STALE. --publish ALIAS publishes the version (semver of T25; --bump may raise it) and moves the alias; with no_changes it only moves the alias.

  • push is plan + apply in one step (refuses violations; says "no changes" and creates no revision when there are none).
  • diff A B accepts wfv_… ids, name@alias, [email protected], name (draft, else latest) and files, mixed. Two server versions show the server's :diff; otherwise the RFC 6902 patch of the canonical documents. --exit-code exits 1 when they differ.

Evaluation in CI

extractit eval run facturas@dev --dataset ds_01j… --split validation --fail-under 0.97
extractit eval compare evr_01ja… evr_01jb…

extractit eval run snapshots the dataset, creates a managed evaluation (T38) of the published version on the requested split, waits, prints the accuracy per field and exits 1 when the metric is below --fail-under (0 when it is equal or above). --metric defaults to f1_macro; when the evaluation reports no macro F1 (plain ground truth) the server's field f1 is used and the output says so. The sealed test split is refused with exit code 2 before any request. extractit eval compare with two evr_… ids prints the delta, the 95 % interval and the adjusted p exactly as the API returns them (with two report files it is T10's local comparison).

The gate works in any CI: give the job DX_BASE_URL and DX_API_KEY as secrets and run ci/dx-eval.sh. There is no GitHub Actions workflow in this repository.

DX_BASE_URL=… DX_API_KEY=… WORKFLOW=facturas@dev DATASET=ds_01j… FAIL_UNDER=0.97 \
  sh docs/ci/dx-eval.sh

Datasets

extractit datasets push ./golden --dataset ds_01j… --dry-run

Uploads a.pdf + a.json pairs (the JSON is the ground truth); documents without a .json are skipped with a warning.

Importing workflows exported from Anyformat

extractit import anyformat FILE… [--dry-run] [-o out.json] [--report report.json] [--strict] converts exported workflows into versioned drafts. See Migrating from Anyformat.

Terminal recordings

Transcripts of real sessions live in tests/cli/recordings/: a batch of 24 PDFs (batch-24-pdfs.txt and its JSONL), the workflow-as-code cycle against a real server (workflow-as-code.txt), the evaluation gate passing and failing (eval-gate.txt) and an import with its compatibility report (import-anyformat-dry-run.txt, import-anyformat-report.json).

Extending extractit

Packages mount their own sub-commands through the extractit.cli entry-point group without editing the CLI:

[project.entry-points."extractit.cli"]
mcp = "my_package.cli:app"   # a typer.Typer or a command function

Entry points are only read when extractit --help lists the commands, and only the command that runs is imported. A name the core already uses is an error that names the package.

MCP bridge (T47)

extractit mcp --url "$DX_BASE_URL/mcp" bridges a local MCP client (stdio) to the server's /mcp endpoint; the core registers it (extractit.cli.main), so it is not an entry point.