caffeinated-whale-cli 3.0.0__tar.gz → 3.1.0__tar.gz

{caffeinated_whale_cli-3.0.0 → caffeinated_whale_cli-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: caffeinated-whale-cli
-Version: 3.0.0
+Version: 3.1.0
 Summary: A CLI tool to help manage Frappe Docker instances.
 Author-email: Christopher McKay <mckay.christopher73@outlook.com>
 License: MIT
@@ -158,6 +158,47 @@ python -m caffeinated_whale_cli ls
 
 This bypasses the shim entirely and behaves identically to `cwcli`/`caffeinated-whale-cli`.
 
+## Shared (multi-user) install
+
+By default cwcli's on-disk state is **per-user**: everything lives under `~/.cwcli`, the cache is `0700`, the config `0600`, and the credential-bridge daemon runs as you.
+That is correct for one person per machine, and it is unchanged - if you do not opt in, nothing here applies to you.
+
+When several people on **one Linux/UNIX box** need to drive the **same** Frappe instances (they already share the containers through the `docker` group), the per-user modes get in the way: the second person hits `Permission denied` on the cache, cannot edit the shared config, and the credential bridge either locks them out or hands them the first person's token.
+Shared mode fixes this with an opt-in, admin-provisioned layout modelled on Docker's `root:docker` socket and Homebrew-on-Linux's shared tree: a dedicated `cwcli` group, a system state tree with setgid group-writable directories, and one machine-wide credential bridge behind a group-owned socket.
+
+**Enable it (once, by an admin):**
+
+```bash
+sudo cwcli setup shared --users alice,bob            # create the group + tree, add members
+sudo cwcli setup shared --users alice,bob --cred-bridge   # also stand up the machine-wide credential bridge
+```
+
+This creates the `cwcli` group and a `cwcli` service account, provisions `/var/lib/cwcli` (config, cache, projects, archive) as `root:cwcli` with setgid `2770` directories, and writes the marker `/etc/cwcli/shared.toml` that turns shared mode on.
+It is idempotent - safe to re-run to add users or repair modes.
+Members must log out and back in for the new group to take effect.
+Windows is unaffected (shared mode is POSIX-only; cwcli stays per-user there).
+
+**Consolidate existing per-user homes into the shared tree:**
+
+```bash
+sudo cwcli setup migrate --from /home/alice/.cwcli --from /home/bob/.cwcli
+sudo cwcli setup migrate --discover          # find every /home/*/.cwcli and /root/.cwcli
+```
+
+`migrate` copies each user's project state into the shared tree with the correct group ownership and modes.
+It **never deletes a source** and **refuses to overwrite an existing shared project** (a name clash is reported, not clobbered), so it is safe to re-run.
+The per-user SQLite cache is regenerable (`cwcli inspect`) and deliberately not merged.
+
+**Opting an invocation back to a private home:** `CWCLI_HOME` always wins over shared mode, so `CWCLI_HOME=~/.cwcli cwcli ...` uses your own home even on a shared box.
+
+**Security consequences - state them plainly before enabling:**
+
+- **`cwcli` group membership is the trust boundary.** Anyone in the group can read every instance's cache, read the rm/rm-site backups (which contain full database dumps), edit the shared config, and - with `--cred-bridge` - ask the machine-wide bridge for a credential. This is the same "docker group ≈ root-ish capability" trade every shared dev tool makes. Keep membership deliberate.
+- **The credential bridge in shared mode serves one machine-owned, read-only service-account token** to any group member's container git, so its audit log records the host and project but **not which human** triggered a fetch (they all present as the service account). Provision that account with a read-only deploy token; rotate it in one place if it leaks.
+- The group-owned socket (`0660 root:cwcli`) closes the world-connectable `0666` socket that could otherwise leak the first user's token to a second user on the box. A uid outside the `cwcli` group cannot reach it.
+
+Run `cwcli doctor` to verify the shared install (group present, tree modes, service account).
+
 ## Quick Start
 
 ```bash
@@ -193,6 +234,8 @@ A cluster containing an unknown short option is rejected as a whole.
 
 Creates a complete Frappe development environment in a single step. Downloads compose files, starts containers, initializes bench, creates a site, and starts the bench's dev services.
 
+Blocks for roughly 10-20 minutes (image pulls, bench init, site creation). Running several `cwcli init` invocations in parallel can OOM-kill the host on a memory-constrained machine - serialize them instead. Adding a bench to an already-running instance (`cwcli init existing-project --bench another-bench`) never disturbs it or its other benches: the frappe container is never pulled, recreated, or restarted, so every already-serving bench keeps running throughout.
+
 ```bash
 cwcli init [OPTIONS] [PROJECT_NAME]
 ```
@@ -934,6 +977,7 @@ cwcli inspect [OPTIONS] PROJECT_NAME
 
 | Option | Description |
 |--------|-------------|
+| `--bench <index\|label>` | Narrow the report to one bench on a multi-bench project (its numeric index or label). Every bench is still discovered/refreshed/cached regardless; only the output is narrowed |
 | `-v`, `--verbose` | Enable verbose diagnostic output |
 | `-j`, `--json` | Output the result as a JSON object |
 | `-u`, `--update` | Update the cache by re-inspecting the project |
@@ -988,6 +1032,9 @@ cwcli inspect frappe-one --no-refresh
 # Get JSON output
 cwcli inspect frappe-one --json
 
+# Narrow the report to one bench in a multi-bench project
+cwcli inspect frappe-one --bench 1
+
 # Interactively label each bench (durable handle for --bench)
 cwcli inspect frappe-one --interactive
 ```
@@ -2021,6 +2068,7 @@ This is the same class of exposure as SSH agent forwarding or VS Code's own cred
 Every request is written to an audit log (`~/.cwcli/run/credbridge-audit.log`, one line per request: timestamp, instance, host, answered - never a credential byte).
 For a tighter blast radius, authenticate `gh`/`glab` with a fine-grained, expiring token scoped to only the repos you need; the bridge faithfully forwards whatever the host tools hold, so the token's reach is your auth choice.
 On a shared multi-user host, note the per-instance socket lives in the instance's workspace directory under `~/.cwcli/projects/<name>/data/`; `enable` tightens `~/.cwcli/projects` to owner-only (0700) for exactly that reason.
+This per-user daemon is distinct from the **machine-wide** bridge of an opt-in [shared install](#shared-multi-user-install): there the daemon runs once as the `cwcli` service account (started by a system unit at boot), serves a single machine-owned read-only service-account token, and its socket is `0660 root:cwcli` so a uid outside the `cwcli` group cannot reach it. See that section for the security consequences.
 
 **Host allowlist:** the daemon only answers credential requests for `github.com` and `gitlab.com` by default.
 Using a self-hosted GitLab (or GitHub Enterprise)?
@@ -2297,8 +2345,11 @@ cwcli axi scale frappe-one --to 8 --yes
 # Every site carries installed_apps_verified: true only on a full read - the
 # cache/partial tiers carry a site's apps (and their git refs) forward without
 # re-observing them, so a non-full read with a remembered app list also warns.
+# --bench <index|label> narrows the report to one bench (every tier still
+# refreshes/caches every bench regardless; only the emitted report is narrowed).
 cwcli axi inspect frappe-one
 cwcli axi inspect frappe-one --update
+cwcli axi inspect frappe-one --bench 1
 
 # List a project's benches with their indices and labels. This is what answers
 # "pass --bench <index|label>" from any other verb - no other verb can.
@@ -2364,7 +2415,7 @@ cwcli axi config
 cwcli axi doctor
 ```
 
-`cwcli axi ls`, `cwcli axi where`, `cwcli axi backup`, `cwcli axi unlock`, `cwcli axi stop`, `cwcli axi start`, `cwcli axi status`, `cwcli axi restart`, `cwcli axi inspect`, `cwcli axi benches`, and `cwcli axi label` run on the same logic core as their human counterparts; only the output (always TOON, never JSON) and choice-handling differ. `cwcli axi start` never prompts: an ambiguous multi-bench project is a `--bench` usage error (exit 2), and an unresolved port conflict is a `CONFLICT` error naming `--yes` (exit 1). `cwcli axi unlock` follows `cwcli axi backup`'s conventions exactly: an ambiguous multi-bench project is a `--bench` usage error (exit 2) and a stopped instance is a usage error pointing at `cwcli start` (exit 2). `cwcli axi stop` is idempotent for an agent - stopping an already-stopped project is a success, not an error. `cwcli axi where` answers from the cache, which outlives the instances it describes, so every match carries `project_state` (`present`, `absent`, or `unverified`) and the document carries `verified`: an agent must read those before acting on a hit, because an `absent` row describes an instance that no longer exists and an `unverified` row means the liveness check could not run. An unreachable Docker daemon degrades the whole answer to `unverified` rather than vouching for it, and `--no-verify` skips the check (reporting `unverified`) when a caller has already established liveness. `cwcli axi status` always exits 0, leading with the instance `overall` aggregate (`offline`/`online`/`running`/`degraded`). It reports **every** bench, in one document, under `benches[N]` - with no `--bench` it used to refuse a multi-bench project with exit 2 and send you off to `cwcli axi benches` to poll once per bench, reassembling the instance view from documents that never said which bench they described. The shape is uniform, so `supervisor_up`, `web_http_code`, `processes` and `not_cwcli_supervised` live inside `benches[i]` even for a single-bench project (`benches[0].processes`), and there is one parse path rather than a branch on bench count. Each bench also carries `bench_present` (`present`/`absent`/`unverified`) - the bench LIST comes from the cache, and a bench whose directory was deleted has no marker and no supervisord, which is indistinguishable from one that was simply never started, so it used to read as `online`; the token answers that, and `overall` keeps its four tokens. Each bench also carries `index`, `bench_path`, `label`, its own `overall`, `web_port`/`web_port_verified` (the port that bench's `web_http_code` was actually measured on), and `web_site` (the site it was measured FOR - Frappe routes by `Host`, so the code belongs to that site, and a probe naming no site is answered `404` by a healthy bench). When that port cannot be read it is `null`/`false` and **no probe was made** - cwcli never falls back to `:8000`, because on a multi-bench instance that reports a different bench's web server as this one's. A stopped instance carries `benches: []`. `cwcli axi stop` takes `--bench <index|label>` to stop ONE bench's dev processes, leaving sibling benches and every container running - the inverse of `cwcli axi start --bench`; without it, it stops the whole instance's containers, and either form is idempotent. `cwcli axi restart` requires `--process`; an unknown/ambiguous process is a usage error listing the valid labels (exit 2). `cwcli axi inspect` serves whichever freshness tier answers the request (`served_from` names it) and, unlike every other bench-scoped verb, has deliberately NO `--yes` - a stopped project on the refresh path is a usage error (exit 2) naming `cwcli start`, and a drift escalation that can no longer discover the bench serves the cached data with `degraded: true` and a warning (exit 0). Every site also carries `installed_apps_verified`: only a full read actually re-observes an app's installed version and git ref, so a cache or partial read carries the remembered list forward unverified and, when that list is non-empty, adds a warning naming `--update` - an agent must not treat an unverified `installed_apps` entry as the live git state. `cwcli axi benches` is the discovery verb behind every other verb's `--bench`: when a bench-scoped verb reports "multiple benches; pass `--bench <index|label>`", this is what tells you the valid values, and a project that has never been inspected is a structured error naming `cwcli axi inspect` rather than an empty list. Its rows come from the cache, which outlives the benches it describes, so every row carries `state` (`present`, `absent`, or `unverified`) and the document carries `verified` - the same contract `cwcli axi where` uses, cross-checked here against the running container in one exec. An agent must read `state` before acting on a row: `absent` means that bench directory no longer exists, and `unverified` means the check could not run (a stopped project, an unreachable daemon, or `--no-verify`) - never a confirmation. A stale row is reported, never pruned; `cwcli axi inspect <project> --update` is what refreshes it. `cwcli axi label` never starts a stopped project (the label marker lives inside the bench), and listing is deliberately `cwcli axi benches` rather than a mode of the mutation verb. `cwcli axi self-update --check` is read-only and **exits 0 whenever the check succeeds, including when an update is available** - the answer is the `is_outdated` field, not the exit code, because on the agent surface a non-zero exit means an error. This deliberately differs from the human `cwcli self-update --check`, which exits 1 when an update is available so shell scripts can gate on it; the mutating `cwcli axi self-update` is deliberately not offered. `cwcli axi config` is the read-only counterpart of `cwcli config show`: one TOON document carrying the search paths, all three auto-inspect state stores, the credential-bridge state, the tips setting, and the file locations. **No config-mutating axi verbs exist** (no `paths add`/`remove`, no `cache clear`, no `auto-inspect enable`/`disable`): an agent rewriting the user's search paths or wiping the cache is a product decision that deserves its own evidence, so mutations stay on the human `cwcli config` surface (whose reads all have `--json`). `cwcli axi doctor` is the read-only, system-wide counterpart of `cwcli doctor`: one TOON document listing every check with a machine-readable `status` (`pass`/`warn`/`fail`) an agent gates on directly, never by parsing the `detail` text. It exits 0 whenever every check is pass/warn and non-zero only when a check fails, exactly matching the human command, so a fleet can run it before driving any instance and `&&`-chain on the result.
+`cwcli axi ls`, `cwcli axi where`, `cwcli axi backup`, `cwcli axi unlock`, `cwcli axi stop`, `cwcli axi start`, `cwcli axi status`, `cwcli axi restart`, `cwcli axi inspect`, `cwcli axi benches`, and `cwcli axi label` run on the same logic core as their human counterparts; only the output (always TOON, never JSON) and choice-handling differ. `cwcli axi start` never prompts: an ambiguous multi-bench project is a `--bench` usage error (exit 2), and an unresolved port conflict is a `CONFLICT` error naming `--yes` (exit 1). `cwcli axi unlock` follows `cwcli axi backup`'s conventions exactly: an ambiguous multi-bench project is a `--bench` usage error (exit 2) and a stopped instance is a usage error pointing at `cwcli start` (exit 2). `cwcli axi stop` is idempotent for an agent - stopping an already-stopped project is a success, not an error. `cwcli axi where` answers from the cache, which outlives the instances it describes, so every match carries `project_state` (`present`, `absent`, or `unverified`) and the document carries `verified`: an agent must read those before acting on a hit, because an `absent` row describes an instance that no longer exists and an `unverified` row means the liveness check could not run. An unreachable Docker daemon degrades the whole answer to `unverified` rather than vouching for it, and `--no-verify` skips the check (reporting `unverified`) when a caller has already established liveness. `cwcli axi status` always exits 0, leading with the instance `overall` aggregate (`offline`/`online`/`running`/`degraded`). It reports **every** bench, in one document, under `benches[N]` - with no `--bench` it used to refuse a multi-bench project with exit 2 and send you off to `cwcli axi benches` to poll once per bench, reassembling the instance view from documents that never said which bench they described. The shape is uniform, so `supervisor_up`, `web_http_code`, `processes` and `not_cwcli_supervised` live inside `benches[i]` even for a single-bench project (`benches[0].processes`), and there is one parse path rather than a branch on bench count. Each bench also carries `bench_present` (`present`/`absent`/`unverified`) - the bench LIST comes from the cache, and a bench whose directory was deleted has no marker and no supervisord, which is indistinguishable from one that was simply never started, so it used to read as `online`; the token answers that, and `overall` keeps its four tokens. Each bench also carries `index`, `bench_path`, `label`, its own `overall`, `web_port`/`web_port_verified` (the port that bench's `web_http_code` was actually measured on), and `web_site` (the site it was measured FOR - Frappe routes by `Host`, so the code belongs to that site, and a probe naming no site is answered `404` by a healthy bench). When that port cannot be read it is `null`/`false` and **no probe was made** - cwcli never falls back to `:8000`, because on a multi-bench instance that reports a different bench's web server as this one's. A stopped instance carries `benches: []`. `cwcli axi stop` takes `--bench <index|label>` to stop ONE bench's dev processes, leaving sibling benches and every container running - the inverse of `cwcli axi start --bench`; without it, it stops the whole instance's containers, and either form is idempotent. `cwcli axi restart` requires `--process`; an unknown/ambiguous process is a usage error listing the valid labels (exit 2). `cwcli axi inspect` serves whichever freshness tier answers the request (`served_from` names it) and, unlike every other bench-scoped verb, has deliberately NO `--yes` - a stopped project on the refresh path is a usage error (exit 2) naming `cwcli start`, and a drift escalation that can no longer discover the bench serves the cached data with `degraded: true` and a warning (exit 0). It takes `--bench <index|label>` like every other bench-scoped verb, narrowing the emitted report to one bench; every tier still discovers/refreshes/caches every bench regardless of the selector, and an unknown selector is a `bench.not_found` error (exit 1). Every site also carries `installed_apps_verified`: only a full read actually re-observes an app's installed version and git ref, so a cache or partial read carries the remembered list forward unverified and, when that list is non-empty, adds a warning naming `--update` - an agent must not treat an unverified `installed_apps` entry as the live git state. `cwcli axi benches` is the discovery verb behind every other verb's `--bench`: when a bench-scoped verb reports "multiple benches; pass `--bench <index|label>`", this is what tells you the valid values, and a project that has never been inspected is a structured error naming `cwcli axi inspect` rather than an empty list. Its rows come from the cache, which outlives the benches it describes, so every row carries `state` (`present`, `absent`, or `unverified`) and the document carries `verified` - the same contract `cwcli axi where` uses, cross-checked here against the running container in one exec. An agent must read `state` before acting on a row: `absent` means that bench directory no longer exists, and `unverified` means the check could not run (a stopped project, an unreachable daemon, or `--no-verify`) - never a confirmation. A stale row is reported, never pruned; `cwcli axi inspect <project> --update` is what refreshes it. `cwcli axi label` never starts a stopped project (the label marker lives inside the bench), and listing is deliberately `cwcli axi benches` rather than a mode of the mutation verb. `cwcli axi self-update --check` is read-only and **exits 0 whenever the check succeeds, including when an update is available** - the answer is the `is_outdated` field, not the exit code, because on the agent surface a non-zero exit means an error. This deliberately differs from the human `cwcli self-update --check`, which exits 1 when an update is available so shell scripts can gate on it; the mutating `cwcli axi self-update` is deliberately not offered. `cwcli axi config` is the read-only counterpart of `cwcli config show`: one TOON document carrying the search paths, all three auto-inspect state stores, the credential-bridge state, the tips setting, and the file locations. **No config-mutating axi verbs exist** (no `paths add`/`remove`, no `cache clear`, no `auto-inspect enable`/`disable`): an agent rewriting the user's search paths or wiping the cache is a product decision that deserves its own evidence, so mutations stay on the human `cwcli config` surface (whose reads all have `--json`). `cwcli axi doctor` is the read-only, system-wide counterpart of `cwcli doctor`: one TOON document listing every check with a machine-readable `status` (`pass`/`warn`/`fail`) an agent gates on directly, never by parsing the `detail` text. It exits 0 whenever every check is pass/warn and non-zero only when a check fails, exactly matching the human command, so a fleet can run it before driving any instance and `&&`-chain on the result.
 
 `cwcli axi url <project>` answers two questions no other `axi` verb does: what HOST URL a bench actually serves on, and whether it is answering HTTP right now.
 `cwcli axi status`'s `web_http_code` is measured against the bench's CONTAINER-internal port and never states the host address; the host URL is computed only by `cwcli open`'s success banner and the human `cwcli init` banner, neither reachable from `cwcli axi`, so getting either answer meant dropping to a raw `docker inspect`/`curl` against the container.
@@ -2418,7 +2469,7 @@ It exits non-zero if a restart fails or the named site does not answer Frappe's
 
 These are agent-only for now: there is no human `cwcli migrate`, `cwcli run-tests`, or `cwcli build` yet. Use `cwcli run <project> --site <site> migrate` for the human equivalent.
 
-`cwcli axi init` provisions a new instance, bench, and site the way `cwcli init` does, but non-interactively and as ONE terminal TOON document. It **blocks** for the full 10-20 minute run - the same block-and-emit-one-document shape as `cwcli axi apps update`, because a progress stream would break the one-TOON-document contract - narrating coarse phase labels to stderr; run `cwcli logs <project>` / `cwcli status <project>` from a second shell for live progress. After the bench+site is created, it starts the bench's dev services by default (the same `core.start` behind `cwcli start`/`cwcli axi start`), leaving a running bench rather than a created-but-idle one; `--no-start` creates without starting, for automation/CI, distinct from Docker container startup (stage 1 always brings the containers up regardless of this flag). A dev-services start failure degrades to a stderr warning rather than a non-zero exit, since the bench was already created. The site administrator password comes from the **`CWCLI_ADMIN_PASSWORD` environment variable (recommended)** or `--admin-password`; the flag wins if both are set, and with neither set the verb refuses with a usage error (exit 2) naming both - it never generates a password and never prompts. The env var keeps the secret off the process argv (visible in `ps`/shell history) that the flag exposes; the container-side `bench new-site` still receives it, so treat the value as one-time. The MariaDB root password takes the same shape via `CWCLI_DB_ROOT_PASSWORD` / `--db-root-password` (default `123`). The interactive decisions the human `cwcli init` prompts for become non-prompting errors: an existing bench with neither `--reuse-bench` nor `--no-reuse-bench` is a usage error (exit 2) naming both; a port conflict names `--port` (exit 1); containers that do not come up point at `cwcli status`/`cwcli logs` (exit 1). There is no `--auto-start` (compose `cwcli axi start` then re-run) and no `--verbose` (stdout is always TOON). `--bench` here is the NAME of the bench to create, distinct from the `--bench <index|label>` selector the other verbs use.
+`cwcli axi init` provisions a new instance, bench, and site the way `cwcli init` does, but non-interactively and as ONE terminal TOON document. It **blocks** for the full 10-20 minute run - the same block-and-emit-one-document shape as `cwcli axi apps update`, because a progress stream would break the one-TOON-document contract - narrating coarse phase labels to stderr; run `cwcli logs <project>` / `cwcli status <project>` from a second shell for live progress. Running several `axi init` calls in parallel can OOM-kill the host on a memory-constrained machine - serialize them instead. Adding a bench to an already-running instance never disturbs it or its other benches: the frappe container is never pulled, recreated, or restarted, so every already-serving bench keeps running throughout. After the bench+site is created, it starts the bench's dev services by default (the same `core.start` behind `cwcli start`/`cwcli axi start`), leaving a running bench rather than a created-but-idle one; `--no-start` creates without starting, for automation/CI, distinct from Docker container startup (stage 1 always brings the containers up regardless of this flag). A dev-services start failure degrades to a stderr warning rather than a non-zero exit, since the bench was already created. The site administrator password comes from the **`CWCLI_ADMIN_PASSWORD` environment variable (recommended)** or `--admin-password`; the flag wins if both are set, and with neither set the verb refuses with a usage error (exit 2) naming both - it never generates a password and never prompts. The env var keeps the secret off the process argv (visible in `ps`/shell history) that the flag exposes; the container-side `bench new-site` still receives it, so treat the value as one-time. The MariaDB root password takes the same shape via `CWCLI_DB_ROOT_PASSWORD` / `--db-root-password` (default `123`). The interactive decisions the human `cwcli init` prompts for become non-prompting errors: an existing bench with neither `--reuse-bench` nor `--no-reuse-bench` is a usage error (exit 2) naming both; a port conflict names `--port` (exit 1); containers that do not come up point at `cwcli status`/`cwcli logs` (exit 1). There is no `--auto-start` (compose `cwcli axi start` then re-run) and no `--verbose` (stdout is always TOON). `--bench` here is the NAME of the bench to create, distinct from the `--bench <index|label>` selector the other verbs use.
 
 `cwcli axi rm <project> --yes` permanently removes an instance: its containers, named volumes (databases, sites, and files), own Docker Compose network, and local project directory.
 It is the agent form of `cwcli rm`, and it runs the same code.

{caffeinated_whale_cli-3.0.0 → caffeinated_whale_cli-3.1.0}/README.md

@@ -118,6 +118,47 @@ python -m caffeinated_whale_cli ls
 
 This bypasses the shim entirely and behaves identically to `cwcli`/`caffeinated-whale-cli`.
 
+## Shared (multi-user) install
+
+By default cwcli's on-disk state is **per-user**: everything lives under `~/.cwcli`, the cache is `0700`, the config `0600`, and the credential-bridge daemon runs as you.
+That is correct for one person per machine, and it is unchanged - if you do not opt in, nothing here applies to you.
+
+When several people on **one Linux/UNIX box** need to drive the **same** Frappe instances (they already share the containers through the `docker` group), the per-user modes get in the way: the second person hits `Permission denied` on the cache, cannot edit the shared config, and the credential bridge either locks them out or hands them the first person's token.
+Shared mode fixes this with an opt-in, admin-provisioned layout modelled on Docker's `root:docker` socket and Homebrew-on-Linux's shared tree: a dedicated `cwcli` group, a system state tree with setgid group-writable directories, and one machine-wide credential bridge behind a group-owned socket.
+
+**Enable it (once, by an admin):**
+
+```bash
+sudo cwcli setup shared --users alice,bob            # create the group + tree, add members
+sudo cwcli setup shared --users alice,bob --cred-bridge   # also stand up the machine-wide credential bridge
+```
+
+This creates the `cwcli` group and a `cwcli` service account, provisions `/var/lib/cwcli` (config, cache, projects, archive) as `root:cwcli` with setgid `2770` directories, and writes the marker `/etc/cwcli/shared.toml` that turns shared mode on.
+It is idempotent - safe to re-run to add users or repair modes.
+Members must log out and back in for the new group to take effect.
+Windows is unaffected (shared mode is POSIX-only; cwcli stays per-user there).
+
+**Consolidate existing per-user homes into the shared tree:**
+
+```bash
+sudo cwcli setup migrate --from /home/alice/.cwcli --from /home/bob/.cwcli
+sudo cwcli setup migrate --discover          # find every /home/*/.cwcli and /root/.cwcli
+```
+
+`migrate` copies each user's project state into the shared tree with the correct group ownership and modes.
+It **never deletes a source** and **refuses to overwrite an existing shared project** (a name clash is reported, not clobbered), so it is safe to re-run.
+The per-user SQLite cache is regenerable (`cwcli inspect`) and deliberately not merged.
+
+**Opting an invocation back to a private home:** `CWCLI_HOME` always wins over shared mode, so `CWCLI_HOME=~/.cwcli cwcli ...` uses your own home even on a shared box.
+
+**Security consequences - state them plainly before enabling:**
+
+- **`cwcli` group membership is the trust boundary.** Anyone in the group can read every instance's cache, read the rm/rm-site backups (which contain full database dumps), edit the shared config, and - with `--cred-bridge` - ask the machine-wide bridge for a credential. This is the same "docker group ≈ root-ish capability" trade every shared dev tool makes. Keep membership deliberate.
+- **The credential bridge in shared mode serves one machine-owned, read-only service-account token** to any group member's container git, so its audit log records the host and project but **not which human** triggered a fetch (they all present as the service account). Provision that account with a read-only deploy token; rotate it in one place if it leaks.
+- The group-owned socket (`0660 root:cwcli`) closes the world-connectable `0666` socket that could otherwise leak the first user's token to a second user on the box. A uid outside the `cwcli` group cannot reach it.
+
+Run `cwcli doctor` to verify the shared install (group present, tree modes, service account).
+
 ## Quick Start
 
 ```bash
@@ -153,6 +194,8 @@ A cluster containing an unknown short option is rejected as a whole.
 
 Creates a complete Frappe development environment in a single step. Downloads compose files, starts containers, initializes bench, creates a site, and starts the bench's dev services.
 
+Blocks for roughly 10-20 minutes (image pulls, bench init, site creation). Running several `cwcli init` invocations in parallel can OOM-kill the host on a memory-constrained machine - serialize them instead. Adding a bench to an already-running instance (`cwcli init existing-project --bench another-bench`) never disturbs it or its other benches: the frappe container is never pulled, recreated, or restarted, so every already-serving bench keeps running throughout.
+
 ```bash
 cwcli init [OPTIONS] [PROJECT_NAME]
 ```
@@ -894,6 +937,7 @@ cwcli inspect [OPTIONS] PROJECT_NAME
 
 | Option | Description |
 |--------|-------------|
+| `--bench <index\|label>` | Narrow the report to one bench on a multi-bench project (its numeric index or label). Every bench is still discovered/refreshed/cached regardless; only the output is narrowed |
 | `-v`, `--verbose` | Enable verbose diagnostic output |
 | `-j`, `--json` | Output the result as a JSON object |
 | `-u`, `--update` | Update the cache by re-inspecting the project |
@@ -948,6 +992,9 @@ cwcli inspect frappe-one --no-refresh
 # Get JSON output
 cwcli inspect frappe-one --json
 
+# Narrow the report to one bench in a multi-bench project
+cwcli inspect frappe-one --bench 1
+
 # Interactively label each bench (durable handle for --bench)
 cwcli inspect frappe-one --interactive
 ```
@@ -1981,6 +2028,7 @@ This is the same class of exposure as SSH agent forwarding or VS Code's own cred
 Every request is written to an audit log (`~/.cwcli/run/credbridge-audit.log`, one line per request: timestamp, instance, host, answered - never a credential byte).
 For a tighter blast radius, authenticate `gh`/`glab` with a fine-grained, expiring token scoped to only the repos you need; the bridge faithfully forwards whatever the host tools hold, so the token's reach is your auth choice.
 On a shared multi-user host, note the per-instance socket lives in the instance's workspace directory under `~/.cwcli/projects/<name>/data/`; `enable` tightens `~/.cwcli/projects` to owner-only (0700) for exactly that reason.
+This per-user daemon is distinct from the **machine-wide** bridge of an opt-in [shared install](#shared-multi-user-install): there the daemon runs once as the `cwcli` service account (started by a system unit at boot), serves a single machine-owned read-only service-account token, and its socket is `0660 root:cwcli` so a uid outside the `cwcli` group cannot reach it. See that section for the security consequences.
 
 **Host allowlist:** the daemon only answers credential requests for `github.com` and `gitlab.com` by default.
 Using a self-hosted GitLab (or GitHub Enterprise)?
@@ -2257,8 +2305,11 @@ cwcli axi scale frappe-one --to 8 --yes
 # Every site carries installed_apps_verified: true only on a full read - the
 # cache/partial tiers carry a site's apps (and their git refs) forward without
 # re-observing them, so a non-full read with a remembered app list also warns.
+# --bench <index|label> narrows the report to one bench (every tier still
+# refreshes/caches every bench regardless; only the emitted report is narrowed).
 cwcli axi inspect frappe-one
 cwcli axi inspect frappe-one --update
+cwcli axi inspect frappe-one --bench 1
 
 # List a project's benches with their indices and labels. This is what answers
 # "pass --bench <index|label>" from any other verb - no other verb can.
@@ -2324,7 +2375,7 @@ cwcli axi config
 cwcli axi doctor
 ```
 
-`cwcli axi ls`, `cwcli axi where`, `cwcli axi backup`, `cwcli axi unlock`, `cwcli axi stop`, `cwcli axi start`, `cwcli axi status`, `cwcli axi restart`, `cwcli axi inspect`, `cwcli axi benches`, and `cwcli axi label` run on the same logic core as their human counterparts; only the output (always TOON, never JSON) and choice-handling differ. `cwcli axi start` never prompts: an ambiguous multi-bench project is a `--bench` usage error (exit 2), and an unresolved port conflict is a `CONFLICT` error naming `--yes` (exit 1). `cwcli axi unlock` follows `cwcli axi backup`'s conventions exactly: an ambiguous multi-bench project is a `--bench` usage error (exit 2) and a stopped instance is a usage error pointing at `cwcli start` (exit 2). `cwcli axi stop` is idempotent for an agent - stopping an already-stopped project is a success, not an error. `cwcli axi where` answers from the cache, which outlives the instances it describes, so every match carries `project_state` (`present`, `absent`, or `unverified`) and the document carries `verified`: an agent must read those before acting on a hit, because an `absent` row describes an instance that no longer exists and an `unverified` row means the liveness check could not run. An unreachable Docker daemon degrades the whole answer to `unverified` rather than vouching for it, and `--no-verify` skips the check (reporting `unverified`) when a caller has already established liveness. `cwcli axi status` always exits 0, leading with the instance `overall` aggregate (`offline`/`online`/`running`/`degraded`). It reports **every** bench, in one document, under `benches[N]` - with no `--bench` it used to refuse a multi-bench project with exit 2 and send you off to `cwcli axi benches` to poll once per bench, reassembling the instance view from documents that never said which bench they described. The shape is uniform, so `supervisor_up`, `web_http_code`, `processes` and `not_cwcli_supervised` live inside `benches[i]` even for a single-bench project (`benches[0].processes`), and there is one parse path rather than a branch on bench count. Each bench also carries `bench_present` (`present`/`absent`/`unverified`) - the bench LIST comes from the cache, and a bench whose directory was deleted has no marker and no supervisord, which is indistinguishable from one that was simply never started, so it used to read as `online`; the token answers that, and `overall` keeps its four tokens. Each bench also carries `index`, `bench_path`, `label`, its own `overall`, `web_port`/`web_port_verified` (the port that bench's `web_http_code` was actually measured on), and `web_site` (the site it was measured FOR - Frappe routes by `Host`, so the code belongs to that site, and a probe naming no site is answered `404` by a healthy bench). When that port cannot be read it is `null`/`false` and **no probe was made** - cwcli never falls back to `:8000`, because on a multi-bench instance that reports a different bench's web server as this one's. A stopped instance carries `benches: []`. `cwcli axi stop` takes `--bench <index|label>` to stop ONE bench's dev processes, leaving sibling benches and every container running - the inverse of `cwcli axi start --bench`; without it, it stops the whole instance's containers, and either form is idempotent. `cwcli axi restart` requires `--process`; an unknown/ambiguous process is a usage error listing the valid labels (exit 2). `cwcli axi inspect` serves whichever freshness tier answers the request (`served_from` names it) and, unlike every other bench-scoped verb, has deliberately NO `--yes` - a stopped project on the refresh path is a usage error (exit 2) naming `cwcli start`, and a drift escalation that can no longer discover the bench serves the cached data with `degraded: true` and a warning (exit 0). Every site also carries `installed_apps_verified`: only a full read actually re-observes an app's installed version and git ref, so a cache or partial read carries the remembered list forward unverified and, when that list is non-empty, adds a warning naming `--update` - an agent must not treat an unverified `installed_apps` entry as the live git state. `cwcli axi benches` is the discovery verb behind every other verb's `--bench`: when a bench-scoped verb reports "multiple benches; pass `--bench <index|label>`", this is what tells you the valid values, and a project that has never been inspected is a structured error naming `cwcli axi inspect` rather than an empty list. Its rows come from the cache, which outlives the benches it describes, so every row carries `state` (`present`, `absent`, or `unverified`) and the document carries `verified` - the same contract `cwcli axi where` uses, cross-checked here against the running container in one exec. An agent must read `state` before acting on a row: `absent` means that bench directory no longer exists, and `unverified` means the check could not run (a stopped project, an unreachable daemon, or `--no-verify`) - never a confirmation. A stale row is reported, never pruned; `cwcli axi inspect <project> --update` is what refreshes it. `cwcli axi label` never starts a stopped project (the label marker lives inside the bench), and listing is deliberately `cwcli axi benches` rather than a mode of the mutation verb. `cwcli axi self-update --check` is read-only and **exits 0 whenever the check succeeds, including when an update is available** - the answer is the `is_outdated` field, not the exit code, because on the agent surface a non-zero exit means an error. This deliberately differs from the human `cwcli self-update --check`, which exits 1 when an update is available so shell scripts can gate on it; the mutating `cwcli axi self-update` is deliberately not offered. `cwcli axi config` is the read-only counterpart of `cwcli config show`: one TOON document carrying the search paths, all three auto-inspect state stores, the credential-bridge state, the tips setting, and the file locations. **No config-mutating axi verbs exist** (no `paths add`/`remove`, no `cache clear`, no `auto-inspect enable`/`disable`): an agent rewriting the user's search paths or wiping the cache is a product decision that deserves its own evidence, so mutations stay on the human `cwcli config` surface (whose reads all have `--json`). `cwcli axi doctor` is the read-only, system-wide counterpart of `cwcli doctor`: one TOON document listing every check with a machine-readable `status` (`pass`/`warn`/`fail`) an agent gates on directly, never by parsing the `detail` text. It exits 0 whenever every check is pass/warn and non-zero only when a check fails, exactly matching the human command, so a fleet can run it before driving any instance and `&&`-chain on the result.
+`cwcli axi ls`, `cwcli axi where`, `cwcli axi backup`, `cwcli axi unlock`, `cwcli axi stop`, `cwcli axi start`, `cwcli axi status`, `cwcli axi restart`, `cwcli axi inspect`, `cwcli axi benches`, and `cwcli axi label` run on the same logic core as their human counterparts; only the output (always TOON, never JSON) and choice-handling differ. `cwcli axi start` never prompts: an ambiguous multi-bench project is a `--bench` usage error (exit 2), and an unresolved port conflict is a `CONFLICT` error naming `--yes` (exit 1). `cwcli axi unlock` follows `cwcli axi backup`'s conventions exactly: an ambiguous multi-bench project is a `--bench` usage error (exit 2) and a stopped instance is a usage error pointing at `cwcli start` (exit 2). `cwcli axi stop` is idempotent for an agent - stopping an already-stopped project is a success, not an error. `cwcli axi where` answers from the cache, which outlives the instances it describes, so every match carries `project_state` (`present`, `absent`, or `unverified`) and the document carries `verified`: an agent must read those before acting on a hit, because an `absent` row describes an instance that no longer exists and an `unverified` row means the liveness check could not run. An unreachable Docker daemon degrades the whole answer to `unverified` rather than vouching for it, and `--no-verify` skips the check (reporting `unverified`) when a caller has already established liveness. `cwcli axi status` always exits 0, leading with the instance `overall` aggregate (`offline`/`online`/`running`/`degraded`). It reports **every** bench, in one document, under `benches[N]` - with no `--bench` it used to refuse a multi-bench project with exit 2 and send you off to `cwcli axi benches` to poll once per bench, reassembling the instance view from documents that never said which bench they described. The shape is uniform, so `supervisor_up`, `web_http_code`, `processes` and `not_cwcli_supervised` live inside `benches[i]` even for a single-bench project (`benches[0].processes`), and there is one parse path rather than a branch on bench count. Each bench also carries `bench_present` (`present`/`absent`/`unverified`) - the bench LIST comes from the cache, and a bench whose directory was deleted has no marker and no supervisord, which is indistinguishable from one that was simply never started, so it used to read as `online`; the token answers that, and `overall` keeps its four tokens. Each bench also carries `index`, `bench_path`, `label`, its own `overall`, `web_port`/`web_port_verified` (the port that bench's `web_http_code` was actually measured on), and `web_site` (the site it was measured FOR - Frappe routes by `Host`, so the code belongs to that site, and a probe naming no site is answered `404` by a healthy bench). When that port cannot be read it is `null`/`false` and **no probe was made** - cwcli never falls back to `:8000`, because on a multi-bench instance that reports a different bench's web server as this one's. A stopped instance carries `benches: []`. `cwcli axi stop` takes `--bench <index|label>` to stop ONE bench's dev processes, leaving sibling benches and every container running - the inverse of `cwcli axi start --bench`; without it, it stops the whole instance's containers, and either form is idempotent. `cwcli axi restart` requires `--process`; an unknown/ambiguous process is a usage error listing the valid labels (exit 2). `cwcli axi inspect` serves whichever freshness tier answers the request (`served_from` names it) and, unlike every other bench-scoped verb, has deliberately NO `--yes` - a stopped project on the refresh path is a usage error (exit 2) naming `cwcli start`, and a drift escalation that can no longer discover the bench serves the cached data with `degraded: true` and a warning (exit 0). It takes `--bench <index|label>` like every other bench-scoped verb, narrowing the emitted report to one bench; every tier still discovers/refreshes/caches every bench regardless of the selector, and an unknown selector is a `bench.not_found` error (exit 1). Every site also carries `installed_apps_verified`: only a full read actually re-observes an app's installed version and git ref, so a cache or partial read carries the remembered list forward unverified and, when that list is non-empty, adds a warning naming `--update` - an agent must not treat an unverified `installed_apps` entry as the live git state. `cwcli axi benches` is the discovery verb behind every other verb's `--bench`: when a bench-scoped verb reports "multiple benches; pass `--bench <index|label>`", this is what tells you the valid values, and a project that has never been inspected is a structured error naming `cwcli axi inspect` rather than an empty list. Its rows come from the cache, which outlives the benches it describes, so every row carries `state` (`present`, `absent`, or `unverified`) and the document carries `verified` - the same contract `cwcli axi where` uses, cross-checked here against the running container in one exec. An agent must read `state` before acting on a row: `absent` means that bench directory no longer exists, and `unverified` means the check could not run (a stopped project, an unreachable daemon, or `--no-verify`) - never a confirmation. A stale row is reported, never pruned; `cwcli axi inspect <project> --update` is what refreshes it. `cwcli axi label` never starts a stopped project (the label marker lives inside the bench), and listing is deliberately `cwcli axi benches` rather than a mode of the mutation verb. `cwcli axi self-update --check` is read-only and **exits 0 whenever the check succeeds, including when an update is available** - the answer is the `is_outdated` field, not the exit code, because on the agent surface a non-zero exit means an error. This deliberately differs from the human `cwcli self-update --check`, which exits 1 when an update is available so shell scripts can gate on it; the mutating `cwcli axi self-update` is deliberately not offered. `cwcli axi config` is the read-only counterpart of `cwcli config show`: one TOON document carrying the search paths, all three auto-inspect state stores, the credential-bridge state, the tips setting, and the file locations. **No config-mutating axi verbs exist** (no `paths add`/`remove`, no `cache clear`, no `auto-inspect enable`/`disable`): an agent rewriting the user's search paths or wiping the cache is a product decision that deserves its own evidence, so mutations stay on the human `cwcli config` surface (whose reads all have `--json`). `cwcli axi doctor` is the read-only, system-wide counterpart of `cwcli doctor`: one TOON document listing every check with a machine-readable `status` (`pass`/`warn`/`fail`) an agent gates on directly, never by parsing the `detail` text. It exits 0 whenever every check is pass/warn and non-zero only when a check fails, exactly matching the human command, so a fleet can run it before driving any instance and `&&`-chain on the result.
 
 `cwcli axi url <project>` answers two questions no other `axi` verb does: what HOST URL a bench actually serves on, and whether it is answering HTTP right now.
 `cwcli axi status`'s `web_http_code` is measured against the bench's CONTAINER-internal port and never states the host address; the host URL is computed only by `cwcli open`'s success banner and the human `cwcli init` banner, neither reachable from `cwcli axi`, so getting either answer meant dropping to a raw `docker inspect`/`curl` against the container.
