unstract-cli 0.1.0__tar.gz

unstract_cli-0.1.0/.claude/skills/bump-client-pins/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: bump-client-pins
+description: Bump the exact `unstract-client` / `llmwhisperer-client` pins, re-sync the vendored specs to match, and cut a CLI release. Use whenever a new version of either client is released, when `tests/test_specs.py` or `tests/test_contract.py` fails, when the CLI is missing a flag for an endpoint the API already has, or when someone asks to "bump the client", "update the pins", "refresh the specs", or "release the CLI". Reach for this even when the request sounds like a plain dependency bump — the pins, the vendored specs and `provenance.json` have to move together or the CLI derives flags the pinned client cannot carry.
+---
+
+# Bumping the client pins
+
+The CLI derives its flags and help text from two published clients and from
+vendored copies of the specs those clients were generated from. That makes a pin
+bump three coupled edits, not one: the pin, the spec, and the provenance record.
+Move one without the others and the tests say so — which is the point of them.
+
+## The pieces
+
+| Thing | Where |
+|---|---|
+| Exact pins | `pyproject.toml`, `[project].dependencies` |
+| Vendored specs | `src/unstract_cli/specs/{docstudio,llmwhisperer}.json` |
+| Provenance | `src/unstract_cli/specs/provenance.json` (client pin, upstream repo, commit, sha256) |
+| Coherence tests | `tests/test_specs.py`, `tests/test_contract.py`, `tests/derived_flags.json` |
+| Release | `.github/workflows/release.yml`, `workflow_dispatch` |
+
+`src/unstract_cli/specs/README.md` explains the vendoring rule in place; read it
+if any of the below is unclear.
+
+## The sequence
+
+1. **Move the pins** in `pyproject.toml` to the released versions you are
+   upgrading to. They are exact (`==`) on purpose: the CLI's published surface is
+   derived from these clients, so a client that moves reshapes the CLI.
+
+2. **Relock:** `uv lock` then `uv sync --extra dev --python 3.12`. CI installs
+   from `uv.lock`, not from a fresh resolve, so a lockfile left behind means the
+   gate tests a dependency set nobody ships.
+
+3. **Re-sync each vendored spec from the commit the pinned client was generated
+   from.** The chain is: the client repo's release tag → its `tools/gen_sdk.sh`,
+   which records the upstream service repo, path and revision the spec was copied
+   from → the spec file committed in that client at that tag. Copy that file here
+   byte-for-byte. Copying from anywhere else — upstream `main`, a newer service
+   commit — is what `tests/test_contract.py` guards: a spec parameter the pinned
+   client has no argument for cannot become a flag.
+
+4. **Update `provenance.json`** for each spec you moved. Set `client` to the
+   exact pin you wrote in `pyproject.toml` (`unstract-client==X.Y.Z`); the
+   tests compare the two, so a pin moved without its spec fails here. Check
+   `repo`, `path` and `commit` against what that client's `tools/gen_sdk.sh`
+   records, because an upstream that moved its spec file leaves `repo` and
+   `path` stale and the tests cannot see it: they check the pin, the `sha256`
+   and the entry names, nothing about where the file came from. The `sha256`
+   is of the file you just wrote (`sha256sum src/unstract_cli/specs/<file>`).
+   This record is what lets the next person tell a current copy from a stale
+   one.
+
+5. **Run the tests:** `uv run pytest -q`.
+
+   - `test_specs.py` fails if a vendored file stops matching its recorded
+     sha256, if its `client` no longer equals the pin in `pyproject.toml`, or if
+     a spec has no provenance entry. It is the cheap check that steps 1, 3 and
+     4 actually agree.
+   - `test_contract.py` fails if a spec parameter the pinned client cannot accept
+     would have become a flag, and separately if the derived flags stop matching
+     `tests/derived_flags.json`.
+
+6. **If `derived_flags.json` fails, read the difference before refreshing it.**
+   The failure names the flags that moved. A flag missing from the new set is a
+   flag the CLI has stopped offering; a narrowed choice or changed type is a value
+   the CLI used to take and now rejects. Once you have decided the change is
+   intended, refresh it deliberately:
+
+   ```bash
+   UNSTRACT_CLI_REFRESH_FLAG_SNAPSHOT=1 uv run pytest -q tests/test_contract.py
+   ```
+
+   and commit the snapshot in the same PR, so the diff shows what the CLI's
+   surface gained or lost.
+
+7. **Lint:** `uv run ruff check . && uv run ruff format --check .` — the release
+   run repeats exactly this, so a failure here is a failure there.
+
+## Versioning and release
+
+Choose the bump by what changed for CLI users: **minor** for new or changed
+flags and commands, **patch** for fixes that leave the surface identical.
+
+Do not bump `__version__` in `src/unstract_cli/__init__.py` in your PR. The
+in-repo value names the last released version; `release.yml` reads it, applies
+the bump chosen at dispatch and commits the result itself.
+
+Release by dispatching **Release Tag and Publish Package** on `main`:
+
+- `version_bump: none` publishes the version already in the repo — what the
+  first release of a version needs.
+- `pre_release: true` publishes `<next-version>rcN` and deliberately leaves the
+  committed version alone, counting N up from the rc tags already published for
+  that target. To promote to stable, dispatch again with it off **and the same
+  `version_bump`**: the workflow recomputes the target from that input every
+  time, so a different bump publishes a different version than the one the rc
+  tested.
+- It publishes to PyPI **before** it tags and releases, because publishing is the
+  only step that cannot be undone: a failure before it leaves nothing to
+  unpublish, and one after it is retried by hand against a live artifact.
+
+## Upstream
+
+If a client pin is missing an endpoint the service already offers, the fix is in
+that client, not here — see the `spec-upgrade` skill in `unstract-python-client`
+and `llm-whisperer-python-client`. Bump the pin here once it is released.

