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) andextractit 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_…andimport 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-shotPOST /v1/extract?wait=N(see API ingest and one-shot runs). It creates no workflow; the run is an ordinaryextractrun, visible in the Studio and billed like any other.--timeout(default 120 s) is how long the CLI waits.--no-cache,--deterministic,--metadata,--notesand several files (a packet) are local-only and are rejected with exit code 2.--rulestakes 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
FILESaccepts files, directories and globs (quoted globs are expanded byextractit); 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
--concurrencyruns 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_reviewis reported asneeds_reviewand 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), noui(canvas positions;--with-uikeeps them), two-space indent and a final newline.pull,pushandpullagain leave the file byte-identical. Runpullonce after creating a file by hand: the server writes default values and thex-dx.field_idof 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 reportscreate,update(a new revision of the draft) orno_changes. It callsPOST :validateand lists every topology violation (rule,message,node_ids); with any it exits 2 and writes no plan. Otherwise it writesplan.json:Key Content actioncreate,updateorno_changesbase_version_id,base_revisionthe draft (or version) the plan was computed from base_graph_hashsha256 of its canonical form patchRFC 6902 patch from the base to the file target,target_hashthe document to write hashsha256 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_STALEand modifies nothing; the draft is saved withIf-Match: "v<base_revision>", so a concurrent writer also yieldsPLAN_STALE.--publish ALIASpublishes the version (semver of T25;--bumpmay raise it) and moves the alias; withno_changesit 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-codeexits 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.