@@ -2378,7 +2429,7 @@ It exits non-zero if a restart fails or the named site does not answer Frappe's
 
 These are agent-only for now: there is no human `cwcli migrate`, `cwcli run-tests`, or `cwcli build` yet. Use `cwcli run <project> --site <site> migrate` for the human equivalent.
 
-`cwcli axi init` provisions a new instance, bench, and site the way `cwcli init` does, but non-interactively and as ONE terminal TOON document. It **blocks** for the full 10-20 minute run - the same block-and-emit-one-document shape as `cwcli axi apps update`, because a progress stream would break the one-TOON-document contract - narrating coarse phase labels to stderr; run `cwcli logs <project>` / `cwcli status <project>` from a second shell for live progress. After the bench+site is created, it starts the bench's dev services by default (the same `core.start` behind `cwcli start`/`cwcli axi start`), leaving a running bench rather than a created-but-idle one; `--no-start` creates without starting, for automation/CI, distinct from Docker container startup (stage 1 always brings the containers up regardless of this flag). A dev-services start failure degrades to a stderr warning rather than a non-zero exit, since the bench was already created. The site administrator password comes from the **`CWCLI_ADMIN_PASSWORD` environment variable (recommended)** or `--admin-password`; the flag wins if both are set, and with neither set the verb refuses with a usage error (exit 2) naming both - it never generates a password and never prompts. The env var keeps the secret off the process argv (visible in `ps`/shell history) that the flag exposes; the container-side `bench new-site` still receives it, so treat the value as one-time. The MariaDB root password takes the same shape via `CWCLI_DB_ROOT_PASSWORD` / `--db-root-password` (default `123`). The interactive decisions the human `cwcli init` prompts for become non-prompting errors: an existing bench with neither `--reuse-bench` nor `--no-reuse-bench` is a usage error (exit 2) naming both; a port conflict names `--port` (exit 1); containers that do not come up point at `cwcli status`/`cwcli logs` (exit 1). There is no `--auto-start` (compose `cwcli axi start` then re-run) and no `--verbose` (stdout is always TOON). `--bench` here is the NAME of the bench to create, distinct from the `--bench <index|label>` selector the other verbs use.
+`cwcli axi init` provisions a new instance, bench, and site the way `cwcli init` does, but non-interactively and as ONE terminal TOON document. It **blocks** for the full 10-20 minute run - the same block-and-emit-one-document shape as `cwcli axi apps update`, because a progress stream would break the one-TOON-document contract - narrating coarse phase labels to stderr; run `cwcli logs <project>` / `cwcli status <project>` from a second shell for live progress. Running several `axi init` calls in parallel can OOM-kill the host on a memory-constrained machine - serialize them instead. Adding a bench to an already-running instance never disturbs it or its other benches: the frappe container is never pulled, recreated, or restarted, so every already-serving bench keeps running throughout. After the bench+site is created, it starts the bench's dev services by default (the same `core.start` behind `cwcli start`/`cwcli axi start`), leaving a running bench rather than a created-but-idle one; `--no-start` creates without starting, for automation/CI, distinct from Docker container startup (stage 1 always brings the containers up regardless of this flag). A dev-services start failure degrades to a stderr warning rather than a non-zero exit, since the bench was already created. The site administrator password comes from the **`CWCLI_ADMIN_PASSWORD` environment variable (recommended)** or `--admin-password`; the flag wins if both are set, and with neither set the verb refuses with a usage error (exit 2) naming both - it never generates a password and never prompts. The env var keeps the secret off the process argv (visible in `ps`/shell history) that the flag exposes; the container-side `bench new-site` still receives it, so treat the value as one-time. The MariaDB root password takes the same shape via `CWCLI_DB_ROOT_PASSWORD` / `--db-root-password` (default `123`). The interactive decisions the human `cwcli init` prompts for become non-prompting errors: an existing bench with neither `--reuse-bench` nor `--no-reuse-bench` is a usage error (exit 2) naming both; a port conflict names `--port` (exit 1); containers that do not come up point at `cwcli status`/`cwcli logs` (exit 1). There is no `--auto-start` (compose `cwcli axi start` then re-run) and no `--verbose` (stdout is always TOON). `--bench` here is the NAME of the bench to create, distinct from the `--bench <index|label>` selector the other verbs use.
 
 `cwcli axi rm <project> --yes` permanently removes an instance: its containers, named volumes (databases, sites, and files), own Docker Compose network, and local project directory.
 It is the agent form of `cwcli rm`, and it runs the same code.

