feat: Unstract CLI — unified interface for Document Studio, LLMWhisperer, and API Hub

[hari-kuriakose]

Establishes the unstract CLI — one interface over Unstract's three products (Document Studio, LLMWhisperer, API Hub), built for agent use: declarative endpoint records, machine-readable --discover, stable exit codes, structured errors, and no interactive prompts.

main is an empty root commit, so this PR's diff is the entire codebase.

Architecture

Every command is generated from a declarative Endpoint record in src/unstract_cli/endpoints/. The command tree, flags, help text, validation, and --discover all derive from those records, so help text cannot drift from behaviour and the bundled Claude Skill has exactly one place to edit.

Highlights

• Config & resolution — profiles, .unstract.toml, --config; resolution order flag → env → profile → default; config doctor reports where each setting resolves from without echoing secrets.
• --discover — a ~1k-token group map an agent drills into, rather than pulling all 156 commands into context.
• --wait — declarative execute → poll → retrieve, deciding terminal state from the response body (not the HTTP code, which the deployment API returns as 422 mid-run).
• One-shot results — --save persists them atomically before exit; a second read exits 9.

Fixes from a full end-to-end run

Driving a document through extract → Prompt Studio → export → deploy → run surfaced real friction; root causes were traced in the backend source, which changed two fixes and ruled one out:

• Exit codes never reached the shell — standalone_mode=False makes Click return the exit code, and main() discarded it, so every failure exited 0 while its envelope reported the real code. Highest-impact fix; caught only by subprocess tests, since CliRunner never runs main().
• prompt create --profile-manager — fetch_response reads the prompt's own profile and never falls back to the project default (unlike its siblings), failing with a message that names a setting it never reads.
• prompt-studio --challenge-llm — an empty challenge_llm fails an enum check at deploy time; setting it before export keeps the metadata valid.
• Param.mirror_as — the key-create routes needed the same id in both path and body; mirroring lets --api-id alone suffice.
• org_id fallback chains and --wait on index-document.
• Server-side items that can't be fixed here now have help text describing the real behaviour instead of implying a workaround.

Verification

245 tests pass; ruff and mypy clean; --discover emits valid JSON (156 commands).

🤖 Generated with Claude Code

[chandrasekharan-zipstack]

Maintenance-cost flag (for discussion). Worth being explicit about what this base path commits us to.

/api/v1/unstract/{org_id}/... is not a versioned public API — it's the same Django urlconf (backend/urls_v2.py) the React frontend calls, and v1 is just the PATH_PREFIX env-var string. No version negotiation, no deprecation policy, and no published OpenAPI schema (drf-yasg is installed but doesn't serve JSON and isn't mounted in the tenant urlconf). So all 125 platform records are hand-encoded against routes that can move in any normal feature PR — workflow/endpoint/ already shows a land→revert→re-land in git history — and there's nothing to CI-check them against.

Highest-leverage fix: publish a real OpenAPI schema from the backend (add drf-spectacular, mount it inside the tenant urlconf, commit the generated openapi.json). That one change makes drift-detection mechanical, lets CI gate path changes, and opens the door to generating these records instead of hand-maintaining them.

Cheaper interim step: a backend CI job that diffs ALL_ENDPOINTS against django.urls.get_resolver() — ~30 lines, catches renamed/removed routes immediately.

[chandrasekharan-zipstack]

Follow-up — how this is trending in 2026, and the tooling that removes the hand-maintenance entirely.

If/when the backend publishes an OpenAPI schema (the suggestion above), this whole registry becomes generated rather than hand-written. Several vendors now generate a full agent-friendly CLI straight from a spec — typed subcommands, --help as JSON, pre-flight validation, dry-run — i.e. exactly the feature list this PR built by hand:

• Fern — https://buildwithfern.com/post/generate-cli-from-openapi-spec
• Speakeasy — https://www.speakeasy.com/docs/cli-generation/create-cli
• Stainless — https://www.stainless.com/blog/stainless-cli-generator-your-api-now-with---help/
• Vercel specli (run an OpenAPI spec as an agent-optimized executable) — https://github.com/vercel-labs/specli

The broader pattern these have converged on for agent-facing CLIs, and where we stand:

