> ## Documentation Index > Fetch the complete documentation index at: https://docs.landing.ai/llms.txt > Use this file to discover all available pages before exploring further. # CLI Reference > See every ade CLI command with its flags, result shapes, and exit states. This reference documents every command in the [ade CLI](https://github.com/landing-ai/ade-cli). For the same reference in your terminal, run `ade help`. New to the CLI? Start with the [Quickstart](./quickstart). Commands are listed by group, each with its flags and its `--json` result keys. Behavior that applies across commands (output modes, exit codes, the local store) is covered in [CLI Concepts](./concepts). AI agents: run `ade help --json` to get this entire surface as a single JSON object. ## Credentials and CLI Lifecycle ### `ade auth login` ```text theme={null} ade auth login [options] [--json] ``` Ensure the target environment is logged in; `--api-key` authenticates with a key directly ('-' prompts with hidden input). Targets `--env`, else \$ADE\_ENV, else production - nothing is stored about the choice. | Flag | Value | Default | Description | | ----------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `--api-key` | `TEXT` | | Log in with this API key directly ('-' prompts with hidden input). | | `--org` | `TEXT` | | Act in this Logto organization (id or name). Browser (OAuth) logins only - API keys are already organization-bound. | | `--env` | `TEXT` | | Environment to target: dev, staging, production, eu (default: \$ADE\_ENV, then production). Credentials are stored per environment. | With `--json`, the command prints an object with these keys: | Key | Description | | ----------------------- | --------------------------------------------------------------------------------------------- | | `method` | api\_key \| oauth | | `credential` | masked credential - never the secret | | `stored` | true once written to credentials.json | | `already_authenticated` | present when the target needed nothing | | `environment` | the resolved target | | `endpoint` | its endpoint | | `endpoint_source` | default \| config \| env | | `identity` | OAuth logins: the token's identity claims | | `organization` | OAuth logins: the selected organization (\{id, name}; null when the platform default applies) | ### `ade auth status` ```text theme={null} ade auth status [options] [--json] ``` Show the resolved target's auth method, identity, and expiry, plus every other environment holding a credential. | Flag | Value | Default | Description | | ------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `--env` | `TEXT` | | Environment to target: dev, staging, production, eu (default: \$ADE\_ENV, then production). Credentials are stored per environment. | With `--json`, the command prints an object with these keys: | Key | Description | | ---------------------------------------------------------------- | ------------------------------------------------ | | `authenticated` | false (exit 1) when the target has no credential | | `method` | api\_key \| oauth | | `credential` | masked credential | | `source` | env (ADE\_API\_KEY) \| stored | | `environment / endpoint / endpoint_source` | the resolved target | | `other_environments` | every other environment holding a credential | | `expires_at / expires_in_seconds / refresh_token / organization` | OAuth only | ### `ade auth logout` ```text theme={null} ade auth logout [options] [--json] ``` Log out of one environment (the resolved target by default); `--all` clears every environment. Idempotent; OAuth refresh tokens are revoked best-effort first. | Flag | Value | Default | Description | | ------- | ------ | ------- | ------------------------------------------------------------------------------------------------- | | `--env` | `TEXT` | | Log out of this environment: dev, staging, production, eu (default: \$ADE\_ENV, then production). | | `--all` | | | Log out of every environment at once. | With `--json`, the command prints an object with these keys: | Key | Description | | ------------- | -------------------------------------------- | | `logged_out` | always true - logout is idempotent | | `cleared` | false when there was nothing stored to clear | | `revoked` | refresh tokens revoked best-effort | | `scope` | environment \| all | | `environment` | the environment cleared (null with `--all`) | ### `ade auth org list` ```text theme={null} ade auth org list [options] [--json] ``` List the organizations the target's OAuth session can act in, marking the selected one. Memberships come live from the login provider, so a fresh grant or removal shows immediately - including a selection that is no longer a membership. | Flag | Value | Default | Description | | ------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `--env` | `TEXT` | | Environment to target: dev, staging, production, eu (default: \$ADE\_ENV, then production). Credentials are stored per environment. | With `--json`, the command prints an object with these keys: | Key | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `organizations` | your memberships, live from the login provider: \[\{id, name, selected}] | | `selected` | the selected organization id (null when the platform default applies) | | `selected_is_stale` | true when the selection is no longer one of your memberships - requests still send it and the platform rejects them; switch or clear | | `environment` | the resolved target | ### `ade auth org switch` ```text theme={null} ade auth org switch ORG [options] [--json] ``` Switch which organization the target's OAuth session acts in. Validated against your live memberships here, and membership-verified by the platform on every request regardless. | Argument | Description | | -------- | ---------------------------------- | | `ORG` | Required. Organization id or name. | | Flag | Value | Default | Description | | ------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `--env` | `TEXT` | | Environment to target: dev, staging, production, eu (default: \$ADE\_ENV, then production). Credentials are stored per environment. | With `--json`, the command prints an object with these keys: | Key | Description | | -------------- | ---------------------------------------- | | `organization` | the selection now stored (\{id, name}) | | `previous` | the selection it replaced (null if none) | | `stored` | always true on success | | `environment` | the resolved target | ### `ade auth org clear` ```text theme={null} ade auth org clear [options] [--json] ``` Drop the target's organization selection, falling back to the platform default. Idempotent, and deliberately offline: this is the way out when a selection has outlived its membership, which is exactly when listing memberships may not work. | Flag | Value | Default | Description | | ------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `--env` | `TEXT` | | Environment to target: dev, staging, production, eu (default: \$ADE\_ENV, then production). Credentials are stored per environment. | With `--json`, the command prints an object with these keys: | Key | Description | | -------------- | ---------------------------------------------- | | `organization` | always null - the platform default now applies | | `previous` | the selection that was dropped (null if none) | | `cleared` | false when there was nothing selected | | `environment` | the resolved target | ### `ade login` ```text theme={null} ade login [options] [--json] ``` Alias of `ade auth login`: ensure the target environment is logged in; `--api-key` authenticates with a key directly ('-' prompts with hidden input). | Flag | Value | Default | Description | | ----------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `--api-key` | `TEXT` | | Log in with this API key directly ('-' prompts with hidden input). | | `--org` | `TEXT` | | Act in this Logto organization (id or name). Browser (OAuth) logins only - API keys are already organization-bound. | | `--env` | `TEXT` | | Environment to target: dev, staging, production, eu (default: \$ADE\_ENV, then production). Credentials are stored per environment. | With `--json`, the command prints an object with these keys: | Key | Description | | ----------------------- | --------------------------------------------------------------------------------------------- | | `method` | api\_key \| oauth | | `credential` | masked credential - never the secret | | `stored` | true once written to credentials.json | | `already_authenticated` | present when the target needed nothing | | `environment` | the resolved target | | `endpoint` | its endpoint | | `endpoint_source` | default \| config \| env | | `identity` | OAuth logins: the token's identity claims | | `organization` | OAuth logins: the selected organization (\{id, name}; null when the platform default applies) | ### `ade logout` ```text theme={null} ade logout [options] [--json] ``` Alias of `ade auth logout`: log out of one environment (the resolved target by default); `--all` clears every environment. | Flag | Value | Default | Description | | ------- | ------ | ------- | ------------------------------------------------------------------------------------------------- | | `--env` | `TEXT` | | Log out of this environment: dev, staging, production, eu (default: \$ADE\_ENV, then production). | | `--all` | | | Log out of every environment at once. | With `--json`, the command prints an object with these keys: | Key | Description | | ------------- | -------------------------------------------- | | `logged_out` | always true - logout is idempotent | | `cleared` | false when there was nothing stored to clear | | `revoked` | refresh tokens revoked best-effort | | `scope` | environment \| all | | `environment` | the environment cleared (null with `--all`) | ### `ade version` ```text theme={null} ade version [--json] ``` Print the ade version and install mode: 'binary' (the standalone app - `ade update` replaces it in place) or 'python' (uv/pipx - upgrade with `uv tool upgrade ade-cli`). With `--json`, the command prints an object with these keys: | Key | Description | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `version` | the installed ade version | | `install` | how it is installed: binary (standalone app, self-updates via `ade update`) \| python (uv/pipx - upgrade with `uv tool upgrade ade-cli`) | ### `ade update` ```text theme={null} ade update [options] [--json] ``` Check the release channel for a newer CLI and self-update on confirmation. A standalone-binary install (see `ade version`) replaces itself in place after verifying the release checksum; a uv/pipx install is never mutated - the command reports the newer version and points at `uv tool upgrade ade-cli`. | Flag | Value | Default | Description | | ------- | ----- | ------- | ------------------------------------------------------------------------------------- | | `--yes` | | | Install without the interactive confirmation (required when stdin is not a terminal). | With `--json`, the command prints an object with these keys: | Key | Description | | --------- | ----------------------------------------------------------------------------------------------- | | `current` | the running version | | `latest` | the latest released version (null when the release channel is not visible) | | `updated` | true when this run installed the newer version | | `install` | binary \| python - python installs are never mutated, only pointed at `uv tool upgrade ade-cli` | ### `ade help` ```text theme={null} ade help [COMMAND|TOPIC]... [--json] ``` Print the whole-surface command reference in one call: every command and flag, the output convention, each verb's result shape, exit states, and the store layout. The agent bootstrap - run this (with `--json`) before anything else. `help TOPIC` prints one conceptual page instead (workflow, output, credentials, errors). | Argument | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `[COMMAND\|TOPIC]...` | Scope the reference to one command or group (`help extract`, `help auth login`), or print a topic: workflow, output, credentials, errors. | With `--json`, the command prints an object with these keys: | Key | Description | | ----------------------------- | ---------------------------------------------------- | | `cli / version / description` | what this binary is | | `conventions` | the rules every command follows | | `commands` | every command: usage, arguments, flags, result shape | | `topics` | the conceptual pages (`ade help workflow`) | | `exit_states` | every exit code and what it means | | `store` | the on-disk layout | ## Network Verbs: The ADE Job Contracts ### `ade parse` ```text theme={null} ade parse [options] [--json] ``` Ensure a document is parsed; persist all artifacts locally. The summary names the job item id every other verb takes: `find` it, `view` it, `extract` against it. The raw result stored in `parse.json` follows the [Parse API](https://docs.landing.ai/api-reference/parse/ade-parse) response schema. | Flag | Value | Default | Description | | ---------------- | -------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-d, --document` | `FILE` | | Local document file to parse; pass exactly one of -d/`--document` or `--document-url`. | | `--document-url` | `TEXT` | | Document URL the server fetches (identity is the URL x params; a re-run dedups even if the remote content changed - `--force` refreshes). | | `--model` | `TEXT` | `dpt-3-pro-latest` | Parse model registry version. | | `--tier` | `priority\|standard` | `priority` | Async lane: priority (full price, fast lane) or standard (half price, slower lane). The CLI defaults to priority. | | `--pages` | `TEXT` | | 1-indexed, e.g. '1,3-5'. | | `--options` | `TEXT` | | Full ParseOptions pass-through as a JSON object, sent verbatim (the server rejects unknown keys with a 422). Keys as of this release - pages: 1-indexed integer array (default: all pages); atomic\_grounding: bool (default true; false omits the per-line atomic\_grounding field from every node); inline\_markdown: bool (default false; true adds each node's own markdown slice inline); blocks.\.markdown: bool (default true; false suppresses that type's markdown; types: text, table, figure, marginalia, attestation, logo, scan\_code, card); blocks.table.format: 'html' (default) or 'markdown'; password: always rejected (422) - decrypt PDFs before upload. Example: '\{"inline\_markdown": true, "blocks": \{"table": \{"format": "markdown"}}}'. Merges with `--pages`; giving pages in both is an error. | | `--env` | `TEXT` | | Environment to run against: dev, staging, production, eu (default: \$ADE\_ENV, then production). Environments keep separate results - the job item id includes the environment. | | `--wait` | `FLOAT` | `600.0` | Poll budget in seconds. | | `--force` | | | Re-parse even if already parsed, or abandon an unreadable job for a fresh one (bills a new parse). | | `--keep-copy` | | | `--document-url` only: also download the document into the job item (plain HTTP, no API credits) so page previews and crops render locally - fetched now, while the URL (often pre-signed) still works. Without it, the first `view`/`crop` fetches the copy instead, by which time a pre-signed URL may have expired. | | `--include` | `markdown\|elements` | | Carry a bulk artifact in the payload instead of leaving it on disk: markdown (the parse markdown) or elements (the flat projection `find` searches). Repeatable. | | `--id-only` | | | Print only the id(s) this run produced, one per line - the piping mode (JOB=\$(ade parse -d f.pdf `--id-only`)). Takes precedence over `--json`; errors and hints go to stderr. | With `--json`, the command prints an object with these keys: | Key | Description | | ----------------- | --------------------------------------------------------------------------------------- | | `status` | 'parsed' | | `run_id` | server-side run id (the wire's job\_id) | | `job_item_id` | store key every other verb takes | | `environment` | resolved environment | | `version` | resolved parse model version | | `credits` | credits billed (0 on a cached hit) | | `tier` | service tier the run was billed at | | `page_count` | pages parsed | | `failed_pages` | 1-indexed pages the server could not parse | | `cached` | true when served free from the store | | `stored` | false when the result could not be persisted | | `store_dir` | absolute path of the job item folder | | `artifacts` | artifact filenames written there | | `markdown` | the parse markdown - only with `--include` markdown | | `elements` | the flat projection - only with `--include` elements | | `kept_copy` | with `--keep-copy`: whether the URL document's copy was stored in the job item | | `keep_copy_error` | with `--keep-copy`: why the copy could not be stored (the parse itself still succeeded) | ### `ade extract` ```text theme={null} ade extract [JOB_ITEM_ID] --schema TEXT [options] [--json] ``` Ensure an extraction exists for a parse job item (or bring-your-own markdown); persist the result as its own job item. The schema-shaped result rides in the payload (`extraction`) with its per-field evidence; `view JOB_ITEM_ID` renders the same join on the page, and `find`/`crop` on the referenced parse reach the cited elements. The raw result stored in `extract.json` follows the [Extract API](https://docs.landing.ai/api-reference/extract/ade-extract) response schema. | Argument | Description | | --------------- | ------------------------------------------------------ | | `[JOB_ITEM_ID]` | A completed parse job item id (or unambiguous prefix). | | Flag | Value | Default | Description | | ---------------- | -------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--schema` | `TEXT` | | Required. JSON Schema file or inline JSON object. | | `-d, --document` | `FILE` | | Extract by document path: reuse the latest completed parse of this path+content, else run a standalone parse job first - as if you had run `parse -d` - then extract (two billable jobs, both itemised). | | `--markdown` | `FILE` | | Escape hatch: extract from markdown that did not come from parse. | | `--markdown-url` | `TEXT` | | Escape hatch: extract from markdown fetched from a URL server-side (the response's echoed markdown is stored). | | `--model` | `TEXT` | `extract-latest` | Extract model registry version. | | `--tier` | `priority\|standard` | `priority` | Async lane: priority (full price, fast lane) or standard (half price, slower lane). The CLI defaults to priority. | | `--strict` | | | v2 ExtractOptions pass-through: the server rejects (422) schemas with fields the model cannot extract instead of skipping them. | | `--env` | `TEXT` | | Environment to run against: dev, staging, production, eu (default: \$ADE\_ENV, then production). The JOB\_ITEM\_ID form inherits the parse item's environment instead - its server-side parse job only exists there - and a conflicting `--env` is refused. | | `--wait` | `FLOAT` | `600.0` | Poll budget in seconds. | | `--force` | | | Re-extract even if already extracted, or abandon an unreadable job for a fresh one (bills a new extract). | | `--id-only` | | | Print only the id(s) this run produced, one per line - the piping mode (JOB=\$(ade parse -d f.pdf `--id-only`)). Takes precedence over `--json`; errors and hints go to stderr. | With `--json`, the command prints an object with these keys: | Key | Description | | ------------------------ | -------------------------------------------------------------------------------------------- | | `status` | 'extracted' | | `run_id` | server-side run id (the wire's job\_id) | | `job_item_id` | this extraction's own job item | | `parse_job_item_id` | the parse it references (absent for markdown) | | `environment` | resolved environment | | `version` | resolved extract model version | | `credits` | credits billed (0 on a cached hit) | | `tier` | service tier the run was billed at | | `extraction` | THE RESULT: the schema-shaped object, verbatim | | `fields` | number of leaf fields | | `ungroundable` | field paths whose non-empty value has no box | | `empty_fields` | field paths with no value (nothing to ground) | | `schema_violation_error` | set when the extraction is partial (strict=false skipped schema fields); null on a clean run | | `warnings` | server warnings, verbatim (\[] when none) | | `evidence` | \{kind, reason?, fields\[]} - the field→box join | | `cached` | true when served free from the store | | `stored` | false when the result could not be persisted | | `store_dir` | absolute path of the job item folder | | `artifacts` | artifact filenames written there | | `reused_parse` | the parse reused, when one was (no parse billed) | | `parsed_first` | the standalone parse run first, when one was | ## Local Read Models ### `ade history list` ```text theme={null} ade history list [options] [--json] ``` List stored job items: id, kind, state, env, params, source - the newest 100 submissions first (`--limit`/`--all` adjust, `--asc` for oldest first). Extract items referencing a parse item indent beneath it. Bare `ade history` defaults to this command. | Flag | Value | Default | Description | | --------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `--asc` | | | Oldest submission first (the pre-1.0.3 order). The listing defaults to newest first - the run you just did leads, matching the viewer sidebar. | | `--limit` | `INTEGER` | `100` | Keep only the newest N items (default 100), whatever the order; `--all` lifts the cap. | | `--all` | | | List every stored job item - no limit. | With `--json`, the command prints an array of objects with these keys: | Key | Description | | --------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `job_item_id` | the item | | `kind` | parse \| extract | | `state` | derived from the ticket and artifacts on disk | | `run_id` | server-side run id of the recorded generation | | `source` | document path, URL, or markdown file | | `params` | the invocation params, verbatim | | `parse` | extract items: the referenced parse - \{job\_item\_id, run\_id (the parse generation extracted against), missing} | | `stale` | extract items: true when the referenced parse was `--force` re-run after this extraction | | `created_at / completed_at` | epoch seconds (null when unknown) | ### `ade history clear` ```text theme={null} ade history clear [JOB_ITEM_ID] [options] [--json] ``` Delete stored job items. Clearing a parse item cascades - with notice - to the extract items referencing it, so the store never holds dangling refs. | Argument | Description | | --------------- | ---------------------------------- | | `[JOB_ITEM_ID]` | Job item id or unambiguous prefix. | | Flag | Value | Default | Description | | ------- | ----- | ------- | ----------------------------- | | `--all` | | | Delete every stored job item. | With `--json`, the command prints an object with these keys: | Key | Description | | ---------- | ---------------------------------------------------- | | `cleared` | job item ids removed | | `cascaded` | extract items removed with the parse they referenced | ### `ade find` ```text theme={null} ade find [JOB_ITEM_ID] [QUERY] [options] [--json] ``` Search parsed elements locally: `find JOB_ITEM_ID [QUERY]`, or `--job` (repeatable) for several items; no query lists every element. Ids discovered here are what `view --element-id` deep-links and `crop --element-id` renders - though `crop` takes these same filters directly (`crop JOB_ITEM_ID --type figure`) when you want the images rather than the records. | Argument | Description | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `[JOB_ITEM_ID] [QUERY]` | Job item id (or unambiguous prefix) to search, then an optional case-insensitive substring QUERY. With `--job`, the one allowed positional is the QUERY. | | Flag | Value | Default | Description | | -------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--job` | `TEXT` | | Parse job item to search (id or unambiguous prefix); repeatable for multi-item search. Equivalent to the positional JOB\_ITEM\_ID for a single item. | | `--regex` | | | Treat QUERY as a regular expression (case-insensitive; scope with (?-i:...)). | | `--type` | `TEXT` | | Element type (text, table, table\_cell, figure, ...). | | `--page` | `INTEGER` | | 1-indexed page number. | | `--element-id` | `TEXT` | | Exact element id to match; repeatable. | | `--limit` | `INTEGER` | | Return at most this many matches. | | `--id-only` | | | Print only the id(s) this run produced, one per line - the piping mode (JOB=\$(ade parse -d f.pdf `--id-only`)). Takes precedence over `--json`; errors and hints go to stderr. | With `--json`, the command prints an array of objects with these keys: | Key | Description | | ------------- | ---------------------------------------------------- | | `job_item_id` | the parse item the match came from | | `element_id` | element id - what crop and view take | | `type` | element type (text, table, table\_cell, figure, ...) | | `page` | 1-indexed page | | `box` | \{xmin, ymin, xmax, ymax} fractions of page size | | `text` | the element's markdown slice | ### `ade view` ```text theme={null} ade view [JOB_ITEM_ID] [options] [--json] ``` Build a job item's self-contained grounded HTML viewer. | Argument | Description | | ------------- | -------------------------------------------------------------------------- | | `JOB_ITEM_ID` | Job item id or unambiguous prefix (default: the latest viewable job item). | | Flag | Value | Default | Description | | --------------------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--element-id` | `TEXT` | | Emit a deep link to this element. | | `--crop` | | | With `--element-id`: render that element's PNG crop instead of the HTML artifact. | | `--open, --no-open` | | | Open the result in the browser. Default: open when stdout is a terminal; `--json` runs and piped output never auto-open. | | `--dpi` | `INTEGER` | | Page render dpi (default 120); with `--crop`, the crop dpi (default 300). | | `--pages` | `TEXT` | | Pages to embed images for, 1-indexed, e.g. '1,3-5'. | | `--download, --no-download` | | | URL-parsed items: fetch the document from its recorded URL into the job item and render page previews from that copy - the parse itself never gives the CLI the bytes (#169). This happens automatically when no copy is attached yet (a notice and progress line land on stderr); `--no-download` skips the fetch and previews stay empty. Explicit `--download` makes a failed fetch an error instead of a warning. Plain HTTP, no API credits; the copy is unverified against the parsed run. Also works on an extract item id (fetches into its referenced parse item). | | `--no-sidebar-sync` | | | Skip the background build of missing sibling viewers. | | `--serve` | | | Open via a local server ([http://127.0.0.1](http://127.0.0.1)) instead of file:// - browser zoom then covers every viewer natively. Starts the server if needed; reuses a running one. It retires itself after 30 idle minutes, or immediately with `--stop-server`. | | `--stop-server` | | | Stop the local viewer server (started by `--serve`) and exit. | With `--json`, the command prints an object with these keys: | Key | Description | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `status` | 'viewed' ('cropped' with `--crop`, 'synced' with `--sync-viewers`) | | `job_item_id` | the item rendered | | `kind` | parse \| extract | | `path` | the self-contained view\.html (or the PNG, with `--crop`) | | `built` | true when this run rebuilt the artifact | | `pages_embedded` | pages inlined; the rest load from sidecars | | `note` | why the render weakened, when it did (else null) | | `downloaded` | URL items: true when this run fetched the document into the job item (automatic on first view). false when the automatic fetch failed (see download\_error) or explicit `--download` found the copy already attached; absent when nothing needed fetching | | `download_error` | why the automatic fetch failed, when it did (the viewer still builds, previews empty; else absent) | | `deep_link` | view\.html#element=... when `--element-id` was given | | `history_items` | items in the rebuilt sidebar read model | | `sidebar_sync` | true when sibling viewers build in the background | ### `ade crop` ```text theme={null} ade crop [JOB_ITEM_ID] [options] [--json] ``` Crop element regions from the source document into PNGs: one `--element-id`, or a filtered batch (`--type figure`, `--page`, `--all`) with the same filters `ade find` searches by. | Argument | Description | | --------------- | ---------------------------------- | | `[JOB_ITEM_ID]` | Job item id or unambiguous prefix. | | Flag | Value | Default | Description | | --------------------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--element-id` | `TEXT` | | Element to crop (ids from `ade find`); repeatable. | | `--type` | `TEXT` | | Crop every element of this type (text, table, figure, ...) - `find`'s filter, applied here. | | `--page` | `INTEGER` | | Restrict the selection to this 1-indexed page. | | `--all` | | | Crop every element the filters select (on its own: the whole item). | | `-o, --output` | `PATH` | | Where the crops land: a directory (a single crop lands inside it too), or - for a single crop only - the PNG path itself (default: the job item's crops/ dir). | | `--dpi` | `INTEGER` | `300` | Render dpi. | | `--open` | | | Open the crop (or the directory holding them). | | `--download, --no-download` | | | URL-parsed items: fetch the document from its recorded URL into the job item and crop from that copy - the parse itself never gives the CLI the bytes (#169). This happens automatically when no copy is attached yet (a notice and progress line land on stderr); `--no-download` skips the fetch, and the crop then fails honestly (a crop has no empty-imagery fallback). | With `--json`, the command prints an object with these keys: | Key | Description | | ------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `status` | 'cropped' | | `job_item_id` | the addressed item (crops land under its crops/) | | `count` | how many PNGs were written | | `directory` | where they landed | | `crops` | one record per PNG (element\_id, type, page, box, dpi, path, width, height) | | `downloaded` | URL items: true when this run fetched the document into the parse item before cropping (absent when nothing needed fetching) | ## Exit States Every command exits with one of these codes. See [Scripting and Automation](./scripting-automation) for how to use them in scripts. | Code | State | Meaning | | ---- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `0` | `ok` | Success - the command's payload is on stdout. | | `1` | `failed` | The run failed or the target cannot serve the request (job failure, unknown id, missing parse, unreadable result). | | `2` | `usage` | The invocation itself was wrong; nothing was submitted. | | `3` | `pending` | The wait budget expired while the run continues server-side - a normal outcome, not an error. The payload carries a 'pending' status plus the run\_id and job\_item\_id; re-run the same command to resume polling (never resubmits, never re-bills). | | `4` | `rate_limited` | Submit was rate-limited and the wait budget ran out before a job existed; nothing was submitted, nothing bills. Re-run to retry. | ## Store Layout The local store lives at \~/.ade (ADE\_HOME overrides). | Path | Contents | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `~/.ade/config.json` | endpoint + named-environment config | | `~/.ade/credentials.json` | per-environment credentials (mode 0600; written by `auth login`) | | `~/.ade/history.js` | sidebar read model over jobs/, rewritten from a fresh store scan by every view/history run | | `~/.ade/jobs//` | one folder per run - parse and extract alike, all top-level siblings (flat, never nested) | | ` meta.json` | commit record: kind, source, identity, params, state, timestamps, artifact index. Its job\_id field is the server-side run id (= run\_id in `--json` payloads), never the job item id | | ` job.json` | claim ticket: the server-side run id (spelled job\_id on disk), tier, state - what a re-run resumes | | ` parse.json / parse.md / elements.json` | parse items: the raw ParseResponse verbatim, its markdown, and the flat elements projection (grounding inline) | | ` extract.json / evidence.json` | extract items: the raw result verbatim and the local field→box evidence join | | ` parse/ref.json` | parse-backed extract items: the reference to the parse job item (artifacts are never copied) | | ` markdown.md` | bring-your-own-markdown extract items: the input markdown, copied in (spans index exactly these bytes) | | ` document.` | URL parses: the attached document copy (`parse --keep-copy`, or fetched automatically on first `view`/`crop`) page previews and crops render from - unverified against the parsed run | | ` view.html / crops/` | derived artifacts: the self-contained viewer and PNG crops - recomputable, built on demand | ## Conventions * **`--json`**: Every command supports `--json`: one stable JSON object/array on stdout (errors and pending payloads follow the same rule). Agents should always pass it. Each command's published shape is its 'result' block below - the full result is always on stdout, never only in a file. * **`--id-only`**: parse, extract, and find also take `--id-only`: just the id(s), one per line, for piping (JOB=\$(ade parse -d f.pdf `--id-only`)). Errors and hints go to stderr so a captured id is never a sentence. * **`job item ids`**: Store commands take a job item id or an unambiguous prefix. Discover ids with `history list`; ambiguous or unknown ids error with candidates listed. Distinct from the server-side run id: `--json` payloads report that as run\_id, and on-disk records spell the same value job\_id (the wire's name) - neither is ever a job item id. * **`guarantees`**: parse and extract ensure a run exists rather than fire a request: an already-done run is served from disk free with an explicit notice (`--force` consents to a re-bill); a pending run is resumed, never resubmitted; Ctrl-C stops the waiting, not the work. * **`env overrides`**: ADE\_HOME relocates the store; ADE\_API\_KEY overrides stored credentials; ADE\_ENDPOINT overrides the stored endpoint. ## Help Topics The CLI ships conceptual help topics (`ade help `). Each one is covered in depth by a guide page: | Topic | Guide | | ---------------------- | -------------------------------------------------- | | `ade help workflow` | [CLI Concepts](./concepts) | | `ade help output` | [Scripting and Automation](./scripting-automation) | | `ade help credentials` | [Authentication](./authentication) | | `ade help errors` | [Scripting and Automation](./scripting-automation) | ## Next Steps Job items, output modes, exit codes, and the local store. Pipe results, handle exit codes, and run the CLI from agents and CI.