{caffeinated_whale_cli-3.0.0 → caffeinated_whale_cli-3.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "caffeinated-whale-cli"
-version = "3.0.0"
+version = "3.1.0"
 authors = [
   { name = "Christopher McKay", email = "mckay.christopher73@outlook.com" },
 ]
@@ -80,12 +80,18 @@ select = [
     "N",   # pep8-naming
     "UP",  # pyupgrade
     "B",   # flake8-bugbear
+    "TID251",  # banned API imports and access
 ]
 ignore = [
     "E501",  # line too long (handled by black)
     "B008",  # function call in default argument (required for Typer)
 ]
 
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+"typer._click" = { msg = "Use Typer's public API instead of its private Click shim." }
+"importlib.import_module" = { msg = "Dynamic imports are forbidden. For a justified exception, add `# noqa: TID251` on that line." }
+"builtins.__import__" = { msg = "The __import__ dynamic import is forbidden. For a justified exception, add `# noqa: TID251` on that line." }
+
 [tool.mypy]
 python_version = "3.10"
 warn_return_any = true

caffeinated_whale_cli-3.1.0/src/caffeinated_whale_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "3.1.0"

{caffeinated_whale_cli-3.0.0 → caffeinated_whale_cli-3.1.0}/src/caffeinated_whale_cli/commands/axi.py

@@ -23,7 +23,6 @@ stderr; stdout carries only TOON.
 
 from __future__ import annotations
 
-import importlib
 import os
 import re
 import sys
@@ -74,32 +73,34 @@ from ..utils import agent_hooks, cache, toon
 # rendering axi-surface parse failures as the same `error:`+`help:` TOON the core
 # errors already use, while leaving the human CLI's rich rendering untouched.
 #
-# Typer >= ~0.17 VENDORS Click as `typer._click`, so a TyperGroup then raises that
-# vendored ClickException/UsageError/Abort - a DIFFERENT class hierarchy from the
+# Typer >= ~0.17 VENDORS Click, so a TyperGroup then raises vendored
+# ClickException/UsageError/Abort - a DIFFERENT class hierarchy from the
 # separately-installed `click` package this module imports. `except click.X` then
 # silently misses them, and a bare `cwcli` (Missing command) escapes uncaught to
-# the top-level rich TRACEBACK instead of the intended usage error (exit 2). Catch
-# and type-test against BOTH flavors; older Typer (<= 0.16) has no `typer._click`
-# and uses standalone click alone. Deliberately paired with the protocol-based
-# `_is_argument`/`_is_option` param checks below, which vendored params also fail.
-try:
-    _vendored_click_exc = importlib.import_module("typer._click.exceptions")
-    _CLICK_EXCEPTIONS: tuple[type[click.ClickException], ...] = (
-        click.ClickException,
-        _vendored_click_exc.ClickException,
-    )
-    _USAGE_ERRORS: tuple[type[click.UsageError], ...] = (
-        click.UsageError,
-        _vendored_click_exc.UsageError,
-    )
-    _ABORTS: tuple[type[click.exceptions.Abort], ...] = (
-        click.exceptions.Abort,
-        _vendored_click_exc.Abort,
-    )
-except ModuleNotFoundError:  # standalone click (Typer <= 0.16)
-    _CLICK_EXCEPTIONS = (click.ClickException,)
-    _USAGE_ERRORS = (click.UsageError,)
-    _ABORTS = (click.exceptions.Abort,)
+# the top-level rich TRACEBACK instead of the intended usage error (exit 2). So we
+# catch and type-test against BOTH flavors.
+#
+# Get the vendored bases from PUBLIC typer exports, never the private `typer._click`
+# module: its layout is not API and shifts across releases (typer 0.27 dropped
+# `Abort` from `typer._click.exceptions`, which crashed this import at module load).
+# `typer.Abort` is the vendored Abort; `typer.BadParameter` subclasses the vendored
+# `UsageError` -> `ClickException`, so its MRO yields those two bases by name. On
+# Typer <= 0.16 (standalone click) these resolve to the same classes as `click.*`,
+# and the sets below dedup - one code path, no version branch. Deliberately paired
+# with the protocol-based `_is_argument`/`_is_option` param checks below, which
+# vendored params also fail.
+_typer_exc_bases: dict[str, type[BaseException]] = {
+    cls.__name__: cls for cls in typer.BadParameter.__mro__ if issubclass(cls, BaseException)
+}
+_CLICK_EXCEPTIONS: tuple[type[click.ClickException], ...] = tuple(
+    {click.ClickException, cast("type[click.ClickException]", _typer_exc_bases["ClickException"])}
+)
+_USAGE_ERRORS: tuple[type[click.UsageError], ...] = tuple(
+    {click.UsageError, cast("type[click.UsageError]", _typer_exc_bases["UsageError"])}
+)
+_ABORTS: tuple[type[click.exceptions.Abort], ...] = tuple(
+    {click.exceptions.Abort, cast("type[click.exceptions.Abort]", typer.Abort)}
+)
 
 
 def _usage_error_message(error: click.UsageError) -> str:
@@ -1222,6 +1223,7 @@ def axi_inspect(
         "--no-refresh",
         help="Serve the cached data verbatim; zero container calls (may be stale).",
     ),
+    bench: str = typer.Option(None, "--bench", help="Which bench: numeric index or label."),
 ) -> None:
     """Inspect a project's benches, sites, and apps; emit the report as TOON.
 
@@ -1247,10 +1249,15 @@ def axi_inspect(
     Deliberately NO ``--yes``: an axi verb must never open a start-from-axi path.
     A stopped project on the refresh path is a usage error (exit 2) naming
     ``cwcli start``, matching every other stopped-project fork on this surface.
+
+    ``--bench <index|label>`` narrows the report to one bench (the same selector
+    ``axi status``/``axi logs``/``axi apps`` take); an unknown selector is a
+    ``bench.not_found`` error (exit 1). Every tier still refreshes/caches every
+    bench regardless of the selector - only the emitted report is narrowed.
     """
     refresh = "full" if update else ("cache_only" if no_refresh else "auto")
     try:
