- Re-running an identical command consumes no credits, because the CLI serves it from disk.
- An interrupted job resumes instead of restarting.
- Every result stays available to search, cite, and reuse.
Every Run Is a Job Item
Every command that sends work to the ADE API, such asade parse or ade extract, is recorded as a job item: the run itself plus everything it produced, in its own folder on your machine. Each job item has a 16-character ID, and every command that reads the store accepts the ID or any unambiguous prefix of it.
A job item’s identity is what defines the run: the command, its parameters, the environment, and the document’s path and contents. Change any of those, by editing the document, moving it, or passing different parameters, and the next run creates a new job item rather than replacing the old one.
To see your job items, newest first, list your history:
Command
Output
Commands Are Guarantees
A guarantee command ensures a state instead of firing a request: runningade parse means “make sure this exact run exists.” If it already exists, the CLI serves the result from disk with an explicit notice, makes no API call, and consumes no credits.
Command
Output
Re-Run and Consume Credits Only on Purpose
The--force flag re-runs a completed job item in place and consumes credits again. It is the only flag that makes a repeated command consume credits.
Editing or moving a document changes its identity, so the next parse of it creates a new job item that consumes credits. The old item stays intact and remains true of the run it came from.
Wait for Long Jobs
Parsing a large document can take longer than you want to watch. By default, a command waits up to 600 seconds for its job to finish. Set a different budget with--wait, or pass --wait 0 to submit the job and return immediately.
If the wait runs out, the command exits with code 3 and the job keeps running on the server. That is a normal outcome, not an error. To pick the job back up, run the same command again: it reconnects to the running job instead of starting a new one, so credits are not consumed twice. Stopping the command with Ctrl+C also leaves the job running on the server, and re-running the same command reconnects to it.
You can’t cancel a job after submitting it. It finishes on the server and consumes its credits whether you wait for it or not.
Read the Output
Every command prints human-readable text by default, and reports its outcome with an exit code. Add--json for the whole result as one object on stdout, or --id-only for just the ID. For what each mode guarantees and how to branch on the exit codes, see Scripting and Automation.
The Local Store
Everything the CLI produces lives under~/.ade, with each job item in its own folder. To move the store, set the ADE_HOME environment variable. The CLI Reference lists the complete layout, including the viewer and crop files the CLI builds on demand.
Files in Every Job Item
Files in a Parse Item
Files in an Extract Item
Spans and Ranges
Stored files describe every text location as a span: a pair of offsets into the parse markdown, written as[start, end) and counted in Unicode code points. The API response calls the same thing a range.
Delete Job Items
To delete a job item, runade history clear JOB_ID. Clearing a parse item also clears the extractions that reference it. Never delete the whole store by hand: the CLI binary lives in a subfolder of it, and the rest is your local record of completed runs.
Update the CLI
Runade update to check for a newer release. For installs made with uv or pipx, the CLI Reference covers how updates work.
Next Steps
Parse Documents
Choose an input, a tier, and a model, and see what a run saves.
Extract Fields
Run a schema against a parse and read the grounded result.