ade
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.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/landing-ai--ade-cli)HTML
<a href="/listings/landing-ai--ade-cli"><img src="/api/listings/landing-ai--ade-cli/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
Each release ships self-contained binaries for macOS, Linux, and Windows (arm64 and x86_64). No Python or `uv` needed.
**macOS / Linux**
curl -fsSL https://raw.githubusercontent.com/landing-ai/ade-cli/main/scripts/install.sh | sh
**Windows (PowerShell)**
irm https://raw.githubusercontent.com/landing-ai/ade-cli/main/scripts/install.ps1 | iex
**Windows (CMD)**
curl -fsSL https://raw.githubusercontent.com/landing-ai/ade-cli/main/scripts/install.cmd -o install.cmd && install.cmd && del install.cmd
To develop or install from source, see [CONTRIBUTING.md](CONTRIBUTING.md).
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 199 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- 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.
README.md · README · 132 lines · 2 findings marked
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # ade-cli
- [](https://github.com/landing-ai/ade-cli/releases)
- [](LICENSE)
- **Agentic Document Extraction (ADE), from your terminal.** Run `ade parse` to
- turn documents with tables, figures, and charts into grounded Markdown and
- elements, and `ade extract` to pull schema-shaped fields with page-and-box
- evidence. Both save to a local store at `~/.ade`, so re-running an identical
- command consumes no credits.
- **[CLI documentation](https://docs.landing.ai/cli/quickstart)** ·
- **[Playground](https://ade.landing.ai)** ·
- **[Get an API key](https://ade.landing.ai/settings/api-key)**
- ## Install
- Each release ships self-contained binaries for macOS, Linux, and Windows
- (arm64 and x86_64). No Python or `uv` needed.
- **macOS / Linux**
- ```sh
- curl -fsSL https://raw.githubusercontent.com/landing-ai/ade-cli/main/scripts/install.sh | sh
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 24 on GitHub
- ```
- **Windows (PowerShell)**
- ```powershell
- irm https://raw.githubusercontent.com/landing-ai/ade-cli/main/scripts/install.ps1 | iex
- Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
- Line 30 on GitHub
- ```
- **Windows (CMD)**
- ```bat
- curl -fsSL https://raw.githubusercontent.com/landing-ai/ade-cli/main/scripts/install.cmd -o install.cmd && install.cmd && del install.cmd
- ```
- To develop or install from source, see [CONTRIBUTING.md](CONTRIBUTING.md).
- ## First run
- Log in once per machine, parse a document, then extract the fields you want
- from it. The parse summary prints the job item ID that `extract` takes.
- ```sh
- ade login
- ade parse -d invoice.pdf
- ade extract JOB_ITEM_ID --schema schema.json
- ```
- The [CLI Quickstart](https://docs.landing.ai/cli/quickstart) walks through the
- same three steps with a sample document and a sample schema, and ends in the
- viewer that shows where each extracted value came from.
- ## Commands
- Every command takes `--json` for one stable JSON object on stdout. Run
- `ade help COMMAND` for its flags and result shape, or see the
- [CLI Reference](https://docs.landing.ai/cli/reference).
- | command | what it does |
- |---|---|
- | `ade parse` | Parse a document into Markdown, elements, and grounding |
- | `ade extract` | Pull schema-shaped fields from a parse, with per-field evidence |
- | `ade find` | Search a parse's elements locally, with no API call |
- | `ade crop` | Save an element's region of the page as a PNG |
- | `ade view` | Build and open a self-contained HTML viewer for a job item |
- | `ade history list` | List stored job items, newest first |
- | `ade history clear` | Delete stored job items |
- | `ade login` / `ade auth login` | Log in with your browser or an API key |
- | `ade auth status` | Show how you are authenticated and where |
- | `ade auth org list` / `switch` / `clear` | Choose which organization your runs act in |
- | `ade logout` / `ade auth logout` | Log out of one environment, or all of them |
- | `ade version` | Print the version and install mode |
- | `ade update` | Self-update to the latest release |
- | `ade help` | Print the whole command surface, including `--json` result shapes |
- The documentation covers what these tables cannot: how job items work and why
- re-runs are free ([CLI Concepts](https://docs.landing.ai/cli/concepts)),
- [parsing](https://docs.landing.ai/cli/parse) and
- [extraction](https://docs.landing.ai/cli/extract) in depth,
- [searching and cropping evidence](https://docs.landing.ai/cli/find-crop-view),
- [authentication and organizations](https://docs.landing.ai/cli/authentication),
- and [scripting the CLI](https://docs.landing.ai/cli/scripting-automation).
- ## For agents
- Agents are first-class callers. Running `ade help --json` returns the entire
- shipped surface in one call: every command, flag, result shape, topic, exit
- state, and the store layout. Every command then takes `--json` and emits one
- stable object whose shape is published per verb, and the full result is always
- on stdout rather than only in a store file.
- [`SKILL.md`](SKILL.md) ships the agent contract: the loop, the conventions, and
- the sharp edges.
- A process that is already running keeps the environment it started with, so
- `ade` may not be on the PATH inside CI, cron, or an agent harness. Call the
- absolute path instead: `~/.ade/bin/ade` on macOS and Linux, or
- `%USERPROFILE%\.ade\bin\ade.exe` on Windows. For credentials, set
- `ADE_API_KEY`.
- ## Managing your install
- | | macOS and Linux | Windows |
- |---|---|---|
- | App | `~/.ade/bin/ade` | `%USERPROFILE%\.ade\bin\ade.exe` |
- | Store | `~/.ade` | `%USERPROFILE%\.ade` |
- | Reaches your PATH via | a symlink in `~/.local/bin` | a user PATH entry |
- Set `ADE_HOME` to move the app and the store, `ADE_CLI_VERSION` to pin a
- version, and `ADE_CLI_INSTALL_DIR` to change the destination.
- Run `ade update` to self-update, with `--yes` to skip the confirmation. For a
- `uv` or `pipx` install it points at `uv tool upgrade ade-cli` instead. The CLI
- mentions new releases on stderr once a day. Set `ADE_NO_UPDATE_CHECK=1` to turn
- that off.
- To uninstall, remove the app directory, and on macOS and Linux the
- `~/.local/bin/ade` symlink too. Never delete all of `.ade`: the rest of that
- directory holds results that already consumed credits.
- ## Project history
- This repository was **`agentic-doc`**, the original Agentic Document Extraction
- SDK. That SDK is preserved unchanged, and no longer developed, on the
- [`legacy`](https://github.com/landing-ai/ade-cli/tree/legacy) branch. Since
- 2026-07-31 this repository ships the ADE CLI.
- ## License
- [Apache-2.0](LICENSE).
scripts/install.cmd · Bundled script · 23 lines · 1 finding marked
- @echo off
- rem ade-cli installer for Windows CMD — a thin wrapper that runs the
- rem PowerShell installer (install.ps1), the single Windows install body.
- rem
- rem curl -fsSL https://raw.githubusercontent.com/landing-ai/ade-cli/main/scripts/install.cmd -o install.cmd && install.cmd && del install.cmd
- rem
- rem Same knobs as install.ps1: ADE_CLI_VERSION, ADE_CLI_INSTALL_DIR, and
- rem GITHUB_TOKEN/GH_TOKEN (also used here to fetch install.ps1 itself while
- rem the repo is private).
- setlocal
- set "PS1_URL=https://raw.githubusercontent.com/landing-ai/ade-cli/main/scripts/install.ps1"
- where powershell >nul 2>nul
- if errorlevel 1 (
- echo error: PowerShell is required but was not found on PATH. 1>&2
- exit /b 1
- )
- powershell -NoProfile -ExecutionPolicy Bypass -Command ^
- "$t = $env:GITHUB_TOKEN; if (-not $t) { $t = $env:GH_TOKEN };" ^
- "$p = @{ Uri = '%PS1_URL%' }; if ($t) { $p.Headers = @{ Authorization = 'Bearer ' + $t } };" ^
- "Invoke-RestMethod @p | Invoke-Expression"
- Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
- Line 22 on GitHub
- exit /b %errorlevel%
scripts/install.ps1 · Bundled script · 116 lines · 1 finding marked
- # ade-cli installer for Windows (x86_64 / arm64).
- #
- # irm https://raw.githubusercontent.com/landing-ai/ade-cli/main/scripts/install.ps1 | iex
- Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
- Line 3 on GitHub
- #
- # Environment knobs:
- # ADE_CLI_VERSION release to install ("0.2.0" or "v0.2.0"; default: latest)
- # ADE_CLI_INSTALL_DIR where the app lands: ade.exe plus its _internal\
- # support dir (default: %USERPROFILE%\.ade\bin — inside
- # the CLI's own home, next to the store; honors ADE_HOME)
- # GITHUB_TOKEN/GH_TOKEN required while the repo is private; downloads go
- # through the GitHub API instead of the public URL.
- #
- # Uninstall: remove %USERPROFILE%\.ade\bin (ade.exe and its _internal\
- # support dir). Never delete all of .ade — the rest of that directory is
- # your local store (billed results).
- $ErrorActionPreference = "Stop"
- $Repo = "landing-ai/ade-cli"
- $InstallDir = if ($env:ADE_CLI_INSTALL_DIR) { $env:ADE_CLI_INSTALL_DIR }
- elseif ($env:ADE_HOME) { Join-Path $env:ADE_HOME "bin" }
- else { Join-Path $env:USERPROFILE ".ade\bin" }
- $Version = if ($env:ADE_CLI_VERSION) { $env:ADE_CLI_VERSION } else { "latest" }
- $Token = if ($env:GITHUB_TOKEN) { $env:GITHUB_TOKEN } elseif ($env:GH_TOKEN) { $env:GH_TOKEN } else { $null }
- # --- pick the release asset for this machine --------------------------------
- $target = switch ([System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture) {
- "Arm64" { "windows-arm64" }
- "X64" { "windows-x86_64" }
- default { throw "unsupported architecture: $_" }
- }
- $Asset = "ade-cli-$target.zip"
- $Tag = if ($Version -eq "latest") { $null }
- elseif ($Version.StartsWith("v")) { $Version } else { "v$Version" }
- $Tmp = Join-Path ([System.IO.Path]::GetTempPath()) "ade-cli-install-$PID"
- New-Item -ItemType Directory -Force -Path $Tmp | Out-Null
- try {
- # --- download ------------------------------------------------------------
- # Anonymous installs use the public download URL; with a token we resolve
- # asset ids through the API, which also works while the repo is private.
- $ReleaseJson = $null
- function Fetch-Asset([string]$Name, [string]$OutFile) {
- if ($Token) {
- if (-not $script:ReleaseJson) {
- $RelUrl = if ($Tag) { "https://api.github.com/repos/$Repo/releases/tags/$Tag" }
- else { "https://api.github.com/repos/$Repo/releases/latest" }
- $script:ReleaseJson = Invoke-RestMethod -Uri $RelUrl -Headers @{ Authorization = "Bearer $Token" }
- }
- $Found = $script:ReleaseJson.assets | Where-Object { $_.name -eq $Name }
- if (-not $Found) { throw "release has no asset $Name" }
- Invoke-WebRequest -Uri "https://api.github.com/repos/$Repo/releases/assets/$($Found.id)" `
- -Headers @{ Authorization = "Bearer $Token"; Accept = "application/octet-stream" } `
- -OutFile $OutFile
- } else {
- $Url = if ($Tag) { "https://github.com/$Repo/releases/download/$Tag/$Name" }
- else { "https://github.com/$Repo/releases/latest/download/$Name" }
- Invoke-WebRequest -Uri $Url -OutFile $OutFile
- }
- }
- Write-Host "downloading $Asset ($Version) ..."
- $Zip = Join-Path $Tmp $Asset
- try {
- Fetch-Asset $Asset $Zip
- } catch {
- throw "download failed ($_) — while the repo is private, set GITHUB_TOKEN and retry"
- }
- # --- verify ----------------------------------------------------------------
- $Sums = Join-Path $Tmp "SHA256SUMS.txt"
- try { Fetch-Asset "SHA256SUMS.txt" $Sums } catch { $Sums = $null }
- if ($Sums) {
- $Line = Get-Content $Sums | Where-Object { $_ -match [regex]::Escape($Asset) + "$" }
- if (-not $Line) { throw "SHA256SUMS.txt has no entry for $Asset" }
- $Expected = ($Line -split "\s+")[0]
- $Actual = (Get-FileHash -Algorithm SHA256 $Zip).Hash
- if ($Expected -ne $Actual) { throw "checksum mismatch for $Asset" }
- Write-Host "checksum OK"
- } else {
- Write-Warning "SHA256SUMS.txt not found on the release; skipping verification"
- }
- # --- install ---------------------------------------------------------------
- # The zip holds a onedir app: ade\ade.exe plus ade\_internal\ with the
- # bundled libraries (a single-file exe would re-extract those on
- # every launch and get rescanned each time — issue #83). Both pieces land
- # in $InstallDir so the exe sits next to its _internal dir.
- New-Item -ItemType Directory -Force -Path $InstallDir | Out-Null
- Expand-Archive -Path $Zip -DestinationPath $Tmp -Force
- Remove-Item -Recurse -Force (Join-Path $InstallDir "_internal") -ErrorAction SilentlyContinue
- Remove-Item -Force (Join-Path $InstallDir "ade.exe") -ErrorAction SilentlyContinue
- Remove-Item -Force (Join-Path $InstallDir "ade-cli.exe") -ErrorAction SilentlyContinue
- Move-Item -Force (Join-Path $Tmp "ade\_internal") (Join-Path $InstallDir "_internal")
- Move-Item -Force (Join-Path $Tmp "ade\ade.exe") (Join-Path $InstallDir "ade.exe")
- Write-Host "installed $(& (Join-Path $InstallDir 'ade.exe') version) to $InstallDir\ade.exe"
- # --- PATH (user-level) -------------------------------------------------------
- $UserPath = [Environment]::GetEnvironmentVariable("Path", "User")
- if (($UserPath -split ";") -notcontains $InstallDir) {
- $NewPath = if ($UserPath) { "$UserPath;$InstallDir" } else { $InstallDir }
- [Environment]::SetEnvironmentVariable("Path", $NewPath, "User")
- $env:Path = "$env:Path;$InstallDir"
- Write-Host "added $InstallDir to your user PATH (open a new terminal to pick it up)"
- }
- Write-Host "run: ade --help"
- # The user PATH above reaches processes started after it — a runner or
- # service already running keeps the environment it launched with, so
- # give machine callers the spelling that always resolves.
- Write-Host ""
- Write-Host "driving ade from CI or an agent? Processes already running keep their old PATH:"
- Write-Host " $InstallDir\ade.exe help --json # absolute path - always resolves"
- Write-Host "then pass --json to every command: the full result is on stdout."
- } finally {
- Remove-Item -Recurse -Force $Tmp -ErrorAction SilentlyContinue
- }
scripts/install.sh · Bundled script · 197 lines · 2 findings marked
- #!/bin/sh
- # ade-cli installer for macOS / Linux.
- #
- # curl -fsSL https://raw.githubusercontent.com/landing-ai/ade-cli/main/scripts/install.sh | sh
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 4 on GitHub
- #
- # Environment knobs:
- # ADE_CLI_VERSION release to install ("0.2.0" or "v0.2.0"; default: latest)
- # ADE_CLI_INSTALL_DIR where the app lands: the binary plus its _internal/
- # support dir (default: ~/.ade/bin — inside the CLI's
- # own home, next to the store; honors ADE_HOME)
- # GITHUB_TOKEN/GH_TOKEN required while the repo is private; downloads go
- # through the GitHub API instead of the public URL.
- #
- # Uninstall: remove ~/.ade/bin (the binary and its _internal/ support dir)
- # and the ~/.local/bin/ade symlink. Never `rm -rf ~/.ade` — the rest of
- # that directory is your local store (billed parse/extract results).
- set -eu
- REPO="landing-ai/ade-cli"
- INSTALL_DIR="${ADE_CLI_INSTALL_DIR:-${ADE_HOME:-$HOME/.ade}/bin}"
- VERSION="${ADE_CLI_VERSION:-latest}"
- TOKEN="${GITHUB_TOKEN:-${GH_TOKEN:-}}"
- say() { printf '%s\n' "$*" >&2; }
- fail() { say "error: $*"; exit 1; }
- command -v curl >/dev/null 2>&1 || fail "curl is required"
- # --- pick the release asset for this platform ------------------------------
- case "$(uname -s)-$(uname -m)" in
- Darwin-arm64) target="darwin-arm64" ;;
- Darwin-x86_64) target="darwin-x86_64" ;;
- Linux-aarch64 | Linux-arm64) target="linux-arm64" ;;
- Linux-x86_64 | Linux-amd64) target="linux-x86_64" ;;
- Windows* | MINGW* | MSYS* | CYGWIN*)
- fail "use install.ps1 on Windows: irm .../install.ps1 | iex" ;;
- Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
- Line 36 on GitHub
- *)
- fail "unsupported platform: $(uname -s) $(uname -m)" ;;
- esac
- asset="ade-cli-${target}.tar.gz"
- case "$VERSION" in
- latest) tag="" ;;
- v*) tag="$VERSION" ;;
- *) tag="v$VERSION" ;;
- esac
- tmp="$(mktemp -d)"
- staging=""
- trap 'rm -rf "$tmp"; if [ -n "$staging" ]; then rm -rf "$staging"; fi' EXIT INT TERM
- # --- download ---------------------------------------------------------------
- # Anonymous installs use the public download URL; with a token we resolve
- # asset ids through the API, which also works while the repo is private.
- fetch_public() { # $1 asset name, $2 output path
- if [ -n "$tag" ]; then
- url="https://github.com/${REPO}/releases/download/${tag}/$1"
- else
- url="https://github.com/${REPO}/releases/latest/download/$1"
- fi
- curl -fsSL --retry 3 -o "$2" "$url"
- }
- # Returns non-zero (never exits) when the release or asset is unavailable:
- # callers decide what is fatal — the binary is, SHA256SUMS.txt is optional.
- release_json="" # cached across fetch_api calls
- fetch_api() { # $1 asset name, $2 output path
- if [ -z "$release_json" ]; then
- if [ -n "$tag" ]; then
- rel_url="https://api.github.com/repos/${REPO}/releases/tags/${tag}"
- else
- rel_url="https://api.github.com/repos/${REPO}/releases/latest"
- fi
- release_json="$(curl -fsSL --retry 3 -H "Authorization: Bearer ${TOKEN}" "$rel_url")" || {
- say "cannot read release ${VERSION} of ${REPO} (bad token or no release yet?)"
- release_json=""
- return 1
- }
- fi
- # Normalize the JSON to one whitespace-free token per line so the match
- # doesn't depend on GitHub's pretty-printing. Inside the "assets" array,
- # an asset's numeric id is the last "id" emitted before its "name" (the
- # guard keeps a release titled like an asset filename from matching).
- asset_id="$(printf '%s' "$release_json" | tr '{,' '\n\n' | tr -d ' \t' \
- | awk -v name="\"name\":\"$1\"" '
- /^"assets":\[/ { in_assets = 1 }
- in_assets && /^"id":[0-9]+$/ { id = substr($0, 6) }
- in_assets && index($0, name) == 1 { print id; exit }')"
- if [ -z "$asset_id" ]; then
- say "release has no asset $1"
- return 1
- fi
- curl -fsSL --retry 3 -o "$2" \
- -H "Authorization: Bearer ${TOKEN}" \
- -H "Accept: application/octet-stream" \
- "https://api.github.com/repos/${REPO}/releases/assets/${asset_id}"
- }
- fetch() {
- if [ -n "$TOKEN" ]; then fetch_api "$1" "$2"; else fetch_public "$1" "$2"; fi
- }
- say "downloading ${asset} (${VERSION}) ..."
- fetch "$asset" "$tmp/$asset" \
- || fail "download failed — while the repo is private, set GITHUB_TOKEN and retry"
- # --- verify -----------------------------------------------------------------
- if fetch "SHA256SUMS.txt" "$tmp/SHA256SUMS.txt" 2>/dev/null; then
- expected="$(grep " ${asset}\$" "$tmp/SHA256SUMS.txt" | awk '{print $1}')"
- [ -n "$expected" ] || fail "SHA256SUMS.txt has no entry for ${asset}"
- if command -v sha256sum >/dev/null 2>&1; then
- actual="$(sha256sum "$tmp/$asset" | awk '{print $1}')"
- else
- actual="$(shasum -a 256 "$tmp/$asset" | awk '{print $1}')"
- fi
- [ "$expected" = "$actual" ] || fail "checksum mismatch for ${asset}"
- say "checksum OK"
- else
- say "warning: SHA256SUMS.txt not found on the release; skipping verification"
- fi
- # --- install ----------------------------------------------------------------
- # The archive holds a onedir app: ade/ade plus ade/_internal/ with the
- # bundled libraries. A single-file binary would re-extract those to
- # fresh inodes on every launch, making macOS re-validate every code
- # signature each run (~10s per command, issue #83); the app dir pays that
- # once, right below at the warm-up run.
- tar -xzf "$tmp/$asset" -C "$tmp"
- mkdir -p "$INSTALL_DIR"
- # Stage inside the destination dir so the final steps are same-filesystem
- # renames: mv from the temp mount would degrade to copy+delete and could
- # leave a half-copied tree under a running `ade`. A concurrently
- # *launched* ade can still hit the brief window between the renames;
- # an already-running one keeps its open inodes and is unaffected.
- staging="$INSTALL_DIR/.ade.new.$$"
- cp -R "$tmp/ade" "$staging"
- chmod 755 "$staging/ade"
- rm -rf "$INSTALL_DIR/_internal" "$INSTALL_DIR/ade" "$INSTALL_DIR/ade-cli"
- mv -f "$staging/_internal" "$INSTALL_DIR/_internal"
- mv -f "$staging/ade" "$INSTALL_DIR/ade"
- rmdir "$staging"
- staging=""
- # The version call doubles as the warm-up: macOS validates each bundled
- # library once per inode, so the one slow launch happens here, not on the
- # user's first real command.
- case "$target" in
- darwin-*) say "verifying the app (first launch validates its libraries; can take ~10s) ..." ;;
- esac
- say "installed $("$INSTALL_DIR/ade" version) to ${INSTALL_DIR}/ade"
- # --- expose on PATH -----------------------------------------------------------
- # Prefer a symlink in ~/.local/bin (the XDG user bin dir, already on PATH in
- # most setups) over asking the user to edit rc files — and create the dir if
- # it is missing rather than skipping the link. Never clobber a real file
- # there: only create or refresh a symlink.
- local_bin="$HOME/.local/bin"
- link="$local_bin/ade"
- linked=0
- if [ "$INSTALL_DIR" != "$local_bin" ]; then
- if [ -e "$link" ] && [ ! -L "$link" ]; then
- say "note: $link exists and is not a symlink; leaving it untouched"
- elif mkdir -p "$local_bin" 2>/dev/null && ln -sf "$INSTALL_DIR/ade" "$link" 2>/dev/null; then
- # A link that doesn't run is not an install: prove it resolves before
- # reporting it, and withdraw it if it doesn't.
- if "$link" version >/dev/null 2>&1; then
- linked=1
- say "linked $link -> $INSTALL_DIR/ade"
- else
- rm -f "$link"
- say "note: ade would not run through $link; skipped the symlink"
- fi
- fi
- fi
- on_path() { case ":$PATH:" in *":$1:"*) return 0 ;; *) return 1 ;; esac; }
- say ""
- if on_path "$INSTALL_DIR" || { [ "$linked" -eq 1 ] && on_path "$local_bin"; }; then
- say "run: ade --help"
- else
- say "put it on PATH for this shell:"
- say " export PATH=\"$INSTALL_DIR:\$PATH\""
- say "and to keep it, append that line to your shell's rc file:"
- say " echo 'export PATH=\"$INSTALL_DIR:\$PATH\"' >> ~/.$(basename "${SHELL:-sh}")rc"
- say "then run: ade --help"
- fi
- # Printed even when the PATH check above passed: that check reads *this*
- # shell's PATH, and the shells CI jobs, cron, and agent harnesses spawn are
- # non-interactive — they source no rc file, so an rc-provided ~/.local/bin
- # is not there for them. The absolute path is the one spelling that always
- # resolves, and `help --json` is where a machine caller should start.
- say ""
- say "driving ade from CI, cron, or an agent? Those shells source no rc file:"
- say " $INSTALL_DIR/ade help --json # absolute path — always resolves"
- say " export PATH=\"$INSTALL_DIR:\$PATH\" # ...or put it on PATH first"
- say "then pass --json to every command: the full result is on stdout."
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.