caffeinated-whale-cli 3.1.2__tar.gz → 3.2.0__tar.gz

{caffeinated_whale_cli-3.1.2 → caffeinated_whale_cli-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: caffeinated-whale-cli
-Version: 3.1.2
+Version: 3.2.0
 Summary: A CLI tool to help manage Frappe Docker instances.
 Author-email: Christopher McKay <mckay.christopher73@outlook.com>
 License: MIT
@@ -254,6 +254,7 @@ cwcli init [OPTIONS] [PROJECT_NAME]
 | `-b`, `--bench TEXT` | Bench directory name inside the container (default: frappe-bench) |
 | `-s`, `--site TEXT` | Primary site name: any hostname/FQDN or IPv4 address (default: development.localhost). `.localhost` names are recommended for local development - they resolve to the machine without DNS. A real domain or IP is accepted too; init prints a one-line note reminding you it must resolve to this machine for browser access |
 | `--bench-parent TEXT` | Directory inside container where bench is created (default: /workspace); also the container mount point for the persisted host `data/` directory, fixed for the life of the instance - changing it on a re-init errors, naming the mounted directory |
+| `--bench-image-tag TEXT` | Pin the `frappe/bench` Docker image to this exact tag (e.g. `v5.29.1`), skipping the Docker Hub latest-tag lookup entirely. Omit to use the short-lived cached tag or a fresh lookup |
 | `--frappe-branch TEXT` | Frappe branch or tag for bench init, e.g. `version-16` or `v16.26.3` (default: version-16). Mutually exclusive with `--version` |
 | `--version TEXT` | Frappe version for bench init, resolved by shape: a bare major (`16` → `version-16` branch) or a full semantic version (`16.26.3` → `v16.26.3` tag). Malformed values are rejected with a non-zero exit. Mutually exclusive with `--frappe-branch` |
 | `--frappe-url TEXT` | Custom Frappe repository URL to build from (a fork), passed to `bench init --frappe-path`. Omit to use the default `frappe/frappe` repo. Pair with `--frappe-branch` to check out the fork's branch. A private fork authenticates through the same credential bridge as `apps install`/`apps update` (host `gh`/`glab`, no token in the container); sign in on the host first |
@@ -264,6 +265,7 @@ cwcli init [OPTIONS] [PROJECT_NAME]
 | `--auto-start` | Automatically start containers if not running |
 | `--start` / `--no-start` | After creating the bench+site, start its dev services (supervisord over `bench start`) so init leaves a running dev environment (default: `--start`). `--no-start` creates without starting, for automation/CI. Distinct from `--auto-start`, which only controls Docker container startup |
 | `--reuse-bench` / `--no-reuse-bench` | Pre-answer the existing-bench question non-interactively: `--reuse-bench` reuses the bench and skips `bench init`; `--no-reuse-bench` requires a fresh `--bench` name and errors if it already exists. Default: ask interactively (a non-TTY without either flag refuses). Distinct from `--auto-start`, which controls container startup |
+| `--uid INTEGER` | Override the uid/gid the container's `frappe` user is aligned to, instead of the host's own uid/gid. Mainly for a root-uid host (e.g. a CI runner running as uid 0), where a root host already falls back to a safe default automatically (see step 7 below); pass `--uid` to choose a specific uid instead. Must be a positive, non-root integer (`--uid 0`, negatives, and non-numeric values are rejected with a usage error before any container or file work). Applies only to this init invocation, including its end-of-init auto-start; it is never persisted, so later `cwcli start`/`restart` do not take it |
 | `-v`, `--verbose` | Show verbose output with streaming command execution |
 
 **What It Does:**
@@ -272,9 +274,9 @@ cwcli init [OPTIONS] [PROJECT_NAME]
 2. Downloads `docker-compose.yml` from frappe_docker GitHub repository
 3. Customizes port mappings based on `--port` flag
 4. Binds the bench workspace to a host `~/.cwcli/projects/{project_name}/data/` directory at `--bench-parent` inside the container (default `/workspace`), so bench files stay directly accessible on the host and survive container recreation
-5. Resolves the latest stable `frappe/bench` image tag from Docker Hub (never uses `:latest`)
+5. Resolves the `frappe/bench` image tag to pin (never uses `:latest`): `--bench-image-tag` is used verbatim and skips the lookup; otherwise a short-lived on-disk cache serves repeated inits and only a cache miss queries Docker Hub for the latest stable tag
 6. Pulls Docker images and starts containers
-7. On hosts that expose uid/gid information, aligns the container's `frappe` user to the host user so bench files written to the mounted workspace stay host-owned and removable by `cwcli rm` (no-op when the ids already match; platforms without `os.getuid`, such as Windows, cleanly skip alignment because Docker Desktop handles bind-mount ownership; a failed attempted remap degrades to a warning and bench creation still proceeds)
+7. On hosts that expose uid/gid information, aligns the container's `frappe` user to the host user so bench files written to the mounted workspace stay host-owned and removable by `cwcli rm` (no-op when the ids already match; platforms without `os.getuid`, such as Windows, cleanly skip alignment because Docker Desktop handles bind-mount ownership; a failed attempted remap degrades to a warning and bench creation still proceeds). On a **root host** (uid 0, a common CI-runner shape) the container `frappe` user is **not** remapped to 0 - that would collide with the container's own root user and break bench's `PATH` (`bench init` fails with exit 127) - so it falls back to the image's default uid (1000) and says so once in a warning; root can still remove those files, so `cwcli rm` keeps working. Pass `--uid <n>` to align to a specific uid instead
 8. Pins the correct Python version via `PYENV_VERSION` for the branch (installs via pyenv if missing)
 9. Pins the correct Node.js version via nvm for older branches (installs via nvm if missing)
 10. Installs `yarn` globally for the activated Node.js version (older branches only)
@@ -778,6 +780,7 @@ The same fail-closed refusal applies when Docker cannot verify whether named vol
 If Docker confirms that no named volumes remain, no backup is needed: `cwcli rm` cleans up the orphan's network and local directory under the default settings.
 The volume state is checked again before cleanup, and any change or verification failure aborts instead of risking unbacked data.
 Under `--no-volumes` no volume data is destroyed, so a stopped project is cleaned up without a backup as before.
+A half-provisioned instance that holds no site on any bench has nothing to back up, so - like a confirmed volume-free orphan - the removal proceeds instead of refusing and sending you back for a second `--no-backup` run; this relaxes only on a *live* proof that every bench is site-less, and any ambiguity keeps the fail-closed refusal.
 
 ```bash
 cwcli rm [OPTIONS] [PROJECT_NAME]...
@@ -808,7 +811,7 @@ If a project has no containers but still has a network, named volumes, or a loca
 Confirmed volume-free orphans are cleaned under the defaults.
 Orphans with named volumes, or an unknown volume state, remain protected by the backup gate.
 
-An invalid project name (empty, `.`, `..`, an absolute path, or one containing a path separator) is rejected before anything is removed, since such a name could otherwise escape the projects directory.
+An invalid project name (empty, blank/whitespace-only, `.`, `..`, an absolute path, or one containing a path separator) is rejected before anything is removed, since such a name could otherwise escape the projects directory or resolve to a phantom project; a blank name is reported as `(empty)` rather than an empty quote.
 `cwcli rm` exits non-zero whenever any removal step fails, including a blocked backup, a rejected name, or a container, volume, network, or directory that could not be removed.
 It does not print the success summary for a project that was not fully removed; the project stays in the cache (and `cwcli ls`) so the leftover state remains visible and can be retried.
 
@@ -1013,6 +1016,9 @@ This means an app you just installed is picked up automatically, without a manua
 If nothing changed, the cached data is served unchanged; if that pass detects a change, it transparently falls back to a full re-inspect so the per-site installed-app lists are refreshed too.
 Use `--no-refresh` to skip the pass and return the cached data as-is (fastest, but possibly stale), or `--update` to force a full re-inspect.
 
+**App-copy flags:** on a full inspect (not a cache-served read) `inspect` flags an app whose `apps/<app>` is a symlink (showing the real directory) and, more seriously, an app whose imported copy differs from `apps/<app>` (the bench imports a different copy, so the site runs code that changes to `apps/<app>` never reach).
+These are live-observed and not persisted to the cache.
+
 **Security Note:** The cache never stores Frappe secrets. Site and common configurations are whitelist-filtered before they are written, so database passwords, per-site encryption keys, admin/root passwords, and Redis URLs are stripped and never persisted (nothing reads them back from the cache - every credential consumer reads live from the container or from CLI flags/prompts). Any cache written before this behavior shipped is cleaned in place on the next run. As defense-in-depth, the cache is also stored with restricted filesystem permissions (directory: `0700`, database: `0600`) so only the current user can read it; still, do not share the cache directory (`~/.cwcli/cache/`) with untrusted users.
 
 ```bash
@@ -1230,17 +1236,18 @@ After a successful mutation the bench's cached app lists are refreshed so `where
 
 ```bash
 cwcli apps list [OPTIONS] PROJECT_NAME
-cwcli apps install [OPTIONS] PROJECT_NAME --app APP [--app APP ...]
+cwcli apps install [OPTIONS] PROJECT_NAME [APP ...]   # or -a/--app APP
 cwcli apps uninstall [OPTIONS] PROJECT_NAME --app APP [--app APP ...]
 cwcli apps update [OPTIONS] PROJECT_NAME APPS...
 cwcli apps checkout [OPTIONS] PROJECT_NAME APP REF
 ```
 
 **`apps list`** - lists apps available in the bench (live `ls apps/`); with `--installed`/`--site` it also lists the apps installed per site (all sites by default, grouped by site).
+It flags an app whose `apps/<app>` is a symlink (naming the real directory it points at) and, more seriously, an app whose imported copy differs from `apps/<app>` (the bench's Python actually imports a different copy, so operating on `apps/<app>` leaves the site running stale code); in `--json` an `app_copies` array carries the same detail for any flagged app.
 
 **`apps install`** - ensures each app is present on the bench, then installs it on the target site(s).
-An app absent from `apps/` is fetched with `bench get-app` (honoring `--branch`); an app already present is not fetched again, so pre-warmed benches install it without failing on the existing directory.
-Each `--app` is a known app name **or** a git URL (passed straight to `bench get-app` when a fetch is needed, so custom apps not in bench's registry work); repeat `--app` to install more than one.
+An app absent from `apps/` is fetched with `bench get-app` (honoring `--branch`); an app already present **and registered** (in `sites/apps.txt`) is not fetched again, so pre-warmed benches install it without failing on the existing directory. A present directory that is *not* a valid install - the leftover of an earlier fetch that cloned but failed at its `pip install` step - is refused with an actionable message telling you to remove it and re-run, rather than reporting a false "get-app ok" and then dumping a raw install traceback on every retry. When a fresh fetch itself fails, the partial `apps/<app>` directory it created is removed so a retry genuinely re-fetches (a pre-existing app directory is never touched).
+Each app is a known app name **or** a git URL (passed straight to `bench get-app` when a fetch is needed, so custom apps not in bench's registry work). Apps may be given positionally (matching `apps update`/`apps checkout` and `axi apps install`) or with `-a`/`--app`; both forms combine, and repeat either to install more than one.
 `--fetch-only` ensures the app is present without installing it on any site.
 `--if-not-present` makes install idempotent: an app already installed on a target site is skipped (reported, not reinstalled, with its install hooks never rerun) and the command still exits 0, so "ensure this app is installed" is a single call whose exit code a script can trust; an app the site does not have is still installed normally, and a genuine install failure still exits non-zero.
 A bench that is already running may still serve code it loaded before the install and fail to see the new app: install therefore **resynchronises** that bench - it restarts every cwcli-supervised program that runs the bench's Python (`web`, `schedule`, and every worker) and requires every changed site to answer Frappe before it reports success.
@@ -1254,6 +1261,8 @@ A bench that was not running is left alone.
 
 **`apps update`** - the canonical app-update path (what the deprecated `cwcli update` now delegates to). Updating the `frappe` framework app runs `bench update --reset`; other apps use the normal git-pull + migrate flow. After the migrations finish and maintenance mode is lifted, it runs the same **resynchronise** step as `apps install`, so a `git pull` cannot leave the bench's web, scheduler, and workers on the code that was there before it; every migrated site must answer Frappe before the run reports success. `--site` narrows which affected sites are migrated; if none of the named site(s) actually have the app installed, the command refuses and exits non-zero rather than silently migrating nothing (a genuine typo/mismatch guard - a bench with no affected sites at all still exits zero). It accepts the same migration flags as the [deprecated `update` command](#update---update-apps-and-migrate) (`--clear-cache`, `--clear-website-cache`, `--build`, `--skip-maintenance`, `--no-recache`). When updating the `frappe` framework app the flow runs the bench-wide `bench update --reset`, so `--site` and those per-app migration flags do not apply and are reported as ignored.
 `--force` is an opt-in, **destructive** recovery for a conflicting update: if an app's `git pull` hits a **conflict** (local changes that would be overwritten, or a conflicted merge), it hard-resets that app to its remote tracking branch (`git fetch` then `git reset --hard @{u}`), discarding the local changes, so the update completes instead of failing. It fires **only on a conflict** - a clean update is untouched, and a pull that failed for another reason (network, auth) is left as the failure it is rather than having work discarded. Without `--force`, a conflict fails safely and discards nothing. Every force-reset app is reported (`force_reset_apps`) and a warning is printed at the reset. `--force` does not delete untracked files (it never runs `git clean`), matching `apps checkout --reset`. `--force` also clears a git **"dubious ownership"** refusal before pulling: when an app's repository is owned by a different user than the container runs as - common on a shared-mode or migrated instance whose app sources are owned by a pre-migration uid - it re-owns the repository to the container user so the pull proceeds, rather than surfacing a raw git ownership error. A `cwcli start`/`cwcli restart` self-heals the same ownership so a plain `apps update` works too; `--force` fixes it inline without a restart.
+When `apps/<app>` is a symlink, the update writes through it and the run names the real directory it operated on.
+After the pull, update verifies that the copy the bench actually imports is the copy it just updated; when they differ it does **not** report plain success - it warns, names both paths, and exits non-zero so a script notices the site is still running the other copy.
 
 **`apps checkout`** - fetches and checks out an arbitrary branch, tag, or commit (`REF`) into an app that is **already present** in the bench (`apps/<app>`), so a specific feature branch can be put under test in the instance the app lives in.
 Unlike `apps install` (bench acquisition when needed, then site installation) and `apps update` (the tracked upstream on every app), this targets one existing checkout: it runs `git fetch <remote> <ref>` then `git checkout -B <ref> FETCH_HEAD` in the app directory (the remote is auto-detected - `upstream` for a bench-installed app, `origin` for a hand-cloned one).
@@ -1267,8 +1276,9 @@ Dirty means precisely **anything `git status --porcelain` reports: staged change
 Files matched by `.gitignore` are not reported by git and so never count, which is why ordinary build residue (`__pycache__`, `node_modules`, `*.egg-info`) does not block a checkout.
 `--reset` is the explicit opt-in through that refusal: it hard-resets the working tree to the fetched ref, discarding tracked local edits, which guarantees the clean tree a subsequent `build`/`migrate` needs.
 Note one honest limit: `--reset` does **not** delete untracked files, because cwcli never runs `git clean` - it lets the checkout proceed and leaves them where they are.
+Like `apps update`, checkout names the real directory when `apps/<app>` is a symlink, and after moving the tree it verifies the bench imports the copy it just changed; if the bench imports a different copy it warns, names both paths, and exits non-zero rather than reporting a checkout the site will not actually run.
 
-**Private repos:** `apps install`/`apps update`/`apps checkout` (and the deprecated `update`), plus any bench subcommand run through [`cwcli run`](#run---execute-bench-commands) (`cwcli run <project> get-app <private-url>`, `cwcli run <project> update --pull`), transparently authenticate git fetches against private GitHub/GitLab app repos through your host's already-signed-in `gh`/`glab` - nothing to configure, no token ever stored in the container, and public repos are unaffected. Sign in on the host first (`gh auth login` / `glab auth login`). To extend this to **interactive** git inside `cwcli open` or a `docker exec` shell (not just cwcli's own operations), opt into the persistent [`config cred-bridge`](#config-cred-bridge---persistent-credential-bridge).
+**Private repos:** `apps install`/`apps update`/`apps checkout` (and the deprecated `update`), plus any bench subcommand run through [`cwcli run`](#run---execute-bench-commands) (`cwcli run <project> get-app <private-url>`, `cwcli run <project> update --pull`), transparently authenticate git fetches against private GitHub/GitLab app repos through your host's already-signed-in `gh`/`glab` - nothing to configure, no token ever stored in the container, and public repos are unaffected. Sign in on the host first (`gh auth login` / `glab auth login`). This credential bridge only serves operations run **through cwcli**; a raw `git` you run yourself inside the container (in a `docker exec` shell, or `cwcli open`) is not bridged and will prompt or fail auth. Run the fetch through `cwcli run <project> <bench-args>` instead, or - to bridge **interactive** git inside `cwcli open` or a `docker exec` shell (not just cwcli's own operations) - opt into the persistent [`config cred-bridge`](#config-cred-bridge---persistent-credential-bridge).
 
 **Common Options:**
 
@@ -1276,7 +1286,7 @@ Note one honest limit: `--reset` does **not** delete untracked files, because cw
 |--------|-------------|
 | `--bench TEXT` | Which bench to target: its numeric index or label (see [Working with Multiple Benches](#working-with-multiple-benches)) |
 | `-p`, `--path TEXT` | Explicit bench directory inside the container (lower-level alternative to `--bench`) |
-| `-a`, `--app TEXT` | App name (`install` also accepts a git URL); repeatable and required for `install`/`uninstall` |
+| `-a`, `--app TEXT` | App name (`install` also accepts a git URL); repeatable. Required for `uninstall`; for `install` the app may instead be given positionally |
 | `--site TEXT` | Target site(s); repeatable. Omit for all sites (list/install/uninstall) or all affected sites (update) |
 | `--json` | Machine-readable JSON output (for `install`/`uninstall`, includes the per-`(app, site)` results; for `update`, the full per-phase report). Stdout carries only the document - bench output never corrupts it |
 | `-y`, `--yes` | Auto-start stopped containers without prompting; for `uninstall`, also skip the destructive confirmation |
@@ -1291,8 +1301,8 @@ cwcli apps list frappe-one
 # List apps installed across every site, as JSON
 cwcli apps list frappe-one --installed --json
 
-# Install ERPNext on every site of the bench
-cwcli apps install frappe-one --app erpnext
+# Install ERPNext on every site of the bench (positional app, or -a/--app)
+cwcli apps install frappe-one erpnext
 
 # Install more than one app in the same call
 cwcli apps install frappe-one --app erpnext --app hrms
@@ -1423,7 +1433,7 @@ cwcli unlock [OPTIONS] PROJECT_NAME
 
 | Option | Description |
 |--------|-------------|
-| `-s`, `--site TEXT` | Site name to unlock. If not provided, uses the default site (from `common_site_config.json`'s `default_site` or `sites/currentsite.txt`) |
+| `-s`, `--site TEXT` | Site name to unlock. If not provided, uses the default site (from `common_site_config.json`'s `default_site` or `sites/currentsite.txt`), falling back to the sole site of a single-site bench |
 | `--bench TEXT` | Which bench to target: its numeric index or label (see [Working with Multiple Benches](#working-with-multiple-benches)) |
 | `-p`, `--path TEXT` | Explicit bench directory inside the container (lower-level alternative to `--bench`; cannot be combined with it) |
 | `-y`, `--yes` | Auto-start stopped containers without prompting |
@@ -1435,9 +1445,9 @@ Removes the `{bench_path}/sites/{site_name}/locks` directory, which can help res
 A site with no locks folder is reported as an honest "already unlocked" success rather than a generic "unlocked" message.
 
 **Smart Defaults:**
-- If `--site` is not specified, automatically uses your bench's default site (from `common_site_config.json`'s `default_site`, or `sites/currentsite.txt` when that key is absent)
-- Shows "Using default site: {site}" when using the default
-- Run `cwcli inspect {project}` first to cache the configuration
+- If `--site` is not specified, uses your bench's configured default site (from `common_site_config.json`'s `default_site`, or `sites/currentsite.txt` when that key is absent); when no default is configured it falls back to the sole site of a single-site bench (the shape a fresh `cwcli init` leaves)
+- A multi-site bench with no configured default still requires `--site`, and the error lists the available sites
+- Shows "Using site '{site}'" when the site was resolved for you
 
 **Examples:**
 
@@ -1445,9 +1455,9 @@ A site with no locks folder is reported as an honest "already unlocked" success
 # Unlock a specific site
 cwcli unlock my-project --site development.localhost
 
-# Use default site (no --site flag needed)
+# Use the resolved site (no --site flag needed)
 cwcli unlock my-project
-# Output: Using default site: development.localhost
+# Output: Using site 'development.localhost'
 
 # Verbose mode with default site
 cwcli unlock my-project -v
@@ -1498,7 +1508,7 @@ cwcli backup [OPTIONS] PROJECT_NAME
 
 | Option | Description |
 |--------|-------------|
-| `-s`, `--site TEXT` | Site name to back up. If not provided, uses the default site (from `common_site_config.json`'s `default_site` or `sites/currentsite.txt`) |
+| `-s`, `--site TEXT` | Site name to back up. If not provided, uses the default site (from `common_site_config.json`'s `default_site` or `sites/currentsite.txt`), falling back to the sole site of a single-site bench; a multi-site bench with no default requires `--site` and the error lists the sites |
 | `--bench TEXT` | Which bench to target: its numeric index or label (see [Working with Multiple Benches](#working-with-multiple-benches)) |
 | `-p`, `--path TEXT` | Explicit bench directory inside the container (lower-level alternative to `--bench`; cannot be combined with it) |
 | `--with-files` | Include public and private files in the backup |
@@ -1541,7 +1551,7 @@ cwcli restore [OPTIONS] PROJECT_NAME
 
 | Option | Description |
 |--------|-------------|
-| `-s`, `--site TEXT` | Site name to restore. If not provided, uses the default site (from `common_site_config.json`'s `default_site` or `sites/currentsite.txt`) |
+| `-s`, `--site TEXT` | Site name to restore. If not provided, uses the default site (from `common_site_config.json`'s `default_site` or `sites/currentsite.txt`), falling back to the sole site of a single-site bench; a multi-site bench with no default requires `--site` and the error lists the sites |
 | `--latest` | Non-interactive: select the most recent backup set for the target site (bypasses the backup menu). A non-TTY without any selector exits non-zero instead of hanging |
 | `--backup-file TEXT` | Non-interactive: select the backup set whose database file matches this filename (or full container path). Bypasses the backup menu |
 | `--bench TEXT` | Which bench to target: its numeric index or label (see [Working with Multiple Benches](#working-with-multiple-benches)) |
@@ -1618,7 +1628,7 @@ cwcli restore my-project --site production.localhost --latest --yes \
 **Example Session:**
 
 ```
-Using default site: development.localhost
+Using site 'development.localhost'
 
 ? Select a backup to restore: (Use arrow keys)
 
@@ -1831,14 +1841,14 @@ read from that bench's `sites/common_site_config.json`, which is what bench's ow
 `make_ports` writes - so a bench's HTTP code always describes that bench.
 
 ```bash
-cwcli status [OPTIONS] PROJECT_NAME
+cwcli status [OPTIONS] [PROJECT_NAME]
 ```
 
 **Arguments:**
 
 | Argument | Description |
 |----------|-------------|
-| `PROJECT_NAME` | The Docker Compose project name to check (required) |
+| `PROJECT_NAME` | The Docker Compose project name to check. Omit it for the all-instances summary (the same table `cwcli ls` gives) - a bare `cwcli status` reads like "how is everything", not a missing-argument error |
 
 **Options:**
 
@@ -1879,15 +1889,20 @@ is a gap in cwcli's knowledge, not a fault in the bench.
 `Host` header, so a request naming no site is correctly answered `404` by a
 perfectly healthy bench - which is what `status` used to report on every read. The
 probe now sends the bench's site as its `Host`, so a healthy bench reads `200`, and
-the report says which site it asked for (`web_site`, shown as `web <site>:<port> ->
-<code>`). That keeps the code attributable the same way the port does: it is that
-site's code, not a claim about the bench as a whole. A bench with no site recorded
-probes without a `Host` header, as before, and reports `web_site: null`.
+the report says which site it asked for (`web_site`). That keeps the code
+attributable the same way the port does: it is that site's code, not a claim about
+the bench as a whole. A bench with no site recorded probes without a `Host` header,
+as before, and reports `web_site: null`. The human `cwcli status` web line shows the
+**host-reachable** address (`web <site>:<host-port> -> <code>`) - the same one the
+init banner and `cwcli axi url` print, so it is copy-pasteable - resolved by mapping
+the bench's container web port through the container's live host bindings; when that
+host binding cannot be resolved it falls back to the container port labelled
+`(in-container)` so nobody tries to open an unreachable address.
 
 A truly-nonexistent project name (a typo, or one never created - no containers
-with the label at all) is NOT `offline`: it exits non-zero with a "no such
-project" error on stderr, so a script can tell a stopped instance apart from a
-name that does not exist.
+with the label at all) is NOT `offline`: it exits non-zero with a "Project
+'<name>' not found." error on stderr, so a script can tell a stopped instance apart
+from a name that does not exist.
 
 **Not under cwcli supervision:** if a bench is running but was NOT started by
 cwcli's supervisord - a plain `bench start`, or an instance already running before
@@ -1900,9 +1915,20 @@ hint to run `cwcli start` to bring it under cwcli's supervisor. In this mode the
 per-process supervisord `state` is unavailable (there is no supervisord to ask);
 `up` comes straight from `ps`. `status` only reads - it never launches supervisord.
 
+**Maintenance mode is called out plainly.** A site stuck in maintenance mode answers
+HTTP 503 to every user with no other signal - the state a `migrate` / `apps update`
+killed mid-run (a closed terminal, a `kill`, a service stop) leaves behind. When a
+bench's site is in maintenance mode, `status` prints `MAINTENANCE MODE ON` for that
+site (even without `-v`, since it is a fault, not detail) and names the way out
+(`cwcli run <project> --site <site> set-maintenance-mode off`); `cwcli axi status`
+carries it as `maintenance_mode` plus a `status.maintenance_mode` warning. It is read
+live from the site's `site_config.json`, not inferred from the 503, and is skipped in
+the `--watch` loop (which makes no web probe).
+
 **Per-bench, per-process detail (stderr):** one sub-block per bench, headed by its
-index, path, label, and own aggregate, with a web line naming the port that was
-actually probed (`web :8001 -> 404`). Beneath each, every Procfile process (`web`, `socketio`,
+index, path, label, and own aggregate, with a web line naming the host-reachable
+address that was probed (`web dev.localhost:17001 -> 200`, or the container port
+labelled `(in-container)` when the host binding cannot be resolved). Beneath each, every Procfile process (`web`, `socketio`,
 `worker`, `schedule`, `watch`, `redis_cache`, `redis_queue`) with up/down plus
 its PID, uptime, CPU%, RSS, and supervisord's authoritative `state`
 (`RUNNING`/`STARTING`/`BACKOFF`/`EXITED`/`FATAL`/`STOPPED`) - so a crash-looping or
@@ -2034,11 +2060,17 @@ cwcli config paths                          # list, one path per line
 cwcli config paths --json                   # the same list as JSON
 cwcli config paths add /home/user/benches   # absolute paths only
 cwcli config paths remove /home/user/benches
+cwcli config paths prune                    # dry-run: list dead paths
+cwcli config paths prune --yes              # actually drop them
 ```
 
 `add` refuses a non-absolute path with a usage error (exit 2) after `~` expansion, and normalizes before duplicate detection, so `/a/b` and `/a/b/` are one entry, not two.
 Adding an already-present path and removing an absent one are both no-op successes (exit 0, saying which no-op occurred).
 
+`prune` removes custom search paths that no live instance references (they accumulate a graveyard: a path added for an instance later removed lingers forever and is re-scanned on every `inspect`).
+It checks each path live against every instance's frappe container and, with `--yes`, drops the ones absent from all of them; without `--yes` it is a dry-run that only lists what it would drop (`--json` for machine output).
+It is fail-closed: a path present in any instance is never dropped, and if any instance cannot be checked (stopped or unreachable) nothing is pruned, so a path a stopped instance still needs is never lost.
+
 ##### `config cache` - Manage Cache
 
 Manages the cache for project inspection data.
@@ -2137,11 +2169,12 @@ Honestly stated: the allowlist keeps the long-lived channel from silently wideni
 
 **Cred-Bridge Subcommands:**
 
-- **`enable [--startup/--no-startup]`** - Enable the bridge AND start its background daemon, in one verb
+- **`enable [--project <name>] [--startup/--no-startup]`** - Enable the bridge AND start its background daemon, in one verb
   - Idempotent; missing `gh`/`glab` is a warning, not a refusal (the bridge simply answers nothing until a tool is installed and authenticated).
-  - Takes effect on any running instance immediately, and self-heals onto each instance on the next `cwcli open`/`cwcli start`/`cwcli run`.
-  - `--startup` also installs an automatic start at system boot/login (LaunchAgent on macOS, systemd user service on Linux, Task Scheduler on Windows) - this covers reopening VS Code straight after a reboot, before any cwcli verb has run. `--no-startup` removes the boot unit; omit both to leave it untouched.
-  - Example: `cwcli config cred-bridge enable --startup`
+  - Takes effect immediately on every currently-running instance cwcli manages (a Frappe container cwcli did not create is never touched), and self-heals onto each instance on the next `cwcli open`/`cwcli start`/`cwcli run`. When the default sweep wires more than one instance it names them, so an operator on a multi-instance machine is never surprised.
+  - `--project <name>` scopes the sweep to the named instance(s) (repeatable; an unknown name is the usual `not found` error, and a running container cwcli does not manage is refused rather than wired). Omit it to wire every running managed instance.
+  - `--startup` also installs an automatic start at system boot/login (LaunchAgent on macOS, systemd user service on Linux, Task Scheduler on Windows) - this covers reopening VS Code straight after a reboot, before any cwcli verb has run. `--no-startup` removes the boot unit; omit both to leave it untouched. If the boot unit cannot be installed (for example a host with no systemd user session), the bridge still enables and runs - the message says so and names `cwcli config cred-bridge start` for a manual start.
+  - Example: `cwcli config cred-bridge enable --project my-instance --startup`
 
 - **`disable`** - Stop the daemon, set enabled = false, make every wired shim inert, and remove the boot unit (non-destructive; an `enable` recreates everything)
   - Example: `cwcli config cred-bridge disable`
@@ -2521,7 +2554,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. 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 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); an invalid `--uid` (0, negative, or non-numeric) is rejected before any container work. `--uid` behaves as it does on `cwcli init` (including the root-host fallback, whose one-time warning is folded into the report's `warnings`). 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.