coho-cli 2026.1.0a21__tar.gz

coho_cli-2026.1.0a21/.github/workflows/ci.yml

@@ -0,0 +1,198 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }}
+
+permissions:
+  contents: read
+
+env:
+  FORCE_COLOR: "1"
+
+jobs:
+  test:
+    name: test · ${{ matrix.os }} · py${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.11", "3.12", "3.13"]
+        include:
+          - os: windows-latest
+            python: "3.13"
+    defaults:
+      run:
+        working-directory: coho-cli
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          path: coho-cli
+          # Every commit and tag: the version is computed from them, and a shallow
+          # clone makes it a meaningless 0.1.dev1.
+          fetch-depth: 0
+
+      # The CLI develops against a sibling checkout of the library, which is what
+      # `[tool.uv.sources]` in pyproject.toml points at. A public repository needs no
+      # extra credential; a private one would need a PAT in `token:`.
+      - uses: actions/checkout@v7
+        with:
+          repository: coho-cms/coho-management-sdk-python
+          path: coho-management-sdk-python
+          # The library's release branch, not its default branch: this CLI needs
+          # the 2026.1 line, which lives there. Spelled out as a branch because the
+          # release tag v2026.1.0 will share its name.
+          ref: refs/heads/v2026.1.0
+          # The library's version comes from its tags. A shallow clone has none and
+          # builds 0.1.dev1, which the version range above refuses.
+          fetch-depth: 0
+
+      - name: Install uv
+        # An exact release: setup-uv stopped publishing floating major tags at v8,
+        # so `@v10` would not resolve.
+        uses: astral-sh/setup-uv@v10.2.0
+        with:
+          python-version: ${{ matrix.python }} # without this every job used the same Python
+          enable-cache: true
+          cache-dependency-glob: coho-cli/uv.lock
+
+      - name: Install the project
+        run: uv sync --locked
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+      - name: Type check
+        run: uv run mypy
+
+      - name: Test
+        run: uv run pytest
+
+  build:
+    name: build distributions
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # Every commit and tag: the version is computed from them, and a shallow
+          # clone makes it a meaningless 0.1.dev1.
+          fetch-depth: 0
+
+      - name: Install uv
+        # An exact release: setup-uv stopped publishing floating major tags at v8,
+        # so `@v10` would not resolve.
+        uses: astral-sh/setup-uv@v10.2.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Refuse a dev-version tag
+        # Dev versions come from commits after a release (2026.1.0a2.dev3), never
+        # from tags. A tag like v2026.1.0.dev1 also makes every later build fail,
+        # because setuptools-scm cannot number a dev build of a dev build.
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          if [[ "$GITHUB_REF_NAME" =~ [.-]?dev[0-9]*$ ]]; then
+            echo "::error::Don't tag dev versions: every commit after a release already builds one."
+            echo "Delete this tag (git push --delete origin $GITHUB_REF_NAME), or every later build fails."
+            exit 1
+          fi
+
+      # Build metadata comes from [project], never from [tool.uv.sources], so the
+      # wheel depends on the published coho-management-sdk even though development does not.
+      - name: Build the wheel and the sdist
+        run: uv build --out-dir dist
+
+      - name: Refuse a tag that is not a version in its standard form
+        # The version comes from the tag, but normalized to PEP 440: `v2026.1.0-rc.1`
+        # builds 2026.1.0rc1. A tag that does not match its own build would mislead
+        # anyone comparing the two, so the wheel's filename is the check.
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          expected="dist/coho_cli-${GITHUB_REF_NAME#v}-py3-none-any.whl"
+          if [ ! -f "$expected" ]; then
+            echo "::error::tag $GITHUB_REF_NAME is not a version in PEP 440's standard form."
+            echo "Use forms like v2026.1.0, v2026.1.0a1, v2026.1.0b1 or v2026.1.0rc1. Built instead:"
+            ls -1 dist
+            exit 1
+          fi
+
+      - name: Check the packaging metadata
+        run: uvx twine check --strict dist/*.whl dist/*.tar.gz
+
+      - name: Upload the distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: coho-cli-dist
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+          if-no-files-found: error
+          retention-days: 90
+
+  release:
+    name: attach to the GitHub release
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download the distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: coho-cli-dist
+          path: dist
+
+      - name: Create or update the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          # An alpha, beta or release candidate is a pre-release on GitHub too, so
+          # it never shows as the latest release.
+          prerelease=""
+          if [[ "$GITHUB_REF_NAME" =~ (a|b|rc)[0-9]+$ ]]; then
+            prerelease="--prerelease"
+          fi
+          if gh release view "$GITHUB_REF_NAME" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+            gh release upload "$GITHUB_REF_NAME" dist/*.whl dist/*.tar.gz --repo "$GITHUB_REPOSITORY" --clobber
+          else
+            gh release create "$GITHUB_REF_NAME" dist/*.whl dist/*.tar.gz \
+              --repo "$GITHUB_REPOSITORY" \
+              --title "coho-cli $GITHUB_REF_NAME" \
+              --generate-notes \
+              --verify-tag $prerelease
+          fi
+
+  publish-pypi:
+    name: publish to PyPI
+    # Skipped unless the repository variable PUBLISH_TO_PYPI is "true". See CONTRIBUTING.md.
+    if: startsWith(github.ref, 'refs/tags/v') && vars.PUBLISH_TO_PYPI == 'true'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/coho-cli/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download the distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: coho-cli-dist
+          path: dist
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

coho_cli-2026.1.0a21/.gitignore

@@ -0,0 +1,226 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# coho-cli
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+*.ndjson
+*.tar

coho_cli-2026.1.0a21/CHANGELOG.md

@@ -0,0 +1,146 @@
+# Changelog
+
+All notable changes to `coho-cli`. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project uses
+[semantic versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+
+- `coho tier move ID --ord N` (coho-data doc 11, M6-15): moves a tier in the pipeline, and
+  the tiers it passes shift by one. Needs coho-management-sdk with `tiers.move`.
+- `coho trait list`, `get`, `put` and `delete` (coho-data doc 05 §10): traits, named groups
+  of fields that types take by naming them in `traits`. `trait list` shows the types that
+  take each. A refused trait or type change now prints what it reaches, `reaches: page,
+  servicePage, and 12 entries`, and a trait in use is refused with the types that take it.
+- `coho type get` shows the type it extends, the traits it takes, and whether it is
+  abstract (coho-data doc 05 §9).
+
+### Changed
+
+- `coho tier create --ord N` inserts: a position another tier holds moves that tier and the
+  ones after it along, where it was refused with `TIER_ORDER_TAKEN`, and anything past the
+  end is the end (coho-data doc 11, M6-15). `coho tier delete` closes the gap it leaves.
+
+### Fixed
+
+- An `@slug` in a field a type inherits, or takes from a trait, is written as the id it
+  names: `coho entry create -t photoGallery --set author=@tom-okafor` stored the text
+  `@tom-okafor`, because the slug was looked up only in the fields the type declares itself.
+- Component types (coho-data doc 40 §14.10): `coho type put` takes a definition with
+  `"kind": "component"`, and `type list`, `get` and `put` show each type's `KIND`. A
+  repeater takes its items as a JSON list, `--set 'citations=[{…}]'`, and the server
+  assigns each item's `_id` and, where the repeater holds one component, its `_type`.
+  Needs coho-management-sdk with `ContentType.kind` and a server with component types.
+
+- `coho project usage [PROJECT]` and `coho account usage`: metered usage (coho-data doc
+  41), as a table or, with `-o json`, the report exactly as the server sent it. A
+  project's shows delivery by key with requests per distinct URL (the client that is not
+  caching), management by people and project tokens and by class, content, history and
+  assets; anyone who can read the project may, project tokens included. The account's
+  sums every project and lists each one's totals, for admins: a member's `FORBIDDEN`
+  says to use `coho project usage` instead. Both take `--grain hour|day`, `--from`,
+  `--to`, `--meter` (repeatable) and `--periods` for a line per hour or day. Needs
+  coho-management-sdk with `usage()` and a server with the usage routes.
+
+- `coho preview entries` ends the table with `more: --offset N` when another page
+  follows, as `entry list` does. It has no `--all`, because each live page resolves the
+  whole ref.
+- `@SLUG` wherever a command takes an entry id: `entry get`, `put`, `delete`, `history`,
+  `references` and `preview entry`. The slug is looked up on the same ref with one
+  request (the BFF's live `preview/{ref}/entries-by-slug/{slug}`), then the command runs
+  as if the id had been typed; a plain id is used as given. A slug nothing has is
+  `ENTRY_NOT_FOUND` (exit 5); one that names a type or an asset, or `@` before something
+  that is not a slug, is a usage error. `entry delete @SLUG` asks about both the slug and
+  the id it found. `entry list` and `entry get` show the slug from `_slug` while the
+  server's entry responses leave out `slug`.
+- `@SLUG` in a reference field's `--set` value, on `entry create` and `entry put`:
+  `--set author=@priya-shah --set 'tags=["@traffic"]'` writes the ids those slugs name
+  on the same ref. Only fields the content type declares as references are looked up, so
+  text keeps a leading `@`; the type is read only when a value starts with `@`.
+- `@SLUG` in an asset field's `--set` value too: `--set image=@culvert` writes the id of
+  the asset with that slug, from one listing of the ref's assets. A slug no asset has
+  is `ASSET_NOT_FOUND` (exit 5).
+- `coho ref switch NAME`: makes a branch, tag or environment of the current project the
+  current ref, after checking it exists, keeping the account and project. It and
+  `coho branch create` warn when `--ref` or `COHO_REF` still overrides the saved ref.
+- `coho asset`: files on the current ref (coho-data doc 40). `asset upload FILE…` hashes
+  each file, sends it straight to object storage on a presigned URL and writes it as an
+  asset, building the slug from the filename (`Hero Shot.jpg` → `hero-shot`) unless
+  `--slug` is given for a single file; `--title`, `--alt`, `--focal x,y` and `--tag` set
+  its metadata. Bytes the project already holds are not sent again. Also `asset list`,
+  `get`, `url` (prints the original, or a resized image URL with `--width`, `--height`,
+  `--fit`, `--format`, `--quality`, centring fills on the focal point), `put` and
+  `delete`, each taking an id or a slug. Upload warns on stderr that asset URLs are
+  public to anyone holding them. Needs the `coho-management-sdk` that adds `ref.assets`,
+  and a server with the asset routes.
+- On PyPI: `uv tool install coho-cli` or `pipx install coho-cli`.
+- `coho login` finishes setting up an identity that has no organization yet: it opens the
+  BFF's sign-in in the browser, which asks for the organization's name, and waits until the
+  account exists. That sign-in asks for the password once more, because the CLI's own sign-in
+  never reaches the BFF. `coho login --token` with such an identity says where to go instead.
+- An account saved with `coho use` that is not one of yours any more — deleted, or
+  remembered from before an environment was reset — gives way to your only account, which
+  is saved in its place (with the stale project and ref cleared) and named in a one-time
+  warning. With several accounts it asks which. Costs one `/me` per command while an
+  account is saved. `--account` and `COHO_ACCOUNT` are used as given.
+- `coho type put` and `coho entry create` build the slug from the name when none is given:
+  camelCase for a type (`Blog post` → `blogPost`), kebab-case for an entry (`Hello, World!` →
+  `hello-world`). An explicit slug is sent unchanged.
+- `coho tag create --validate` has the server check every entry at the tag point before
+  cutting the tag. If any fails, it is refused with `TAG_CONTENT_INVALID` and nothing is
+  tagged: the CLI prints how many entries fail, then each listed one's slug, type, id and
+  field errors, says how many went unlisted past the server's 100, and exits 1. With
+  `-o json` the problem document goes to stdout. Without the flag, tagging is unchanged.
+  Needs the `coho-management-sdk` that adds `tags.create(validate=…)`, and a server that
+  accepts `validate`.
+
+### Changed
+
+- `coho branch create` makes the new branch the current ref, as `coho project create`
+  makes the new project current; `--no-use` keeps the current ref. When `--ref` or
+  `COHO_REF` is set, it warns that the override still wins over the saved ref.
+- `coho signup` opens the BFF's sign-up page in the browser, as `coho login` opens the
+  sign-in page, and makes no API call itself. Sign-up stays an interactive session;
+  before release that page verifies a captcha.
+- `coho login` uses `http://localhost:8765/callback`, matching the CLI's Cognito app
+  client, and answers on both loopback addresses.
+
+- The library moved to its own repository and distribution,
+  [coho-management-sdk-python](https://github.com/coho-cms/coho-management-sdk-python), along with the API
+  contracts and the library reference. This repository is now the command alone, and
+  depends on `coho-management-sdk` as an ordinary package. Development uses a sibling checkout;
+  see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+### Fixed
+
+- `coho preview entries` crashed with `AttributeError: 'str' object has no attribute
+  'get'`, in table and JSON output both. It read the body as a list of entries, but
+  delivery answers with an `EntryGraph`: it now lists `roots` in order, looked up in
+  `entries`.
+- `coho signup`, `coho invite lookup` and `coho invite accept` failed with
+  `NOT_LOGGED_IN` for anyone without a login, who are exactly the people they are for.
+- Errors printed their code twice, as in `error NOT_LOGGED_IN: NOT_LOGGED_IN: …`.
+- URLs printed by `--no-browser` were wrapped at the terminal's width, so a copied URL
+  came out broken.
+- `coho login` followed a successful sign-in with a bare `UNAUTHENTICATED` when the
+  identity had no Coho account yet. It now says so, and what to run.
+
+## [0.1.0] — unreleased
+
+Initial version.
+
+- Commands: `login`, `logout`, `whoami`, `signup`, `configure`, `profile`, `use`,
+  `status`, `account`, `member`, `invite`, `user`, `project`, `role`, `ref`, `branch`,
+  `tag`, `type`, `entry`, `diff`, `merge`, `env`, `promote`, `rollback`, `tier`, `key`,
+  `export`, `preview`.
+- A sticky context (account, project, ref) per profile, verified against the server
+  before it is saved, and overridable by flag or environment variable.
+- `--output json` prints the contract's response verbatim, so `jq` works against the
+  documented shapes. Exit codes distinguish usage (2), authentication (3), a failed
+  precondition worth retrying (4) and not-found (5).
+- A local project registry, because the server has no project listing yet.
+
+[Unreleased]: https://github.com/coho-cms/coho-cli/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/coho-cms/coho-cli/releases/tag/v0.1.0

coho_cli-2026.1.0a21/CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributing
+
+## Setup
+
+The CLI is a thin layer over [`coho-management-sdk`](https://github.com/coho-cms/coho-management-sdk-python),
+and develops against a sibling checkout of it:
+
+```bash
+git clone https://github.com/coho-cms/coho-management-sdk-python
+git clone https://github.com/coho-cms/coho-cli
+cd coho-cli
+uv sync                    # resolves coho-management-sdk from ../coho-management-sdk-python
+uv run coho --help
+uv run pytest              # 22 tests, no network, no server
+uv run ruff check . && uv run ruff format --check .
+uv run mypy                # strict
+```
+
+Or `make check` for all of it.
+
+### `coho` as a real command
+
+To use your working copy as the installed `coho`, from any directory:
+
+```bash
+uv tool install --editable . --with-editable ../coho-management-sdk-python
+```
+
+The command lands in `~/.local/bin` and runs the source in both repositories, so
+edits take effect at once. Reinstall, by adding `--force`, only when dependencies or
+the entry point change; `uv tool uninstall coho-cli` removes it. It shares the
+profiles and stored logins in `~/.config/coho` with `uv run coho`. `uv sync --no-sources` builds against the published
+`coho-management-sdk` instead, which is what a user gets; see `[tool.uv.sources]` in
+`pyproject.toml`.
+
+## Layout
+
+```
+src/coho_cli/
+  main.py          the typer app, global options, error → exit code
+  _state.py        config/profile/client/context resolution for commands
+  _output.py       tables, JSON, shown-once secrets
+  _io.py           --file and --set parsing
+  commands/        one module per noun
+tests/             the whole command tree against the SDK's FakeBff
+docs/              guides and the command reference
+```
+
+⚠️ **Push the SDK first.** CI builds the CLI against the SDK's `v2026.1.0` branch on GitHub,
+not your local copy. A CLI change that uses new SDK code fails CI with
+`"Coho" has no attribute …` until that SDK code is pushed; then re-run the CLI's
+workflow.
+
+The library, the API contracts and the library reference live in
+[coho-management-sdk-python](https://github.com/coho-cms/coho-management-sdk-python).
+
+## Rules of the road
+
+1. **The library owns behaviour; the CLI owns presentation.** If a command needs logic
+   that is not printing or argument parsing, it belongs in `coho_management_sdk` — open a pull
+   request there and call it from here. Resist the urge to reimplement it locally.
+2. **Errors print their `code`.** `main.py` maps `CohoError` to an exit code and a
+   one-line message; never catch an error just to reword it.
+3. **Secrets go to stdout alone**, with the warning on stderr, so
+   `coho key create > key.txt` captures the key and nothing else.
+4. **`--output json` prints the contract's response**, not a reshaped version of it.
+   Every model in the SDK keeps `.raw` for exactly this.
+5. **Tests run against `coho_management_sdk.testing.FakeBff`**, never a live server. A behaviour
+   that needs a new route belongs in the fake, which means a pull request against the
+   library.
+
+## Releasing
+
+The version comes from git tags (`hatch-vcs`); nothing in the source holds it.
+Tag `v2026.1.0` to release, `v2026.1.0a1`, `b1` or `rc1` for a pre-release. Every
+commit after a tag builds a dev version such as `2026.1.0a2.dev3`. ⚠️ Never tag a dev
+version: CI refuses it, and every later build would fail.
+
+1. Update the `coho-management-sdk` constraint if the CLI needs a newer library, and add
+   a `CHANGELOG.md` entry.
+2. Commit and push, then tag: `git tag v2026.1.0a4 && git push origin v2026.1.0a4`.
+3. CI tests, builds a wheel and an sdist, fails if the tag is not a version in its
+   standard form, uploads both as a build artifact, attaches them to a GitHub
+   Release (a pre-release for an alpha, beta or release candidate), and publishes
+   them to [PyPI](https://pypi.org/project/coho-cli/).
+
+⚠️ **Release `coho-management-sdk` first**, and wait until it is on PyPI: a `coho-cli` that
+depends on a library version nobody can install is not installable either. PyPI never
+takes the same version's files twice, even after a delete, so a broken release is fixed
+by the next tag.
+
+The `publish-pypi` job authenticates as a [trusted publisher](https://docs.pypi.org/trusted-publishers/)
+with a short-lived OIDC token, so no API token is stored anywhere, and deploys through
+the `pypi` environment, which only `v*` tags can use. Setting the repository variable
+`PUBLISH_TO_PYPI` to anything but `true` turns it off.