Unstract CLI
The unstract CLI runs LLMWhisperer text extraction and Unstract API deployments from your terminal. Pass -o json and every command prints a single JSON envelope, so shell scripts and coding agents can drive it.
Install
uv tool install unstract-cli # or: pip install unstract-cli
unstract --help
Python 3.12+. No Python or uv on the machine? The install script fetches uv, which brings its own Python, then installs the same package:
curl -LsSf https://raw.githubusercontent.com/Zipstack/unstract-cli/main/install.sh | sh
Get your API keys
| Key | Where to get it | What it is for |
|---|---|---|
| Platform key | Settings → Platform API Keys in the Unstract UI (org admins) | Platform related operations and to identify the organization |
| Global API deployment key | Settings → Platform → Global API Deployment Keys | Runs any API deployment in the organization |
| LLMWhisperer key | The LLMWhisperer console — see LLMWhisperer API authentication | Text extraction |
A key generated from Manage Keys on an individual deployment works too, but it authenticates only that one deployment. The global key covers all of them — see API deployment authentication.
Set up
unstract auth login
A wizard asks for each product's URL (Enter keeps the cloud host; self-hosted, type your own) and each key (Enter skips one), verifies what it can, resolves your organization and writes ~/.unstract/config.toml:
default_profile = "cloud-us"
[profiles.cloud-us.docstudio]
platform_key = "..."
base_url = "https://us-central.unstract.com"
api_key = "..."
org_id = "org_ABC123"
[profiles.cloud-us.llmwhisperer]
api_key = "..."
base_url = "https://llmwhisperer-api.us-central.unstract.com/api/v2"
Run auth login again to rotate a key. Then check it:
unstract auth whoami # which organization am I in?
unstract config doctor --probe # checks the platform and LLMWhisperer keys; a deployment key is only checked when a deployment runs
Without a terminal — CI, a container, an agent — skip the wizard. Export the keys and every command resolves from the environment; no key is ever written to disk. Do not pass keys as command-line flags: they show up in the process list.
export UNSTRACT_PLATFORM_KEY=...
export UNSTRACT_DEPLOYMENT_KEY=...
export LLMWHISPERER_API_KEY=...
unstract auth whoami # resolves and stores your org_id; or export UNSTRACT_ORG_ID instead
unstract config init writes a starter file that references those variables (api_key = "env:UNSTRACT_DEPLOYMENT_KEY") instead of holding secrets, so it is safe to commit. Every setting resolves flag > environment variable > profile > built-in default.
Set up with an AI agent
Export the three keys, then paste this into Claude Code, Cursor or any coding agent:
Install and set up the Unstract CLI by following
https://docs.unstract.com/unstract/unstract_platform/cli/unstract_cli/
My keys are already in the environment as UNSTRACT_PLATFORM_KEY,
UNSTRACT_DEPLOYMENT_KEY and LLMWHISPERER_API_KEY. Never ask me to paste one
and never pass one as a command-line flag. Skip `auth login`; run
`unstract auth whoami`, then `unstract config doctor --probe`, then
`unstract --discover full` for the full command and exit-code reference.
Pass `-o json` on every command and branch on the exit code.
Extract text with LLMWhisperer
# Extract a PDF and print the text
unstract whisper extract invoice.pdf -o raw > invoice.txt
# Submit without waiting, then collect the result later
unstract whisper extract invoice.pdf --no-wait
unstract whisper status <whisper_hash>
unstract whisper retrieve <whisper_hash> --save invoice.json
extract takes a file path or a URL and waits by default. Also in the group: detail, highlights, usage, and webhook create | get | update | delete. A retrieved result is a one-shot read — pass --save <file> to keep it.
Run an API deployment
# What can I run?
unstract docstudio deployment ls
# Run a deployment and wait for the structured result
unstract docstudio deployment run invoice-parser invoice.pdf
# Longer job: poll every 10s, give up after 20 minutes
unstract docstudio deployment run invoice-parser invoice.pdf --interval 10 --timeout 1200
# Check an execution you did not wait for
unstract docstudio deployment run invoice-parser invoice.pdf --no-wait
unstract docstudio deployment status invoice-parser <execution_id>
run and status take the API name exactly as ls prints it. --wait is on by default; --interval sets how often it polls and --timeout how long before giving up — the execution keeps running on the server, and status picks it up again.
Output for scripts and agents
-o json puts exactly one {"ok", "data", "error", "meta"} envelope on stdout, success or failure, with diagnostics on stderr. -o raw prints a single field unwrapped. Failures exit non-zero with a stable code. unstract --discover full prints the whole command tree, every flag and the exit-code table as JSON.
What it does not do yet
The CLI runs what you have already built in Unstract. It cannot create API deployments and does not manage workflows, Prompt Studio projects or connectors. For the full option list on any command, use --help:
unstract whisper extract --help
unstract docstudio deployment run --help