1. Generate from the spec, don't hand-write — the single biggest divergence here; we built by hand only because there's no schema to generate from yet.
2. Machine-readable discovery + stable exit codes + JSON errors — this PR already nails this (--discover, exit 2/7/9, error envelopes). Speakeasy goes one further with an agent mode that auto-detects Claude Code / Cursor / Codex / Copilot from the environment and adjusts output — cheap to steal.
3. Ship a skill / AGENTS.md with the CLI — also already done here (bundled update-unstract-cli skill). Ahead of the curve.
4. CLI and MCP, not either/or — CLI for shell-outable/composable work, MCP for OAuth / audit / multi-tenant / hosted access. The MCP arm is already in flight (feat(mcp): host deployment-scoped and organization-scoped MCP servers unstract#2207), so the hybrid is on track — the one thing to keep aligned is which operations are canonical across the CLI registry and the MCP tool set so coverage doesn't silently diverge.

Net: architecture and agent-ergonomics here are ahead of most vendor CLIs. The schema is the piece that turns items in (1) from maintenance into generation.

[chandrasekharan-zipstack]

Binary-name collision — needs an action before publishing. This registers a console script named unstract, but the already-published unstract-client package registers the same name (unstract = "unstract.cli:main", https://github.com/Zipstack/unstract-python-client/blob/main/pyproject.toml), and it already ships a working unstract clone subcommand. Installing both in one env → one silently shadows the other. Flagging so we decide how to handle before PyPI publish (not proposing a fix here).

[chandrasekharan-zipstack]

Blocker: --base-url / --org-id are silent no-ops on all 131 Document Studio commands. The override is stored keyed by product (docstudio.base_url) here, but build_url reads it by API group — config.get(endpoint.api, ...) → platform.base_url (http.py:135). The keys never match, so it falls through to DEFAULT_BASE_URLS["platform"]. An on-prem/EU user passing --base-url sends their platform key + documents to us-central.unstract.com. Works on whisper/apihub only because there product == api group.

The one covering test (test_cli.py:156) passes a --base-url value identical to the default, so it passes whether or not the flag works. Fix: key overrides by endpoint.api.value.

[chandrasekharan-zipstack]

Blocker (security): project-config discovery is a credential-exfiltration vector. This searches upward from cwd for .unstract.toml ahead of the user's XDG config, with no trust check and no diagnostic naming the file. Combined with env:VAR indirection, a repo-committed .unstract.toml can set base_url to an attacker host and api_key = "env:AWS_SECRET_ACCESS_KEY"; the next unstract run inside that tree ships the env var as a Bearer token to the attacker. Agent sandboxes cd into untrusted checkouts routinely.

Fix: refuse base_url/api_key from project-level files (or make project discovery opt-in), and always print the resolved config path to stderr.

[chandrasekharan-zipstack]

Blocker (data loss): whisper extract advertises --save but never defines it. This endpoint is poll.one_shot=True, so generate.py:222 prints "ONE-SHOT: … Use --save to persist it" and errors.py:268 repeats it on exit 9 — but _EXTRACT_PARAMS has no save param, so whisper extract --wait --save out.json → Error: No such option '--save'. The extracted text is one-shot and unrecoverable. It's the only one_shot endpoint missing save (deployment.run has it).

Fix: add Param("save", client_side=True, ...); add a test asserting every one_shot endpoint exposes --save.

[chandrasekharan-zipstack]

Blocker: workflow execute --file silently drops the entire JSON body. This record is body=BodyKind.JSON but files is ParamLocation.FORM. build_request populates both json= and files=, and httpx sends only files — so workflow_id (required) never reaches the wire, and --dry-run prints the body that gets discarded.

Fix: make this record MULTIPART with all fields FORM, and have build_request raise if more than one body channel is populated rather than letting httpx silently pick one.

[chandrasekharan-zipstack]

Blocker (data loss): a successful result can be destroyed as "already consumed". _looks_consumed substring-matches payload["message"] on every response, before the status check. But for deployment status the message field is the result (per the PollSpec note in deployment.py), so a 200 whose result text happens to contain e.g. "already delivered" raises exit 9 and drops the payload.

Fix: gate this on response.status >= 400 and require message to be a plain string. (Related: poll.py:118 discards response.payload on every non-terminal poll — retain last_payload so an unrecognised terminal status on a one-shot store isn't lost.)

[chandrasekharan-zipstack]

Non-idempotent POSTs are retried. execute() accepts this endpoint param but never reads it; transport errors and 5xx are retried for every method, so a read timeout on deployment run / whisper extract re-uploads the document up to 4× → duplicate executions and billing. The docstring only disclaims 4xx. Fix: use the endpoint you already have — force max_retries=0 for one-shot/POST, or retry transport errors only for GET/HEAD.

[chandrasekharan-zipstack]

Retry-After is honoured with no cap. Retry-After: 3600 → CLI sleeps an hour per attempt, silently and uninterruptibly; under --wait an agent just sees a hang. Fix: clamp to a ceiling (~60s) and to the remaining --wait-timeout budget, and emit a diagnostic on each retry.

[chandrasekharan-zipstack]

Path params are interpolated without percent-encoding. --api-name '../../../v1/admin' traverses; --api-name 'x?a=b' injects a query string. Fix: urllib.parse.quote(value, safe=""), with an explicit exemption for share --resource whose enum values intentionally span path segments.

[chandrasekharan-zipstack]

--dry-run output isn't scrubbed with plan.secrets. plan.describe() redacts only by header/key name; plan.secrets (populated for exactly this) is used only on the error path. FORM-located JSON params are re-serialised to a string out of redact_value's reach, so deployment run --custom-data '{"api_key":"sk-…"}' prints the key verbatim while the same JSON in a BODY param is redacted. Fix: scrub(render(...), plan.secrets) before emitting.

[chandrasekharan-zipstack]

config doctor can't be a CI gate, and _probe leaks the key. doctor always exits 0 even when every credential is unresolved / every live check fails. And this except Exception returns str(exc) unscrubbed to stdout (e.g. "upstream rejected key SUPERSECRET…") while every other error path calls scrub(). Fix: exit non-zero when a probed group fails or a required api_key is unresolved; scrub(str(exc), collect_secrets(...)) and narrow the catch.

[chandrasekharan-zipstack]

Non-Click exceptions bypass the structured-error contract. Only Click exceptions are caught here; a KeyError from a bad PollSpec name (get_endpoint) or a yaml.safe_dump on bytes exits with a bare traceback and no JSON envelope — breaking the guarantee advertised to agents in app.py:396. Fix: add a final except Exception emitting a GENERIC CLIError envelope.

[chandrasekharan-zipstack]

Concurrency hazards for parallel agents. (1) --save writes a deterministic .{name}.partial temp file at default umask — two agents saving to one path corrupt each other, and the file lands 0644 while the config path goes to lengths for 0600. Use tempfile.mkstemp(dir=path.parent) + os.replace + chmod 600. (2) config set (loader.py:215) is a non-atomic O_TRUNC read-modify-write with no lock, and rebuilds the doc from known keys only — it silently drops any top-level table it doesn't recognise. Use temp-file + os.replace and preserve unknown keys.

[chandrasekharan-zipstack]

no_trailing_slash=True is wrong for this route. The backend router is DefaultRouter(trailing_slash=True) (tenant_account_v2/groups_urls.py), so this DELETE requires the slash; it only works today because follow_redirects=True follows Django's APPEND_SLASH 301 (extra round-trip, breaks if redirects are ever disabled). The module docstring's claim that these paths "genuinely have none" is false for this one — the other nine no_trailing_slash records verified correct against the live URL resolver. Fix: drop no_trailing_slash=True here.

[chandrasekharan-zipstack]

Nit (tests + comments, batched to keep noise down).

Tests: coverage is 88% but ~11/20 targeted mutations survive — the endpoint records and config-resolution are largely asserted against themselves (changing a record's path, deleting the require_response_fields guard, or swapping env/profile precedence all keep the suite green). Highest-value adds: a --dry-run smoke test walking every endpoint (assert URL has no unsubstituted {...} + auth header present — would have caught the --base-url blocker); a precedence test for flag>env>profile>default; and actually running the docdiff drift suite in CI (those 4 tests are the only drift protection and currently skip because CI checks out only this repo). Also uv run pytest fails on a fresh checkout (ModuleNotFoundError: tomli_w) — needs --extra dev; README:263 documents the bare command that doesn't work.

Comments: ~57 citations to GOTCHAS #N / CAPTURE2 … / BUG N / DOC N — none of those files exist in the repo, and 19 render into user-facing --help. Either commit those docs or inline the fact at the use-site (as was already done well for the P1–P12 table). Also RequiredUnless (model.py:179) docstrings a "live case" that doesn't exist and is unused in src/; and platform.py:142 says "Verified this session". The load-bearing defect comments (poll.py:6, http.py:428) are genuinely good — keep them, just reword "currently returns X" → "insensitive to X" so they don't rot once the backend is fixed.