unstract_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,74 @@
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  # Offline by design: no network, no credentials, sub-second. Live round trips
+  # are a manual pre-release step, not a per-PR gate.
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.6.14"
+          enable-cache: true
+      # Synced from uv.lock rather than resolved fresh, so the gate tests the
+      # dependency set an install actually gets.
+      - run: uv sync --extra dev --python 3.12
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pytest -q
+      # `uv run` resolves from uv.lock, whose click sits in the middle of the
+      # range the pin allows. Both ends are what an install in the wild gets --
+      # the floor exactly, not the newest release that satisfies it -- and
+      # discovery is a published contract read out of Click's own objects, so
+      # both ends are run and their answers compared.
+      - run: uv pip install 'click==8.1.0'
+      - run: .venv/bin/python -m pytest -q
+      - run: .venv/bin/python -m unstract_cli -o json --discover full > floor.json
+      - run: uv pip install -U 'click>=8.1,<9'
+      - run: .venv/bin/python -m pytest -q
+      - run: .venv/bin/python -m unstract_cli -o json --discover full > latest.json
+      - run: diff floor.json latest.json
+
+  # The wheel rather than the checkout: packaging and entry points are declared
+  # in `pyproject.toml` and are not exercised by running the tests in place.
+  package:
+    runs-on: ubuntu-latest
+    env:
+      VIRTUAL_ENV: /tmp/smoke
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.6.14"
+          enable-cache: true
+      - run: uv build --out-dir dist
+      - run: uv venv --python 3.12 /tmp/smoke
+      - run: uv pip install dist/*.whl
+      - name: Both entry points answer
+        run: |
+          /tmp/smoke/bin/unstract --version
+          /tmp/smoke/bin/unstract-cli --version
+          /tmp/smoke/bin/unstract --help > /dev/null
+      - name: The published surfaces render from an installed wheel
+        run: |
+          /tmp/smoke/bin/unstract -o json --discover full > discover.json
+          python -c "import json; d = json.load(open('discover.json')); assert d['ok'] and d['data']['commands']"
+          # A usage error still renders the envelope and still exits 2.
+          set +e
+          /tmp/smoke/bin/unstract -o json whisper status > usage.json
+          code=$?
+          set -e
+          test "$code" = "2"
+          python -c "import json; d = json.load(open('usage.json')); assert d['ok'] is False and d['error']['exit_code'] == 2"
+      - name: A fresh install can write its own config
+        env:
+          UNSTRACT_CONFIG: /tmp/smoke-config.toml
+        run: |
+          /tmp/smoke/bin/unstract config init < /dev/null
+          test -s /tmp/smoke-config.toml

unstract_cli-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,226 @@
+name: Release Tag and Publish Package
+
+on:
+  workflow_dispatch:
+    inputs:
+      version_bump:
+        description: "Version bump type."
+        required: true
+        default: "patch"
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+      pre_release:
+        description: "Publish a release candidate (`<version>rcN`) instead of the version itself. Dispatch again with the same bump and this off to promote it to stable."
+        required: false
+        default: false
+        type: boolean
+      release_notes:
+        description: "Release notes (optional)"
+        required: false
+        type: string
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release-and-publish:
+    runs-on: ubuntu-latest
+    # Dispatchable from any branch by anyone who can dispatch it, and a
+    # candidate reaches PyPI without a commit to review: the published artefact
+    # must come from the reviewed branch.
+    if: github.ref == 'refs/heads/main'
+    permissions:
+      contents: write
+      # Publishing is by PyPI Trusted Publisher, so there is no API token.
+      id-token: write
+    steps:
+      # Checked before the checkout, so a missing one fails on the reason
+      # rather than on a token that renders empty three steps later.
+      - name: Check the release credentials are visible to this repository
+        env:
+          APP_CLIENT_ID: ${{ vars.PUSH_TO_MAIN_APP_CLIENT_ID }}
+          APP_PRIVATE_KEY: ${{ secrets.PUSH_TO_MAIN_APP_PRIVATE_KEY }}
+        run: |
+          missing=""
+          [ -n "$APP_CLIENT_ID" ] || missing="$missing vars.PUSH_TO_MAIN_APP_CLIENT_ID"
+          [ -n "$APP_PRIVATE_KEY" ] || missing="$missing secrets.PUSH_TO_MAIN_APP_PRIVATE_KEY"
+          if [ -n "$missing" ]; then
+            echo "Missing:$missing" >&2
+            echo "An organisation-level variable or secret also has to list this repository." >&2
+            exit 1
+          fi
+
+      - name: Generate GitHub App Token
+        id: generate-token
+        uses: actions/create-github-app-token@v3
+        with:
+          client-id: ${{ vars.PUSH_TO_MAIN_APP_CLIENT_ID }}
+          private-key: ${{ secrets.PUSH_TO_MAIN_APP_PRIVATE_KEY }}
+          owner: Zipstack
+          repositories: |
+            unstract-cli
+
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ steps.generate-token.outputs.token }}
+          fetch-depth: 0
+
+      - name: Configure Git
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.6.14"
+          enable-cache: true
+
+      # The same install as ci.yml, so what the release run lints and tests is
+      # what the PR gate lints and tests.
+      - run: uv sync --extra dev --python 3.12
+
+      # Staged locally only: nothing is committed, tagged or released until the
+      # checks and the build have passed, so a failure leaves main untouched.
+      - name: Compute new version
+        id: version
+        run: |
+          VERSION_FILE=src/unstract_cli/__init__.py
+          CURRENT_VERSION=$(sed -nE 's/^__version__ = "(.*)"/\1/p' "$VERSION_FILE")
+          echo "Current version: $CURRENT_VERSION"
+
+          IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT_VERSION"
+          case "${{ github.event.inputs.version_bump }}" in
+            major) MAJOR=$((MAJOR + 1)); MINOR=0; PATCH=0 ;;
+            minor) MINOR=$((MINOR + 1)); PATCH=0 ;;
+            patch) PATCH=$((PATCH + 1)) ;;
+          esac
+          NEXT_VERSION="$MAJOR.$MINOR.$PATCH"
+
+          # A pre-release is a candidate for NEXT_VERSION, not a version of its
+          # own, so it never moves the committed one: the file keeps naming the
+          # last stable release, and repeat dispatches count up from the rc tags
+          # already published for that target.
+          if [ "${{ github.event.inputs.pre_release }}" = "true" ]; then
+            HIGHEST_RC=$(git tag -l "v${NEXT_VERSION}rc*" \
+              | sed -nE "s/^v${NEXT_VERSION}rc([0-9]+)$/\1/p" | sort -n | tail -1)
+            NEW_VERSION="${NEXT_VERSION}rc$(( ${HIGHEST_RC:-0} + 1 ))"
+          else
+            NEW_VERSION="$NEXT_VERSION"
+          fi
+
+          echo "New version: $NEW_VERSION"
+          echo "version=$NEW_VERSION" >> "$GITHUB_OUTPUT"
+
+          sed -i "s/^__version__ = \".*\"/__version__ = \"$NEW_VERSION\"/" "$VERSION_FILE"
+
+          if git rev-parse -q --verify "refs/tags/v$NEW_VERSION" >/dev/null; then
+            echo "Tag v$NEW_VERSION already exists. Exiting..."
+            exit 1
+          fi
+
+      - name: Verify version update
+        run: |
+          BUILT_VERSION=$(uv run python -c "import unstract_cli; print(unstract_cli.__version__)")
+          echo "Package version: $BUILT_VERSION"
+          echo "Target version: ${{ steps.version.outputs.version }}"
+          if [ "$BUILT_VERSION" != "${{ steps.version.outputs.version }}" ]; then
+            echo "Version mismatch! Exiting..."
+            exit 1
+          fi
+
+      - name: Run linting
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+
+      - name: Run tests
+        run: uv run pytest -q
+
+      - name: Build package
+        run: uv build
+
+      # Publishing is the one step that cannot be undone, so it runs last, and
+      # the release is created as a draft so a publish that fails leaves
+      # nothing public. Until then the bump commit exists only in the tag, so
+      # a failed publish leaves main untouched.
+      - name: Commit version bump and create draft release
+        env:
+          RELEASE_NOTES: ${{ github.event.inputs.release_notes }}
+          GITHUB_TOKEN: ${{ steps.generate-token.outputs.token }}
+        run: |
+          NEW_VERSION="${{ steps.version.outputs.version }}"
+
+          # A pre-release leaves the committed version alone.
+          if [ "${{ github.event.inputs.pre_release }}" = "true" ]; then
+            git checkout -- src/unstract_cli/__init__.py
+          elif ! git diff --quiet; then
+            git add src/unstract_cli/__init__.py
+            git commit -m "chore: bump version to $NEW_VERSION [skip ci]"
+          fi
+
+          git tag "v$NEW_VERSION"
+          git push origin "v$NEW_VERSION"
+
+          if [ -z "$RELEASE_NOTES" ]; then
+            gh release create "v$NEW_VERSION" \
+              --title "Release v$NEW_VERSION" \
+              --generate-notes \
+              --draft \
+              ${{ github.event.inputs.pre_release == 'true' && '--prerelease' || '' }}
+          else
+            gh release create "v$NEW_VERSION" \
+              --title "Release v$NEW_VERSION" \
+              --notes "$RELEASE_NOTES" \
+              --generate-notes \
+              --draft \
+              ${{ github.event.inputs.pre_release == 'true' && '--prerelease' || '' }}
+          fi
+
+          echo "Created draft release v$NEW_VERSION"
+
+      - name: Publish to PyPI
+        run: uv publish
+
+      # Everything the run created before the publish, so a rerun after the
+      # cause is fixed starts clean rather than on the tag guard. Each removal
+      # tolerates its target being absent: the failure may have come partway
+      # through creating them.
+      - name: Remove the tag and draft release a failed publish leaves behind
+        if: failure() && steps.version.outcome == 'success'
+        env:
+          GITHUB_TOKEN: ${{ steps.generate-token.outputs.token }}
+        run: |
+          NEW_VERSION="${{ steps.version.outputs.version }}"
+          # The wheel and the sdist upload separately, so a failed publish can
+          # still have put the version on PyPI; then the tag has to stay.
+          if curl -fsS -o /dev/null "https://pypi.org/pypi/unstract-cli/$NEW_VERSION/json"; then
+            echo "PyPI serves $NEW_VERSION; keeping the tag and draft release." >&2
+            exit 0
+          fi
+          gh release delete "v$NEW_VERSION" --yes || true
+          git push origin ":refs/tags/v$NEW_VERSION" || true
+
+      # If this fails the published version is on PyPI and in the tag but not
+      # on main; `git push origin v<version>:main` finishes the job by hand.
+      - name: Push version bump
+        if: github.event.inputs.pre_release != 'true'
+        run: git push origin main
+
+      - name: Publish release
+        env:
+          GITHUB_TOKEN: ${{ steps.generate-token.outputs.token }}
+        run: gh release edit "v${{ steps.version.outputs.version }}" --draft=false
+
+      - name: Success message
+        run: |
+          echo "Published ${{ steps.version.outputs.version }} to PyPI with uv publish using Trusted Publishers"
+          echo "Release: https://github.com/${{ github.repository }}/releases/tag/v${{ steps.version.outputs.version }}"
+          echo "PyPI: https://pypi.org/project/unstract-cli/${{ steps.version.outputs.version }}/"

unstract_cli-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+.coverage
+.coverage.*
+htmlcov/

unstract_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zipstack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

unstract_cli-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.5
+Name: unstract-cli
+Version: 0.1.0
+Summary: Unified, LLM-friendly CLI for the Unstract suite of products
+Project-URL: Homepage, https://unstract.com
+Project-URL: Documentation, https://docs.unstract.com/unstract/unstract_platform/cli/unstract_cli/
+Project-URL: Repository, https://github.com/Zipstack/unstract-cli
+Project-URL: Issues, https://github.com/Zipstack/unstract-cli/issues
+Project-URL: Changelog, https://github.com/Zipstack/unstract-cli/releases
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: click<9,>=8.1
+Requires-Dist: llmwhisperer-client==2.9.0
+Requires-Dist: requests>=2.32.3
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: unstract-client==1.7.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# unstract-cli
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/unstract-cli)](https://pypi.org/project/unstract-cli/)
+[![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2FZipstack%2Funstract-cli%2Fmain%2Fpyproject.toml)
+](https://pypi.org/project/unstract-cli/)
+[![PyPI - Version](https://img.shields.io/pypi/v/unstract-cli)](https://pypi.org/project/unstract-cli/)
+
+`unstract` runs [LLMWhisperer](https://docs.unstract.com/llmwhisperer/) text
+extraction and [Unstract](https://docs.unstract.com/unstract/) API deployments
+from the terminal. Pass `-o json` and every command prints one JSON envelope, so a
+shell script or a coding agent can drive it.
+
+Full reference: <https://docs.unstract.com/unstract/unstract_platform/cli/unstract_cli/>
+
+## Install
+
+```bash
+curl -LsSf https://raw.githubusercontent.com/Zipstack/unstract-cli/main/install.sh | sh
+```
+
+The installer fetches [`uv`](https://docs.astral.sh/uv/) if it is missing and
+installs the CLI with it; `uv` brings its own Python. With `uv` or `pip`
+already there:
+
+```bash
+uv tool install unstract-cli   # or: pip install unstract-cli
+unstract --version
+```
+
+## Get your keys
+
+| Key | Where it is minted | What it does |
+| --- | --- | --- |
+| **Platform key** | An organisation admin, under **Settings → Platform API Keys** in the Unstract UI | Platform related operations and to identify the organization |
+| **Deployment key** | The API deployment's own page in the Unstract UI or an organisation admin mints one under **Settings → Global API Deployment Keys** | Runs deployments (`deployment run`, `deployment status`) |
+| **LLMWhisperer key** | The LLMWhisperer console | Extracts text (`whisper …`) |
+
+## Set up
+
+```bash
+unstract auth login
+```
+
+A wizard asks for each product's URL (Enter keeps the cloud host; self-hosted,
+type your own) and API keys, then writes `~/.unstract/config.toml`. Then verify:
+
+```bash
+unstract auth whoami             # which organisation the platform key belongs to
+unstract config doctor --probe   # where each setting resolved from, keys checked
+```
+
+## Usage
+
+```bash
+# Extract text from a document (path or URL); waits for the result
+unstract whisper extract invoice.pdf -o raw > invoice.txt
+
+# What deployments can I run?
+unstract docstudio deployment ls
+
+# Run one and wait for the structured result
+unstract docstudio deployment run invoice-parser invoice.pdf
+
+# Long job: submit, then check later
+unstract docstudio deployment run invoice-parser invoice.pdf --no-wait
+unstract docstudio deployment status invoice-parser <execution_id>
+```
+
+`--help` on any command lists its options; `unstract --discover full` prints
+the whole command tree, every flag and the exit-code table as JSON.
+
+## Configuration
+
+`~/.unstract/config.toml`, or `$UNSTRACT_CONFIG`, or `--config`, or a
+project-local `.unstract.toml` is found by upward search. Here's an example config that uses environment variables for the API keys.
+
+```toml
+default_profile = "cloud-us"
+
+[profiles.cloud-us.docstudio]
+base_url = "https://us-central.unstract.com"
+org_id = "org_ABC123"
+platform_key = "env:UNSTRACT_PLATFORM_KEY"
+api_key = "env:UNSTRACT_DEPLOYMENT_KEY"
+
+[profiles.cloud-us.llmwhisperer]
+base_url = "https://llmwhisperer-api.us-central.unstract.com/api/v2"
+api_key = "env:LLMWHISPERER_API_KEY"
+
+# Only for a deployment whose key differs from the profile's.
+[profiles.cloud-us.deployments."invoice-parser"]
+api_key = "env:INVOICE_PARSER_KEY"
+```
+
+Every setting resolves **flag > environment > profile > built-in default**.
+`auth login` writes keys literally; `env:VAR_NAME` keeps them out of the file.
+The connection flags on each group (`--base-url`, `--api-key`, `--org-id`,
+`--platform-key`) override the profile for one invocation without writing
+anything. `config doctor` reports where each setting resolved from without
+echoing a value, and exits non-zero when one of its checks fails.
+
+### Environment variables
+
+The same settings without a file, for CI, containers and agents:
+
+```bash
+export UNSTRACT_PLATFORM_KEY=...      # auth whoami, deployment ls
+export UNSTRACT_DEPLOYMENT_KEY=...    # deployment run / status
+export UNSTRACT_ORG_ID=...            # the organisation id auth whoami reports
+export LLMWHISPERER_API_KEY=...       # whisper …
+export UNSTRACT_BASE_URL=...          # self-hosted only
+export LLMWHISPERER_BASE_URL=...      # self-hosted only
+```
+
+`auth login` also takes each key as a flag (`--platform-key`, `--deployment-key`,
+`--llmwhisperer-key`; `-` reads it from stdin) and the host as `--base-url`, so
+it runs without a terminal too.
+
+## Output for scripts and agents
+
+**Parsing anything? Pass `-o json`.** stdout then carries exactly one envelope,
+on success and on failure alike, and diagnostics go to stderr:
+
+```json
+{"ok": true, "data": {...}, "error": null, "meta": {"contract_version": 1}}
+```
+
+Ignore fields you do not recognise; refuse a `meta.contract_version` above the
+one you were written against. `-o raw` prints one field unwrapped. When a
+coding agent is driving (detected from the environment it sets) json is the
+default; `--agent yes|no` forces that, and an explicit `-o` wins over both.
+
+Failures exit non-zero with a stable code:
+
+| Code | Meaning |
+|------|---------|
+| 0 | success |
+| 1 | generic failure |
+| 2 | usage error |
+| 3 | authentication failed |
+| 4 | not found |
+| 5 | validation failed, including a run in which a document failed |
+| 6 | rate limited |
+| 7 | timed out; resume with the job handle in the error payload, do not resubmit |
+| 8 | server error |
+| 9 | result already consumed (one-shot read); pass `--save` next time |
+| 10 | result read but not saved; it is in `error.details` |
+| 130 | interrupted (128 + SIGINT) — the user stopped it, not a failure |
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run ruff check .
+```
+
+## Questions and Feedback
+
+On Slack, [join great conversations](https://join-slack.unstract.com/) around LLMs, their ecosystem and leveraging them to automate the previously unautomatable!
+
+[Unstract Cloud](https://unstract.com/): Signup and Try!