---
name: ade
description: Parse documents and extract schema-shaped data with the ADE (Agentic Document Extraction) v2 APIs through the ade CLI. A local job-item store makes every run idempotent, resumable, and citable — repeat runs are free, interrupted runs resume, and every answer can cite element ids with visual evidence.
---

# 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.

## Pending and resume

Wait expiry is a normal outcome, not an error. If the poll budget
(`--wait`, default 600s) runs out, the command exits with code 3 and a
`{"status": "pending", "run_id": …, "job_item_id": …}` payload while the
run continues server-side (submitted work always completes and bills —
there is no cancel). **The recovery gesture is always the same command,
re-run.** A re-run joins the recorded run; it never resubmits and never
re-bills. Interrupts (Ctrl-C) stop the waiting, not the work — same
gesture. `--wait 0` submits and returns immediately.

Submit-and-return, then collect later — the pending payload carries the
id too, so this works in both steps:

```
JOB=$(ade parse -d report.pdf --wait 0 --id-only)   # exit 3, run continuing
ade parse -d report.pdf --json                       # re-run: resumes, never re-bills
```

## Exit codes

| Code | State | Meaning |
|------|-------|---------|
| 0 | ok | Success — the payload is on stdout. |
| 1 | failed | The run failed or the target cannot serve the request. |
| 2 | usage | The invocation itself was wrong; nothing was submitted. |
| 3 | pending | Wait budget expired; the run continues server-side. Re-run the same command to resume. |
| 4 | rate_limited | Submit was rate-limited and the wait budget ran out before a run existed; nothing billed. Re-run to retry. |

## Reading the store directly

Optional, never required: every result is already on stdout. Artifacts
are plain files — `history list --json` gives every item's records, and
the summaries print each item's store path.

- `parse.json` — raw ParseResponse (ground truth, verbatim)
- `parse.md` — the parse markdown extraction spans index
- `elements.json` — flat element records with inline grounding; boxes
  are normalized `{xmin, ymin, xmax, ymax}` fractions of page size in
  `[0, 1]`
- `extract.json` — raw extraction result with per-field spans
- `evidence.json` — the field→box join (element ids, pages, boxes)

One vocabulary note when reading these files: on-disk records
(`meta.json`, `job.json`, `parse/ref.json`) spell the server-side run id
as `job_id` — the wire contract's name for the same value `--json`
payloads report as `run_id`. Neither is ever the job item id.

Prefer `find` over loading `elements.json` into context: it returns
joined records, not lines. `history clear JOB_ITEM_ID` deletes an item;
clearing a parse item cascades to the extractions referencing it.

## Sharp edges

- **`--options` is a verbatim ParseOptions pass-through** — the server
  rejects unknown keys with a 422, so consult `ade help parse` for
  the accepted keys rather than guessing.
- **Parse variants coexist.** The same document parsed with different
  params is a sibling item, not a replacement. An extraction goes stale
  only when its exact parse item is re-run in place with `--force`.
- **Moving or editing a file changes identity** — the next parse of it
  is a new job item that bills. The old item and its evidence stay
  intact and true of the run they came from.
- **`--markdown` extractions have no page evidence** (there is no parse
  to join against) — evidence degrades to spans-only, and `view`
  renders the markdown pane alone.
- **URL parses have no local bytes**, so page imagery renders from an
  attached copy: `parse --document-url … --keep-copy` fetches it at
  parse time (reliable — pre-signed URLs expire); otherwise the first
  `view`/`crop` downloads it automatically (`--no-download` skips;
  the payload records `downloaded`, and on a failed fetch `view`
  degrades to an empty preview with `download_error` while `crop`
  errors). Markdown, elements, and extractions work either way.