unstract-cli 0.1.0rc1__tar.gz

unstract_cli-0.1.0rc1/.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.0rc1/.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.0rc1/.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.0rc1/.gitignore

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

unstract_cli-0.1.0rc1/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.5
+Name: unstract-cli
+Version: 0.1.0rc1
+Summary: Unified, LLM-friendly CLI for the Unstract suite of products
+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
+
+`unstract` — one CLI for the Unstract suite: extract a document with
+LLMWhisperer, run it through a Document Studio API deployment, get structured
+JSON back. It also clones one organization's resources into another.
+
+```bash
+curl -LsSf https://raw.githubusercontent.com/Zipstack/unstract-cli/main/install.sh | sh
+unstract auth login                   # asks for your keys, checks them, stores them
+unstract docstudio deployment ls      # what can I run?
+```
+
+For an agent or CI, no prompts and no file — the environment is the profile:
+
+```bash
+export UNSTRACT_ORG_ID=... UNSTRACT_DEPLOYMENT_KEY=... LLMWHISPERER_API_KEY=...
+unstract -o json whisper extract ./doc.pdf
+unstract -o json docstudio deployment run invoice-parser ./doc.pdf
+```
+
+The installer fetches `uv` if it is missing and installs the CLI with it; `uv`
+brings its own Python, so nothing on the machine has to match. Already have
+`uv`? `uv tool install git+https://github.com/Zipstack/unstract-cli` is the same
+thing. Set `UNSTRACT_CLI_SOURCE` to install a branch or a local checkout
+instead.
+
+Or run it without installing: `uvx --from git+https://github.com/Zipstack/unstract-cli unstract --discover groups`.
+
+## Output
+
+`unstract` prints a table by default — in a terminal and in a pipe alike, so
+what you see while trying something is what a script sees running it.
+
+**Parsing anything? Pass `-o json`.** stdout then carries exactly one envelope,
+on success and on failure alike:
+
+```json
+{"ok": true, "data": {...}, "error": null, "meta": {"contract_version": 1}}
+```
+
+`-o json` output depends on nothing but the command and its arguments — not the
+terminal, not the config, not the environment. `-o raw` prints one field
+unwrapped, for piping a document's text somewhere else. Diagnostics, warnings
+and progress always go to stderr.
+
+Consuming the JSON: ignore fields you do not recognise, and refuse a
+`meta.contract_version` above the one you were written against. `unstract
+--discover full` publishes the whole contract alongside every command and flag.
+
+If a coding agent is driving (detected from the environment it sets), the
+*default* becomes json. `--agent yes|no` forces that either way, and an explicit
+`-o` always wins over both.
+
+Failures exit non-zero with a stable code. The codes are this CLI's own
+convention, not a service's — they are the `ExitCode` enum in
+`core/errors.py`, and `--discover full` publishes the table so a caller does not
+have to copy it:
+
+| Code | Meaning |
+|------|---------|
+| 0 | success |
+| 1 | generic failure |
+| 2 | usage error |
+| 3 | authentication failed |
+| 4 | not found |
+| 5 | validation failed — also a completed run in which a document failed; the full result, successful documents included, is in `error.details` |
+| 6 | rate limited |
+| 7 | timed out (the job handle is in the error payload — resume, do not resubmit) |
+| 8 | server error |
+| 9 | result already consumed (one-shot read; use `--save` next time) |
+| 10 | the result was read but could not be saved — it is in `error.details` |
+| 130 | interrupted (128 + SIGINT) — the user stopped it, not a failure |
+
+## Credentials
+
+Three keys, each for one job:
+
+- **LLMWhisperer key** — extracts text (`whisper …`). Minted in the LLMWhisperer
+  console.
+- **Deployment key** — runs deployments (`deployment run`, `deployment status`).
+  Shown on the API deployment's own page in the Unstract UI; one an
+  organisation admin mints under **Settings → Global API Deployment Keys**
+  covers every deployment in the organisation.
+- **Platform key** — identifies the organisation and lists what is in it
+  (`auth whoami`, `deployment ls`). Minted by an organisation admin under
+  **Settings → Platform API Keys**.
+
+`auth login` takes whichever of the three you have, checks the two it can
+(`whoami` for the platform key, the usage endpoint for the LLMWhisperer key; a
+deployment key has nothing side-effect-free to call and is stored as given) and
+writes them to one profile. Run it again to rotate a key. A login that stores a
+different host drops the profile's other keys rather than leave them beside a
+server that never accepted them: it asks first, or without a terminal fails
+until `--force`. Without a terminal pass them as flags — `--platform-key`, `--deployment-key`, `--llmwhisperer-key`,
+any one of them `-` to read from stdin.
+
+## Configuration
+
+`~/.unstract/config.toml`, or a project-local `.unstract.toml` found by upward
+search, or `$UNSTRACT_CONFIG`, or `--config`. Every setting resolves
+**flag > env > profile > built-in default**, and the CLI is fully usable with no
+config file at all. The flag tier is the connection options on each product
+group — `--base-url`, `--api-key`, `--org-id` and `--platform-key` on
+`docstudio`, `--base-url`/`--api-key` on `whisper`, `--base-url`/`--platform-key`
+on `auth` — which override the profile for that one invocation without writing
+anything.
+
+```toml
+default_profile = "cloud-us"
+
+[profiles.cloud-us.llmwhisperer]
+base_url = "https://llmwhisperer-api.us-central.unstract.com/api/v2"
+api_key = "env:LLMWHISPERER_API_KEY"
+
+[profiles.cloud-us.docstudio]
+base_url = "https://us-central.unstract.com"
+org_id = "org_ABC123"
+api_key = "env:UNSTRACT_DEPLOYMENT_KEY"
+platform_key = "env:UNSTRACT_PLATFORM_KEY"
+
+# Only for a deployment whose key differs from the one above.
+[profiles.cloud-us.deployments."invoice-parser"]
+api_key = "env:INVOICE_PARSER_KEY"
+```
+
+`deployment run` and `deployment status` take the API name as `deployment ls`
+prints it. `ls` itself authenticates with the platform key and refuses
+`--api-key`, which on `docstudio` means a deployment key. The key for a run resolves `--api-key` > `$UNSTRACT_DEPLOYMENT_KEY` >
+the deployment's own entry > the profile's `api_key`, so most profiles need no
+`deployments` section at all; `config set docstudio api_key <key> --deployment
+<api_name>` writes one. `org_id` lives on the `docstudio` block — `auth login`
+and `auth whoami` write the one the platform key resolves there. `config init`
+writes this shape minus `platform_key` and the `deployments` entry — both are
+the exception, not the starting point — plus a `cloud-eu` profile and an
+`onprem-example` shape to copy for a self-hosted install; only the *active*
+profile is ever resolved.
+
+Either form works for a credential. `auth login` writes keys literally, having
+checked them at the moment it writes. `env:VAR_NAME` indirection — what `config
+init` writes and what the example above uses — keeps the secret out of the file,
+so it stays safe to copy or commit; that is the form for a shared machine or a
+CI checkout. Either way the file is created `0600`, and `config doctor` warns
+when its mode is wider than that.
+
+`unstract config doctor` reports where each setting resolved from — including
+whether an `env:` reference is actually set in the current process — without
+echoing any value. `--probe` also checks the two keys that can be
+checked — the platform key and the LLMWhisperer key, the same two `auth login`
+checks — and, with a platform key, warns about a `deployments` entry the
+organisation no longer has. It exits non-zero when one of its own checks failed, so a setup script can
+branch on it.
+
+A project-local `.unstract.toml` **found by upward search** may not supply a
+key or `base_url`. Those are ignored, with a warning; everything else in it —
+profile selection, `org_id` — applies as usual. A checkout you did not write is
+not trusted to name the host your key is sent to. Name the file explicitly
+(`--config` or `$UNSTRACT_CONFIG`) and it is honoured in full.
+
+What that protects is the key and the host, not the routing: `org_id` and
+profile selection stay repo-controllable by design, so a project file can still
+decide *which* organisation a command runs against on a host you trust. Read
+one before you run inside a checkout you did not write.
+
+`clone` is the exception, and it is an operator command: a human moving one
+organisation's resources into another, holding two admin Platform keys. It is
+not part of the document-processing path the rest of this CLI wraps, so an agent
+serving a user request should not reach for it unasked. It talks to two
+deployments at once, which no single profile describes, so it takes both
+endpoints as flags and both keys from `UNSTRACT_SRC_PLATFORM_KEY` /
+`UNSTRACT_TGT_PLATFORM_KEY` — two keys for two organisations, so it reads
+neither the profile's `platform_key` nor `$UNSTRACT_PLATFORM_KEY`. It exits 0
+when nothing failed, which is not the same as everything having moved: oversize
+and unsupported documents are skipped by design, and `data.skipped` counts them.
+
+## Development
+
+```bash
+uv venv && uv pip install -e '.[dev]'
+uv run pytest   # offline; no network, no credentials
+uv run ruff check .
+```