Ade

ade — agent skill

ade drives the ADE (Agentic Document Extraction) v2 document APIs (parse, extract) and persists everything it produces in a local store under ~/.ade. You are the judgment; the CLI is deterministic plumbing: it parses, persists, searches, renders, and totals — it never ranks or selects for you.

First move

ade help --json

One call returns the whole shipped surface: every command and flag, each verb's --json result shape, the exit states, and the store layout. Prefer it over N --help round trips. ade help workflow (also output, credentials, errors) is the conceptual page behind it. Check credentials with ade auth status --json; if logged out, set ADE_API_KEY, or pipe a key in (echo $KEY | ade auth login) — no terminal required either way. An API key acts in the organization it was created in; browser (OAuth) sessions carry their own selection — status reports it, ade auth org list --json shows the memberships, and ade auth org switch <org> --env <env> changes it. If a run must bill to a specific organization, confirm the selection before parsing: re-running the same invocation after a switch joins the recorded run instead of re-billing under the new organization.

Conventions

• Always pass --json. Every command emits one stable JSON object/array on stdout — errors and pending payloads included. Human text is for terminals, not for parsing. The whole result is on stdout: the extraction, the matches, the paths. Reading the store is a convenience, never a requirement — and ade help --json publishes each verb's shape, so you never have to discover it by running.
• --id-only when you only need the id. parse, extract, and find take it: the id(s), one per line, nothing else — JOB=$(ade parse -d report.pdf --id-only). Errors go to stderr, so a captured id is never a sentence.
• Job item ids are the currency. Every parse or extract run is a job item: one folder under ~/.ade/jobs/<job-item-id>/, keyed by the invocation (verb × environment × source × content × params; URL sources are keyed by the URL alone — no content component, so remote drift does not re-key). Commands accept an unambiguous id prefix. Changing the file, its path, or any param mints a sibling item — nothing is silently replaced.
• Commands are guarantees. parse means "ensure this exact run exists", not "fire a request". Re-running an already-done invocation is free — served from disk with an already parsed notice and "cached": true. Only --force re-bills.

The loop

1. Parse (free if already done):

   ade parse -d report.pdf --json

   The payload carries job_item_id — hold onto it. Everything else keys off it. The markdown and the elements projection stay on disk unless you ask for them: --include markdown, --include elements.

2. Discover element ids (local, instant, no API call):

   ade find JOB_ITEM_ID "total revenue" --json
   ade find JOB_ITEM_ID --type table_cell --page 3 --json

   (--job JOB_ITEM_ID is the equivalent flag spelling — repeat it to search several items in one call.)

   Matches are citation records: {job_item_id, element_id, type, page, box, text}. Filters compose (AND); results come in document order, never ranked — selection is your job.

3. Extract structured data against a JSON Schema:

   ade extract JOB_ITEM_ID --schema schema.json --json

   The result is its own job item. The payload's extraction key is the schema-shaped result itself — read it there, not off disk. Per-field evidence (evidence, persisted as evidence.json) joins extraction spans to element ids, pages, and boxes — non-empty fields the model synthesised rather than quoted are flagged ungroundable; empty-valued fields (blank cells, absent optionals — nothing to ground) are labeled empty. Neither is ever silently dropped.

4. Cite and show. ade view JOB_ITEM_ID --json builds a self-contained HTML viewer; deep links are the citation contract:

   ade view JOB_ITEM_ID --element-id ELEMENT_ID --json   # emits view.html#element=ELEMENT_ID
   ade crop JOB_ITEM_ID --element-id ELEMENT_ID --json   # PNG of that element's region
   ade crop JOB_ITEM_ID --type figure --json             # every figure, one command

   End answers with one deep link per job item, citing element ids. Use crop when you need to look at evidence mid-reasoning — it takes find's own filters (--type, --page, --all), so a selection crops in one call and returns crops[]; never loop find into crop yourself.

Reuse posture — parse bills once

Every parse the CLI ever runs is a reusable job item. Given a document path, extract -d FILE --schema … reuses the latest completed parse of that path+content (logged in the summary; no parse billed). If none exists, it runs a standalone parse first — a normal, top-level parse item, exactly as if you had run parse -d — then the extraction referencing it: two billable runs, both itemised. Repeat extract -d runs of the same file then reuse that parse, so it bills exactly once.

Prefer the explicit two-step (parse -d, then extract JOB_ITEM_ID) when you want the same parse to feed several schemas — the id makes the reuse visible.