UN-4016 [FEAT] Support a platform API key: auth whoami and deployment ls

[pk-zipstack]

What

A platform product group in the config table, and two commands that use it:

export UNSTRACT_PLATFORM_KEY=...
unstract auth whoami                    # resolves and stores org_id
unstract docstudio deployment ls        # no api_name paste
unstract docstudio deployment run invoices doc.pdf

Based on feat/cli-scaffold (#2), not main.

Why

Before this, running anything meant assembling a credential from three values in three places: org_id, a deployment key, and the deployment's api_name. org_id had no documented source at all — it is the first path segment of every web-app URL (useMainAppRoutes.jsx, <Route path=":orgName">) and nothing said so. There was no way to ask what deployments exist, so every api_name was copied by hand out of the UI.

A platform key already carries its own organisation, so supplying the key is enough to discover the rest. That is what every comparable pre-OAuth CLI does — doctl, twilio, sentry-cli all issue one opaque token that carries its scope and is validated the moment it is supplied.

How

• platform is a fourth entry in the table-driven config layer, which lights up config get/set/doctor, require()'s hints and settings_for() with no new code. It deliberately has no org_id of its own: auth whoami writes the resolved one to the docstudio block, which is where deployment URLs and aliases already read it from. Two org_id settings would mean two rows in config doctor a user has to keep in agreement by hand.
• deployment ls is a thin wrapper. PlatformClient.list_api_deployments already ships in unstract-client; this adds no transport for it. Rows are projected to five fields by default because render_table wraps rather than truncates and the server sends fifteen — --full returns them all, and the help text says so rather than truncating silently.
• auth whoami needed one new call. PlatformClient._url() always injects /{prefix}/unstract/{org}/, which is precisely the segment this call exists to discover, so CLIPlatformClient subclasses it and builds that one URL itself. That avoids an upstream release for a single method; if another consumer wants it, it moves.
• PlatformAPIError is now translated like every other client failure. Without that a rejected key reached __main__ as an uncaught exception and printed a traceback instead of exiting 3.
• config doctor --probe gains a platform branch. Its own docstring lamented having no side-effect-free endpoint to verify a key against; whoami is one. An absent platform key reports ok: null, not false — holding only a deployment key is the common case and must not decide the command's exit code.

Can this PR break any existing features

No new behaviour on any existing path. The config layer gains a product; the three existing ones are untouched, and their env vars, precedence and file layout are unchanged. clone still reads UNSTRACT_SRC_PLATFORM_KEY/UNSTRACT_TGT_PLATFORM_KEY and neither the platform block nor $UNSTRACT_PLATFORM_KEY — two orgs, so no single profile describes it.

Three exact-set assertions in the suite had to grow (--discover groups, the config command set, the deployment command set). Each is a surface addition, not a changed guarantee.

Backend dependency

Needs GET /api/v1/unstract/whoami/, added in Zipstack/unstract#2269. Until that ships, auth whoami and the config doctor --probe platform row will 404 against a deployment without it.

Notes on Testing

280 tests, offline as the rest of the suite is — the client factory is the seam, not the transport. New coverage: the arguments each command hands the client, the envelope and exit code a caller sees, that whoami writes org_id into the right profile block and that --no-save writes nothing, that a rejected key exits 3 rather than raising, and that an absent platform key leaves doctor --probe at exit 0 while a wrong one fails it.

Also exercised live against a local backend carrying #2269, with two seeded organisations: the same commands under two keys return two organisations and two deployment lists, with no org_id ever typed.

Review history

Two follow-up commits sit on top of the feature commit, each closing findings from a full pre-merge review pass:

• e224089 — the platform key was sent to the built-in cloud default rather than the host the caller named, in four places (a legacy profile, docstudio --base-url, --api-key, an explicit [platform] base_url). One resolution helper closed all four.
• 35a41f1 — three regressions the first round introduced, two of them the inverse of what they fixed: a sub-second --transport-timeout truncated to 0 and died with a traceback rather than an envelope; an explicitly-named SaaS host was discarded because the code inferred "unset" by comparing against the default; and declining to rewrite a project-local .unstract.toml exited 2 and threw the resolved identity away, on the CLI's documented first command.

Every fix is pinned by a test that fails when the fix is reverted, with one exception recorded as an equivalent mutant: reading docstudio's base_url tier with get_explicit rather than get is behaviourally identical while both default hosts are the same string, which they are by design.

Related

• UN-4016 (sub-task of UN-4008)
• UN-4016 [FEAT] Resolve the organisation from a platform API key via a whoami endpoint unstract#2269 — the whoami endpoint this consumes
• UN-4008 [FEAT] Add the unstract CLI to run extractions and API deployments from the terminal #2 — the branch this is based on

🤖 Generated with Claude Code

https://claude.ai/code/session_01K92qFRNecJ5kNkKcmJ8qkM

[greptile-apps]

Greptile Summary

The PR adds platform-key authentication, organization discovery, and API deployment listing while extending configuration and client-error handling.

• Adds auth whoami, including optional persistence of the resolved organization.
• Adds docstudio deployment ls with filtering and full-response modes.
• Adds platform configuration, probing, URL resolution, credential scrubbing, and transport error translation.
• The follow-up implementation now resolves platform and Doc Studio hosts tier-by-tier, preserving command-line precedence.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
src/unstract_cli/core/platform.py	Adds the platform client adapter and tier-aware host resolution; the follow-up resolves the previously reported command-line override failure.
src/unstract_cli/commands/platform_cmd.py	Implements organization discovery, safe persistence behavior, and platform-authenticated deployment listing.
src/unstract_cli/config.py	Adds platform settings and explicit tier iteration while preserving flag-over-environment-over-profile precedence.
src/unstract_cli/core/clients.py	Translates platform and requests-layer failures into consistent CLI error envelopes.
src/unstract_cli/commands/config_cmd.py	Extends credential probing to validate an optional platform key through the identity endpoint.
tests/test_platform.py	Covers platform URL selection, including the precedence scenario from the previous review thread.
tests/test_commands.py	Covers the new command behavior, persistence outcomes, credential errors, timeouts, and deployment listings.

Sequence Diagram

sequenceDiagram
    participant U as User
    participant CLI as Unstract CLI
    participant P as Platform API
    participant C as Config
    U->>CLI: auth whoami (platform key)
    CLI->>P: GET /api/v1/unstract/whoami/
    P-->>CLI: organization identity
    CLI->>C: Store docstudio.org_id when allowed
    CLI-->>U: Identity and save status
    U->>CLI: docstudio deployment ls
    CLI->>C: Resolve platform host, key, and org_id
    CLI->>P: List API deployments
    P-->>CLI: Deployment rows
    CLI-->>U: Projected or full listing

Loading

_{Reviews (2): Last reviewed commit: "UN-4016 [FIX] Resolve the platform host ..." | Re-trigger Greptile}