-        result = core_inspect.inspect(project, refresh=refresh)
+        result = core_inspect.inspect(project, refresh=refresh, bench=bench)
     except CwcliError as error:
         emit_axi_error(error)
         raise typer.Exit(exit_for(error.kind)) from None
@@ -2223,7 +2230,11 @@ def axi_init(
     update` blocks on a long update - streaming N documents would break the
     one-TOON-document contract. Coarse phase progress goes to STDERR; for live or
     deeper progress, run `cwcli logs <project>` / `cwcli status <project>` from a
-    second shell.
+    second shell. Running several `axi init` calls in parallel can OOM-kill the
+    host on a memory-constrained machine - serialize them. Adding a bench to an
+    already-running instance never disturbs it or its other benches: the frappe
+    container is never pulled, recreated, or restarted, so every already-serving
+    bench keeps running throughout.
 
     After the bench+site is created, dev services start by default (reusing the
     same `core.start` behind `cwcli start`/`axi start`), so this leaves a running

{caffeinated_whale_cli-3.0.0 → caffeinated_whale_cli-3.1.0}/src/caffeinated_whale_cli/commands/init.py

@@ -562,6 +562,13 @@ def init(
     Creates project directory, downloads compose files, starts containers,
     initializes bench, and creates a site. Optionally installs ERPNext.
 
+    Blocks for roughly 10-20 minutes (image pulls, bench init, site creation).
+    Running several `cwcli init` invocations in parallel can OOM-kill the host
+    on a memory-constrained machine - serialize them instead. Adding a bench
+    to an already-running instance never disturbs it or its other benches:
+    the frappe container is never pulled, recreated, or restarted, so every
+    already-serving bench keeps running throughout.
+
     If project_name is not provided, prompts interactively.
 
     The site's administrator password is generated and printed once when

{caffeinated_whale_cli-3.0.0 → caffeinated_whale_cli-3.1.0}/src/caffeinated_whale_cli/commands/inspect.py

@@ -83,6 +83,11 @@ def inspect(
     project_name: str = typer.Argument(
         ..., help="The Docker Compose project to inspect.", autocompletion=complete_project_names
     ),
+    bench: str = typer.Option(
+        None,
+        "--bench",
+        help="Narrow the report to one bench: its numeric index or label (multi-bench projects).",
+    ),
     verbose: bool = typer.Option(
         False, "--verbose", "-v", help="Enable verbose diagnostic output."
     ),
@@ -122,6 +127,11 @@ def inspect(
     """
     Inspects a Project to find all Bench Instances, Sites, and Apps within it.
     Caches the results for faster subsequent inspects.
+
+    ``--bench <index|label>`` narrows the report to one bench, on a multi-bench
+    project. Every tier still discovers/refreshes/caches every bench regardless
+    of the selector - only the rendered output is narrowed. An unknown selector
+    exits non-zero.
     """
     if verbose:
         console_err.print(f"VERBOSE: --- Inspecting Project: {project_name} ---")
@@ -141,6 +151,7 @@ def inspect(
                     refresh=refresh,
                     offer_choice=prompt_to_start,
                     on_event=on_event,
+                    bench=bench,
                 )
         except CwcliError as e:
             raise render_error_exit(project_name, e) from None
@@ -185,13 +196,14 @@ def inspect(
             )
 
         assignments: list[tuple[str, str]] = []
-        for position, bench in enumerate(bench_instances_data):
-            index = bench.get("index", position)
-            existing = bench.get("label")
+        for position, bench_instance in enumerate(bench_instances_data):
+            index = bench_instance.get("index", position)
+            existing = bench_instance.get("label")
             existing_hint = f" [current: '{existing}']" if existing else ""
             try:
                 answer = questionary.text(
-                    f"Bench [{index}] at {bench['path']} on '{project_name}'.{existing_hint}\n"
+                    f"Bench [{index}] at {bench_instance['path']} on '{project_name}'."
+                    f"{existing_hint}\n"
                     "Label (blank to keep, letters/digits/.-_ only): "
                 ).ask()
                 if answer is None:  # User pressed Ctrl+C
@@ -205,7 +217,7 @@ def inspect(
                 continue
 
             if answer.strip():  # Blank keeps the existing label.
-                assignments.append((bench["path"], answer))
+                assignments.append((bench_instance["path"], answer))
 
         label_result = core_label.set_labels(project_name, assignments)
         for warning in label_result.warnings: