caffeinated-whale-cli 2.2.0__tar.gz → 2.3.1__tar.gz

{caffeinated_whale_cli-2.2.0 → caffeinated_whale_cli-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: caffeinated-whale-cli
-Version: 2.2.0
+Version: 2.3.1
 Summary: A CLI tool to help manage Frappe Docker instances.
 Author-email: Christopher McKay <mckay.christopher73@outlook.com>
 License: MIT
@@ -320,15 +320,19 @@ Then open http://development.localhost:8000 (or `cwcli open my-project`).
 If the dev services fail to start, init still exits successfully (the bench was already created) and prints a warning telling you to run `cwcli start` yourself.
 The start itself waits for the web server to answer on the bench's own configured port before declaring success; if that times out, init reports the same "not running" output even though the containers and supervisor did launch, since the web isn't actually serving yet.
 If the port cannot be read, start skips the wait and warns instead of probing another bench's port.
+If the web server is running inside the container but its port is not published to the host, init prints a warning naming the missing host binding and advises recreating the instance.
 
 **Port Conflict Handling:**
 
-If the requested ports are in use, you'll see:
+Init retries occupied ports five times, one second apart, to allow bindings from a just-removed instance to finish releasing.
+Each retry is announced in both interactive and non-interactive runs.
+If the ports remain occupied, init exits nonzero before creating the instance and names every conflicting port:
 
 ```
 Error: The following ports are already in use: 8000-8005
 
-Tip: Use the --port flag to select a different starting port.
+Tip: If an instance using these ports was just removed, they may still be releasing - wait a few seconds and retry.
+Tip: Otherwise, use the --port flag to select a different starting port.
 Example: cwcli init my-project --port 10000
 ```
 
@@ -498,6 +502,7 @@ cwcli start [OPTIONS] [PROJECT_NAME]...
 - **Idempotent:** a re-run on an already-running bench is a clean no-op ("already running: N/N processes up"), never a second supervisor stack
 - **Per-process supervision:** each Procfile process runs under supervisord, so one can be restarted or auto-healed without disturbing the others
 - **Waits for the web server:** on a genuine launch, `start` blocks until the bench's **own** web port actually answers before reporting the bench as running, so a scripted `cwcli start && cwcli status` never catches a transient `degraded`. The port is read from that bench's `sites/common_site_config.json`, never assumed - waiting on a hardcoded `:8000` meant `--bench 1` watched bench 0's port and then warned that a healthy bench had not started. If the port cannot be read, the wait is **skipped** (`web_ready` stays unset) rather than spent on a guess. A timeout (60s) does not fail the start (the stack IS launched) - it prints a warning naming the real port and telling you to check `cwcli status` / `cwcli logs`
+- **Host port verification:** on both a genuine launch and an idempotent no-op, `start` warns when the bench's web server has no live host port binding. The warning names the container port and advises recreating the instance with `cwcli init`
 - **Port Conflict Detection:** Automatically checks if required ports are available
 - **Interactive Resolution:** Offers to stop conflicting Frappe projects (use `--yes` to auto-confirm)
 - **Process Identification:** Shows which processes are using ports (cross-platform)
@@ -1114,14 +1119,24 @@ 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).
 
-**`apps install`** - fetches (`bench get-app`, honoring `--branch`) and installs each app on the target site(s). Each `APP` is a known app name **or** a git URL (passed straight to `bench get-app`, so custom apps not in bench's registry work). `--fetch-only` fetches without installing on any site. 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. Each restart is announced as it happens and the step is reported as a `restart-processes` row, and the command exits non-zero rather than claiming success for a site it could not confirm. A running manager that cwcli does not own is verified without being restarted; an unhealthy site fails with a manual-restart remedy. `socketio`, `watch`, and the redis programs are deliberately left alone: they import no Frappe app, and cycling redis would drop the cache and the job queue for nothing. Restarting a worker does interrupt a job in flight, which is the honest cost of not leaving background jobs running code that no longer exists. A bench that was not running is left alone.
+**`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).
+`--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.
+Each restart is announced as it happens and the step is reported as a `restart-processes` row, and the command exits non-zero rather than claiming success for a site it could not confirm.
+A running manager that cwcli does not own is verified without being restarted; an unhealthy site fails with a manual-restart remedy.
+`socketio`, `watch`, and the redis programs are deliberately left alone: they import no Frappe app, and cycling redis would drop the cache and the job queue for nothing.
+Restarting a worker does interrupt a job in flight, which is the honest cost of not leaving background jobs running code that no longer exists.
+A bench that was not running is left alone.
 
 **`apps uninstall`** - removes each app from the target site(s) (`bench --site <site> uninstall-app`). This destroys site data, so it is gated by `-y`/`--yes` or an interactive confirmation (a non-TTY without `--yes` refuses). It uses the same resynchronise-and-verify step as install, so no supervised process - web, scheduler, or worker - can keep running against the code and tables of an app that is gone.
 
 **`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.
 
 **`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` (a fresh `bench get-app` clone) 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).
+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).
 A **dirty working tree is refused** before anything is fetched, so uncommitted work in the in-instance checkout is never carried across a branch switch.
 Once the checkout step moves the tree, the command runs the same **resynchronise** step `apps install` uses, even if a later `--reset` step fails.
 Swapping the code under a running bench and leaving it serving the branch you just moved off is the quietest form of that defect, because nothing errors at all.
@@ -2224,16 +2239,19 @@ cwcli axi apps update frappe-one erpnext
 cwcli axi apps update frappe-one frappe          # runs 'bench update --reset'
 
 # Put ONE branch, tag, or commit under test in an app already in the bench -
-# the gap 'apps install' (a fresh clone) and 'apps update' (the tracked
+# the gap 'apps install' (bench acquisition and site installation) and 'apps update' (the tracked
 # upstream) leave. Add --reset to force a clean tree at the fetched ref.
 cwcli axi apps checkout frappe-one myapp feature/new-thing
 cwcli axi apps checkout frappe-one myapp feature/new-thing --reset
 
-# Fetch and install ONE app on ONE named site. --site is required (there is no
+# Ensure and install ONE app on ONE named site. --site is required (there is no
 # fan-out here), and an app already installed on that site is refused rather
-# than re-installed over its existing data.
+# than reinstalled over its existing data unless --if-not-present requests a skip.
 cwcli axi apps install frappe-one hrms --site erp.localhost
 cwcli axi apps install frappe-one https://github.com/me/myapp --site erp.localhost --branch develop
+# Idempotent: skip (do not reinstall) an app already on the site and exit 0, so a
+# CI step can trust the exit code. A real install failure still exits non-zero.
+cwcli axi apps install frappe-one hrms --site erp.localhost --if-not-present
 
 # Provision a new instance, bench, and site; the report prints as ONE TOON
 # document. BLOCKS for the full 10-20 minute run (like axi apps update) and
@@ -2278,9 +2296,9 @@ Use `cwcli open`'s banner for the host address and `cwcli status` for the HTTP o
 
 `cwcli axi apps list` is the read that answers what is *on* the bench `cwcli axi benches` names: the bench's available apps, and with `--installed`/`--site` which apps are installed on which site (only the app name, never the version column `bench list-apps` prints). A site whose read FAILED is reported as `null` and exits `1`, never as an empty list - "has no apps" and "could not tell" are different facts, and only one of them is safe to act on. Like every other bench-scoped verb it takes `--bench`, has no `--yes`, and reports a stopped project as a usage error naming `cwcli start` (exit 2). **`cwcli axi apps uninstall` deliberately does not exist:** letting an agent drop the tables of a real site is a product decision that deserves its own evidence, not something settled as a side effect of moving code onto the logic core. Use the human `cwcli apps uninstall` (it has `--json` and honest exit codes) until that decision is taken. `cwcli axi apps install` was held under that same shared rationale and now exists, scoped to the half of it that rationale never covered - see below.
 
-`cwcli axi apps checkout <project> <app> <ref>` puts ONE named branch, tag, or commit under test in an app that is already in the bench - the gap `apps install` (a fresh `bench get-app` clone) and `apps update` (the tracked upstream on every app) leave. It emits the same per-step TOON report as the other `apps` verbs, one row per git step, and its exit code reads that report's `ok`, so a refused checkout exits `1` rather than looking like a success. **It existed before `apps install` did and while `apps uninstall` still does not, and that was deliberate rather than inconsistent:** their shared deferral names one threat, an agent destroying site data (uninstalling an app drops its tables), while a checkout runs `git fetch` then `git checkout -B` inside the app's source directory - no bench command, no site, no SQL. Its guards each protect against something named: there is no `--yes` (an agent must not start containers you deliberately stopped, so a stopped project is a usage error pointing at `cwcli start`); the app must already be a git checkout, so a typo'd name errors instead of silently doing nothing or implying an install; and a **dirty working tree is refused outright**, before anything is fetched, so your uncommitted edits are never carried across a branch switch. That refusal is deliberately **stronger than git's own**: git blocks only a checkout that would overwrite a modified file, which used to let a non-conflicting edit ride silently onto another ref. It matters here because these checkouts live in a shared dev instance, where the work carried across may not even be yours. Be precise about what counts as dirty: **anything `git status --porcelain` reports - staged changes, unstaged modifications to tracked files, and untracked files** - refuses. Untracked files count because a new module written but not yet added is uncommitted work, and it is exactly the case where the tool must not decide for you that the file is worthless; `.gitignore`d build residue is not reported by git at all, so it never blocks a checkout. `--reset` is the explicit opt-in through the refusal: it is the one destructive flag, is never implied, and is reported as its own row in the output; it discards tracked local edits in the container's copy of the app, which is what the post-merge step of an app delivery workflow wants. It does **not** delete untracked files - cwcli never runs `git clean` - so it lets the checkout proceed and leaves them in place. Private-repo fetches use the same credential bridge as `apps install`/`apps update`, so no token is stored in the container. One current limit: the report does not tell you which commit you landed on - that is deliberately left to a future read verb rather than bolted onto the shared mutation report.
+`cwcli axi apps checkout <project> <app> <ref>` puts ONE named branch, tag, or commit under test in an app that is already in the bench - the gap `apps install` (bench acquisition when needed, then site installation) and `apps update` (the tracked upstream on every app) leave. It emits the same per-step TOON report as the other `apps` verbs, one row per git step, and its exit code reads that report's `ok`, so a refused checkout exits `1` rather than looking like a success. **It existed before `apps install` did and while `apps uninstall` still does not, and that was deliberate rather than inconsistent:** their shared deferral names one threat, an agent destroying site data (uninstalling an app drops its tables), while a checkout runs `git fetch` then `git checkout -B` inside the app's source directory - no bench command, no site, no SQL. Its guards each protect against something named: there is no `--yes` (an agent must not start containers you deliberately stopped, so a stopped project is a usage error pointing at `cwcli start`); the app must already be a git checkout, so a typo'd name errors instead of silently doing nothing or implying an install; and a **dirty working tree is refused outright**, before anything is fetched, so your uncommitted edits are never carried across a branch switch. That refusal is deliberately **stronger than git's own**: git blocks only a checkout that would overwrite a modified file, which used to let a non-conflicting edit ride silently onto another ref. It matters here because these checkouts live in a shared dev instance, where the work carried across may not even be yours. Be precise about what counts as dirty: **anything `git status --porcelain` reports - staged changes, unstaged modifications to tracked files, and untracked files** - refuses. Untracked files count because a new module written but not yet added is uncommitted work, and it is exactly the case where the tool must not decide for you that the file is worthless; `.gitignore`d build residue is not reported by git at all, so it never blocks a checkout. `--reset` is the explicit opt-in through the refusal: it is the one destructive flag, is never implied, and is reported as its own row in the output; it discards tracked local edits in the container's copy of the app, which is what the post-merge step of an app delivery workflow wants. It does **not** delete untracked files - cwcli never runs `git clean` - so it lets the checkout proceed and leaves them in place. Private-repo fetches use the same credential bridge as `apps install`/`apps update`, so no token is stored in the container. One current limit: the report does not tell you which commit you landed on - that is deliberately left to a future read verb rather than bolted onto the shared mutation report.
 
-`cwcli axi apps install <project> <app-or-git-url> --site <site>` fetches an app into the bench and installs it on one named site.
+`cwcli axi apps install <project> <app-or-git-url> --site <site>` ensures the app is present on the bench, fetching it only when absent, and installs it on one named site.
 Installing an app is the first step of essentially any Frappe app work, and until this verb existed it was the one routine operation with no agent-surface form, so an agent had to drop to the raw human command for it.
 It is deliberately narrower than the human `cwcli apps install`, in exactly two ways, because the original deferral of `apps install`/`apps uninstall` named a real threat - an agent destroying site data - that covers `uninstall` unconditionally but covers `install` only in one case.
 Installing an app a site does **not** have creates that app's own tables and touches no other app's data; installing over an app the site **already** has re-runs that app's install hooks against rows that already exist.
@@ -2290,14 +2308,15 @@ So the verb ships scoped to the first case and refuses the second, rather than b
 The human verb installs on every site on the bench when you omit it; an unqualified fan-out is how an agent reaches a site nobody named, so on this surface the target is always explicit.
 That follows `cwcli axi run-tests`, which requires its site for the same reason: `install-app` runs the app's `after_install`, which is arbitrary Python from the repository being installed, against a live database, and when the effect is unbounded, defaulting the target is the wrong default.
 
-**An app already installed on that site is refused**, before anything is fetched, as `app.already_installed` with exit `1`.
+**By default, an app already installed on that site is refused**, before anything is fetched, as `app.already_installed` with exit `1`.
 The refusal names what to do instead: `cwcli axi apps checkout` to move the app to another ref, `cwcli axi apps update` to pull and migrate it, or the human `cwcli apps install` for a genuine reinstall.
 A site whose installed-app list cannot be *read* is refused too (`app.install_state_unknown`), because an unreadable state must never be treated as "nothing is installed there".
-There is deliberately **no flag to bypass this**: a `--force` here has no beneficiary in the workflow the verb serves (install, check out a ref, migrate, test), and its mere existence invites its use.
-The escape hatch is the human verb, which is where a human confirms a reinstall.
+There is deliberately **no flag to bypass this by reinstalling**: a `--force` that re-ran the install hooks over existing data has no beneficiary in the workflow the verb serves (install, check out a ref, migrate, test), and its mere existence invites its use.
+The escape hatch for a genuine reinstall is the human verb, which is where a human confirms one.
 
-Note that the already-installed case is **not** reported as an idempotent exit-`0` no-op, even though the agent surface generally treats an already-satisfied desired state as a success.
-The desired state here is "installed from this branch", and cwcli cannot confirm the copy already on the site matches the `--branch` you asked for, so exiting `0` would be asserting something it has not verified.
+By default the already-installed case is **not** reported as an idempotent exit-`0` no-op, even though the agent surface generally treats an already-satisfied desired state as a success: the desired state here is "installed from this branch", and cwcli cannot confirm the copy already on the site matches the `--branch` you asked for, so a silent exit `0` would be asserting something it has not verified.
+`--if-not-present` opts into the idempotent reading for a caller that just wants the app present: an app already installed on the site is then **skipped** (reported as a `skip-install` row, with its install hooks never rerun) and the verb exits `0`, so a CI step can trust the exit code instead of swallowing every failure with `|| true`; an app the site lacks is still installed, and a genuine install failure still exits non-zero.
+It is not a `--force`: there is still no way to reinstall over an app the site already has.
 Like every other bench-scoped verb it takes `--bench`, has no `--yes`, and reports a stopped project as a usage error naming `cwcli start`.
 Private-repo fetches use the same credential bridge as `apps update`/`apps checkout`, so no token is stored in the container.
 On an already-serving bench, the operation resynchronises that bench - it restarts every supervised program running the bench's Python (`web`, `schedule`, workers) and reports a `restart-processes` row.

{caffeinated_whale_cli-2.2.0 → caffeinated_whale_cli-2.3.1}/README.md

@@ -280,15 +280,19 @@ Then open http://development.localhost:8000 (or `cwcli open my-project`).
 If the dev services fail to start, init still exits successfully (the bench was already created) and prints a warning telling you to run `cwcli start` yourself.
 The start itself waits for the web server to answer on the bench's own configured port before declaring success; if that times out, init reports the same "not running" output even though the containers and supervisor did launch, since the web isn't actually serving yet.
 If the port cannot be read, start skips the wait and warns instead of probing another bench's port.
+If the web server is running inside the container but its port is not published to the host, init prints a warning naming the missing host binding and advises recreating the instance.
 
 **Port Conflict Handling:**
 
-If the requested ports are in use, you'll see:
+Init retries occupied ports five times, one second apart, to allow bindings from a just-removed instance to finish releasing.
+Each retry is announced in both interactive and non-interactive runs.
+If the ports remain occupied, init exits nonzero before creating the instance and names every conflicting port:
 
 ```
 Error: The following ports are already in use: 8000-8005
 
-Tip: Use the --port flag to select a different starting port.
+Tip: If an instance using these ports was just removed, they may still be releasing - wait a few seconds and retry.
+Tip: Otherwise, use the --port flag to select a different starting port.
 Example: cwcli init my-project --port 10000
 ```
 
@@ -458,6 +462,7 @@ cwcli start [OPTIONS] [PROJECT_NAME]...
 - **Idempotent:** a re-run on an already-running bench is a clean no-op ("already running: N/N processes up"), never a second supervisor stack
 - **Per-process supervision:** each Procfile process runs under supervisord, so one can be restarted or auto-healed without disturbing the others
 - **Waits for the web server:** on a genuine launch, `start` blocks until the bench's **own** web port actually answers before reporting the bench as running, so a scripted `cwcli start && cwcli status` never catches a transient `degraded`. The port is read from that bench's `sites/common_site_config.json`, never assumed - waiting on a hardcoded `:8000` meant `--bench 1` watched bench 0's port and then warned that a healthy bench had not started. If the port cannot be read, the wait is **skipped** (`web_ready` stays unset) rather than spent on a guess. A timeout (60s) does not fail the start (the stack IS launched) - it prints a warning naming the real port and telling you to check `cwcli status` / `cwcli logs`
+- **Host port verification:** on both a genuine launch and an idempotent no-op, `start` warns when the bench's web server has no live host port binding. The warning names the container port and advises recreating the instance with `cwcli init`
 - **Port Conflict Detection:** Automatically checks if required ports are available
 - **Interactive Resolution:** Offers to stop conflicting Frappe projects (use `--yes` to auto-confirm)
 - **Process Identification:** Shows which processes are using ports (cross-platform)
@@ -1074,14 +1079,24 @@ 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).
 
-**`apps install`** - fetches (`bench get-app`, honoring `--branch`) and installs each app on the target site(s). Each `APP` is a known app name **or** a git URL (passed straight to `bench get-app`, so custom apps not in bench's registry work). `--fetch-only` fetches without installing on any site. 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. Each restart is announced as it happens and the step is reported as a `restart-processes` row, and the command exits non-zero rather than claiming success for a site it could not confirm. A running manager that cwcli does not own is verified without being restarted; an unhealthy site fails with a manual-restart remedy. `socketio`, `watch`, and the redis programs are deliberately left alone: they import no Frappe app, and cycling redis would drop the cache and the job queue for nothing. Restarting a worker does interrupt a job in flight, which is the honest cost of not leaving background jobs running code that no longer exists. A bench that was not running is left alone.
+**`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).
+`--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.
+Each restart is announced as it happens and the step is reported as a `restart-processes` row, and the command exits non-zero rather than claiming success for a site it could not confirm.
+A running manager that cwcli does not own is verified without being restarted; an unhealthy site fails with a manual-restart remedy.
+`socketio`, `watch`, and the redis programs are deliberately left alone: they import no Frappe app, and cycling redis would drop the cache and the job queue for nothing.
+Restarting a worker does interrupt a job in flight, which is the honest cost of not leaving background jobs running code that no longer exists.
+A bench that was not running is left alone.
 
 **`apps uninstall`** - removes each app from the target site(s) (`bench --site <site> uninstall-app`). This destroys site data, so it is gated by `-y`/`--yes` or an interactive confirmation (a non-TTY without `--yes` refuses). It uses the same resynchronise-and-verify step as install, so no supervised process - web, scheduler, or worker - can keep running against the code and tables of an app that is gone.
 
 **`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.
 
 **`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` (a fresh `bench get-app` clone) 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).
+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).
 A **dirty working tree is refused** before anything is fetched, so uncommitted work in the in-instance checkout is never carried across a branch switch.
 Once the checkout step moves the tree, the command runs the same **resynchronise** step `apps install` uses, even if a later `--reset` step fails.
 Swapping the code under a running bench and leaving it serving the branch you just moved off is the quietest form of that defect, because nothing errors at all.
@@ -2184,16 +2199,19 @@ cwcli axi apps update frappe-one erpnext
 cwcli axi apps update frappe-one frappe          # runs 'bench update --reset'
 
 # Put ONE branch, tag, or commit under test in an app already in the bench -
-# the gap 'apps install' (a fresh clone) and 'apps update' (the tracked
+# the gap 'apps install' (bench acquisition and site installation) and 'apps update' (the tracked
 # upstream) leave. Add --reset to force a clean tree at the fetched ref.
 cwcli axi apps checkout frappe-one myapp feature/new-thing
 cwcli axi apps checkout frappe-one myapp feature/new-thing --reset
 
-# Fetch and install ONE app on ONE named site. --site is required (there is no
+# Ensure and install ONE app on ONE named site. --site is required (there is no
 # fan-out here), and an app already installed on that site is refused rather
-# than re-installed over its existing data.
+# than reinstalled over its existing data unless --if-not-present requests a skip.
 cwcli axi apps install frappe-one hrms --site erp.localhost
 cwcli axi apps install frappe-one https://github.com/me/myapp --site erp.localhost --branch develop
+# Idempotent: skip (do not reinstall) an app already on the site and exit 0, so a
+# CI step can trust the exit code. A real install failure still exits non-zero.
+cwcli axi apps install frappe-one hrms --site erp.localhost --if-not-present
 
 # Provision a new instance, bench, and site; the report prints as ONE TOON
 # document. BLOCKS for the full 10-20 minute run (like axi apps update) and
@@ -2238,9 +2256,9 @@ Use `cwcli open`'s banner for the host address and `cwcli status` for the HTTP o
 
 `cwcli axi apps list` is the read that answers what is *on* the bench `cwcli axi benches` names: the bench's available apps, and with `--installed`/`--site` which apps are installed on which site (only the app name, never the version column `bench list-apps` prints). A site whose read FAILED is reported as `null` and exits `1`, never as an empty list - "has no apps" and "could not tell" are different facts, and only one of them is safe to act on. Like every other bench-scoped verb it takes `--bench`, has no `--yes`, and reports a stopped project as a usage error naming `cwcli start` (exit 2). **`cwcli axi apps uninstall` deliberately does not exist:** letting an agent drop the tables of a real site is a product decision that deserves its own evidence, not something settled as a side effect of moving code onto the logic core. Use the human `cwcli apps uninstall` (it has `--json` and honest exit codes) until that decision is taken. `cwcli axi apps install` was held under that same shared rationale and now exists, scoped to the half of it that rationale never covered - see below.
 
-`cwcli axi apps checkout <project> <app> <ref>` puts ONE named branch, tag, or commit under test in an app that is already in the bench - the gap `apps install` (a fresh `bench get-app` clone) and `apps update` (the tracked upstream on every app) leave. It emits the same per-step TOON report as the other `apps` verbs, one row per git step, and its exit code reads that report's `ok`, so a refused checkout exits `1` rather than looking like a success. **It existed before `apps install` did and while `apps uninstall` still does not, and that was deliberate rather than inconsistent:** their shared deferral names one threat, an agent destroying site data (uninstalling an app drops its tables), while a checkout runs `git fetch` then `git checkout -B` inside the app's source directory - no bench command, no site, no SQL. Its guards each protect against something named: there is no `--yes` (an agent must not start containers you deliberately stopped, so a stopped project is a usage error pointing at `cwcli start`); the app must already be a git checkout, so a typo'd name errors instead of silently doing nothing or implying an install; and a **dirty working tree is refused outright**, before anything is fetched, so your uncommitted edits are never carried across a branch switch. That refusal is deliberately **stronger than git's own**: git blocks only a checkout that would overwrite a modified file, which used to let a non-conflicting edit ride silently onto another ref. It matters here because these checkouts live in a shared dev instance, where the work carried across may not even be yours. Be precise about what counts as dirty: **anything `git status --porcelain` reports - staged changes, unstaged modifications to tracked files, and untracked files** - refuses. Untracked files count because a new module written but not yet added is uncommitted work, and it is exactly the case where the tool must not decide for you that the file is worthless; `.gitignore`d build residue is not reported by git at all, so it never blocks a checkout. `--reset` is the explicit opt-in through the refusal: it is the one destructive flag, is never implied, and is reported as its own row in the output; it discards tracked local edits in the container's copy of the app, which is what the post-merge step of an app delivery workflow wants. It does **not** delete untracked files - cwcli never runs `git clean` - so it lets the checkout proceed and leaves them in place. Private-repo fetches use the same credential bridge as `apps install`/`apps update`, so no token is stored in the container. One current limit: the report does not tell you which commit you landed on - that is deliberately left to a future read verb rather than bolted onto the shared mutation report.
+`cwcli axi apps checkout <project> <app> <ref>` puts ONE named branch, tag, or commit under test in an app that is already in the bench - the gap `apps install` (bench acquisition when needed, then site installation) and `apps update` (the tracked upstream on every app) leave. It emits the same per-step TOON report as the other `apps` verbs, one row per git step, and its exit code reads that report's `ok`, so a refused checkout exits `1` rather than looking like a success. **It existed before `apps install` did and while `apps uninstall` still does not, and that was deliberate rather than inconsistent:** their shared deferral names one threat, an agent destroying site data (uninstalling an app drops its tables), while a checkout runs `git fetch` then `git checkout -B` inside the app's source directory - no bench command, no site, no SQL. Its guards each protect against something named: there is no `--yes` (an agent must not start containers you deliberately stopped, so a stopped project is a usage error pointing at `cwcli start`); the app must already be a git checkout, so a typo'd name errors instead of silently doing nothing or implying an install; and a **dirty working tree is refused outright**, before anything is fetched, so your uncommitted edits are never carried across a branch switch. That refusal is deliberately **stronger than git's own**: git blocks only a checkout that would overwrite a modified file, which used to let a non-conflicting edit ride silently onto another ref. It matters here because these checkouts live in a shared dev instance, where the work carried across may not even be yours. Be precise about what counts as dirty: **anything `git status --porcelain` reports - staged changes, unstaged modifications to tracked files, and untracked files** - refuses. Untracked files count because a new module written but not yet added is uncommitted work, and it is exactly the case where the tool must not decide for you that the file is worthless; `.gitignore`d build residue is not reported by git at all, so it never blocks a checkout. `--reset` is the explicit opt-in through the refusal: it is the one destructive flag, is never implied, and is reported as its own row in the output; it discards tracked local edits in the container's copy of the app, which is what the post-merge step of an app delivery workflow wants. It does **not** delete untracked files - cwcli never runs `git clean` - so it lets the checkout proceed and leaves them in place. Private-repo fetches use the same credential bridge as `apps install`/`apps update`, so no token is stored in the container. One current limit: the report does not tell you which commit you landed on - that is deliberately left to a future read verb rather than bolted onto the shared mutation report.
 
-`cwcli axi apps install <project> <app-or-git-url> --site <site>` fetches an app into the bench and installs it on one named site.
+`cwcli axi apps install <project> <app-or-git-url> --site <site>` ensures the app is present on the bench, fetching it only when absent, and installs it on one named site.
 Installing an app is the first step of essentially any Frappe app work, and until this verb existed it was the one routine operation with no agent-surface form, so an agent had to drop to the raw human command for it.
 It is deliberately narrower than the human `cwcli apps install`, in exactly two ways, because the original deferral of `apps install`/`apps uninstall` named a real threat - an agent destroying site data - that covers `uninstall` unconditionally but covers `install` only in one case.
 Installing an app a site does **not** have creates that app's own tables and touches no other app's data; installing over an app the site **already** has re-runs that app's install hooks against rows that already exist.
@@ -2250,14 +2268,15 @@ So the verb ships scoped to the first case and refuses the second, rather than b
 The human verb installs on every site on the bench when you omit it; an unqualified fan-out is how an agent reaches a site nobody named, so on this surface the target is always explicit.
 That follows `cwcli axi run-tests`, which requires its site for the same reason: `install-app` runs the app's `after_install`, which is arbitrary Python from the repository being installed, against a live database, and when the effect is unbounded, defaulting the target is the wrong default.
 
-**An app already installed on that site is refused**, before anything is fetched, as `app.already_installed` with exit `1`.
+**By default, an app already installed on that site is refused**, before anything is fetched, as `app.already_installed` with exit `1`.
 The refusal names what to do instead: `cwcli axi apps checkout` to move the app to another ref, `cwcli axi apps update` to pull and migrate it, or the human `cwcli apps install` for a genuine reinstall.
 A site whose installed-app list cannot be *read* is refused too (`app.install_state_unknown`), because an unreadable state must never be treated as "nothing is installed there".
-There is deliberately **no flag to bypass this**: a `--force` here has no beneficiary in the workflow the verb serves (install, check out a ref, migrate, test), and its mere existence invites its use.
-The escape hatch is the human verb, which is where a human confirms a reinstall.
+There is deliberately **no flag to bypass this by reinstalling**: a `--force` that re-ran the install hooks over existing data has no beneficiary in the workflow the verb serves (install, check out a ref, migrate, test), and its mere existence invites its use.
+The escape hatch for a genuine reinstall is the human verb, which is where a human confirms one.
 
-Note that the already-installed case is **not** reported as an idempotent exit-`0` no-op, even though the agent surface generally treats an already-satisfied desired state as a success.
-The desired state here is "installed from this branch", and cwcli cannot confirm the copy already on the site matches the `--branch` you asked for, so exiting `0` would be asserting something it has not verified.
+By default the already-installed case is **not** reported as an idempotent exit-`0` no-op, even though the agent surface generally treats an already-satisfied desired state as a success: the desired state here is "installed from this branch", and cwcli cannot confirm the copy already on the site matches the `--branch` you asked for, so a silent exit `0` would be asserting something it has not verified.
+`--if-not-present` opts into the idempotent reading for a caller that just wants the app present: an app already installed on the site is then **skipped** (reported as a `skip-install` row, with its install hooks never rerun) and the verb exits `0`, so a CI step can trust the exit code instead of swallowing every failure with `|| true`; an app the site lacks is still installed, and a genuine install failure still exits non-zero.
+It is not a `--force`: there is still no way to reinstall over an app the site already has.
 Like every other bench-scoped verb it takes `--bench`, has no `--yes`, and reports a stopped project as a usage error naming `cwcli start`.
 Private-repo fetches use the same credential bridge as `apps update`/`apps checkout`, so no token is stored in the container.
 On an already-serving bench, the operation resynchronises that bench - it restarts every supervised program running the bench's Python (`web`, `schedule`, workers) and reports a `restart-processes` row.

{caffeinated_whale_cli-2.2.0 → caffeinated_whale_cli-2.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "caffeinated-whale-cli"
-version = "2.2.0"
+version = "2.3.1"
 authors = [
   { name = "Christopher McKay", email = "mckay.christopher73@outlook.com" },
 ]

caffeinated_whale_cli-2.3.1/src/caffeinated_whale_cli/__init__.py

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

{caffeinated_whale_cli-2.2.0 → caffeinated_whale_cli-2.3.1}/src/caffeinated_whale_cli/commands/apps.py

@@ -53,6 +53,9 @@ _ANNOUNCE = {
     "install-app": lambda app_name, site: (
         f"[bold cyan]Installing[/bold cyan] {app_name} on [magenta]{site}[/magenta]..."
     ),
+    "skip-install": lambda app_name, site: (
+        f"[dim]Skipping[/dim] {app_name} on [magenta]{site}[/magenta] (already installed)..."
+    ),
     "uninstall-app": lambda app_name, site: (
         f"[bold cyan]Uninstalling[/bold cyan] {app_name} from [magenta]{site}[/magenta]..."
     ),
@@ -267,7 +270,9 @@ def install_apps(
     project_name: str = typer.Argument(
         ..., help="The Docker Compose project name.", autocompletion=complete_project_names
     ),
-    apps: list[str] = typer.Argument(..., help="App name(s) or git URL(s) to fetch and install."),
+    apps: list[str] = typer.Argument(
+        ..., help="App name(s) or git URL(s) to ensure on the bench and install."
+    ),
     bench: str = typer.Option(
         None, "--bench", help="Which bench to target: its numeric index or label."
     ),
@@ -283,16 +288,28 @@ def install_apps(
         "--fetch-only",
         help="Fetch the app(s) into the bench without installing on any site.",
     ),
+    if_not_present: bool = typer.Option(
+        False,
+        "--if-not-present",
+        help=(
+            "Idempotent: skip (do not re-install) an app already installed on a "
+            "target site instead of re-running its install hooks. A skipped app is "
+            "reported and the command still exits 0."
+        ),
+    ),
     json_output: bool = typer.Option(False, "--json", help="Output as JSON."),
     yes: bool = typer.Option(
         False, "--yes", "-y", help="Auto-start stopped containers without prompting."
     ),
     verbose: bool = typer.Option(False, "--verbose", "-v", help="Enable verbose output."),
 ):
-    """Fetch (bench get-app) and install app(s) on the target site(s).
+    """Ensure app(s) are present on the bench, then install them on the target site(s).
 
-    Each app is a known app name OR a git URL (passed straight to bench get-app).
+    Apps absent from apps/ are fetched with bench get-app; apps already present skip
+    that fetch. Each app is a known app name OR a git URL.
     Multi-site by default: with no --site the app is installed on every site.
+    With --if-not-present an app already installed on a target site is skipped rather
+    than re-installed, so "ensure this app is installed" is a single idempotent call.
     """
     ensure_containers_running(project_name, require_running=True, verbose=verbose, auto_start=yes)
     resolved = _resolve_bench(project_name, bench, bench_path, verbose)
@@ -305,6 +322,7 @@ def install_apps(
             sites=sites,
             branch=branch,
             fetch_only=fetch_only,
+            if_not_present=if_not_present,
             on_event=_make_renderer(json_output=json_output, verbose=verbose),
         )
     except CwcliError as e:
@@ -322,13 +340,15 @@ def install_apps(
         _refresh_cache(project_name, verbose)
 
     # The banner must match what actually happened: only claim "installed" when an
-    # install-app step ran (not for --fetch-only or a bench with no sites).
-    installed = any(r.action == "install-app" for r in report.results)
-    _report_and_exit(
-        report,
-        json_output,
-        success_msg="App(s) installed." if installed else "App(s) fetched.",
-    )
+    # install-app step ran (not for --fetch-only, a bench with no sites, or an
+    # --if-not-present run that only skipped already-installed apps).
+    if any(r.action == "install-app" for r in report.results):
+        success_msg = "App(s) installed."
+    elif any(r.action == "skip-install" for r in report.results):
+        success_msg = "App(s) already installed; nothing to do."
+    else:
+        success_msg = "App(s) fetched."
+    _report_and_exit(report, json_output, success_msg=success_msg)
 
 
 # ------------------------------------------------------------------------ uninstall
@@ -450,7 +470,7 @@ def checkout_app(
 ):
     """Fetch and check out a branch/ref into an app already installed in the instance.
 
-    Unlike 'apps install' (a fresh get-app clone) and 'apps update' (the tracked
+    Unlike 'apps install' (bench acquisition and site installation) and 'apps update' (the tracked
     upstream on every app), this puts a specific feature branch, tag, or commit
     under test in the EXISTING apps/<app> checkout, authenticated for private repos
     through the same credential bridge as install/update. Use --reset to force a

{caffeinated_whale_cli-2.2.0 → caffeinated_whale_cli-2.3.1}/src/caffeinated_whale_cli/commands/axi.py

@@ -1563,7 +1563,7 @@ def axi_apps_checkout(
 ) -> None:
     """Fetch and check out a ref into an app already in the bench; emit the report as TOON.
 
-    The gap `apps install` (a fresh get-app clone) and `apps update` (the tracked
+    The gap `apps install` (bench acquisition and site installation) and `apps update` (the tracked
     upstream on every app) leave: putting ONE named branch, tag, or commit under
     test in the EXISTING apps/<app> checkout. There is no `axi run`, so this is
     the only agent-surface route to that step.
@@ -1665,15 +1665,27 @@ def axi_apps_install(
     # Named `app_name` because `app` is this module's Typer instance; the metavar
     # keeps the agent-visible usage line matching the human `cwcli apps install`.
     app_name: str = typer.Argument(
-        ..., metavar="APP", help="App name or git URL to fetch and install."
+        ..., metavar="APP", help="App name or git URL to ensure on the bench and install."
     ),
     site: str = typer.Option(
         ..., "--site", help="The single site to install on. Required: there is no fan-out here."
     ),
     bench: str = typer.Option(None, "--bench", help="Which bench: numeric index or label."),
     branch: str = typer.Option(None, "--branch", help="Git branch to fetch (passed to get-app)."),
+    if_not_present: bool = typer.Option(
+        False,
+        "--if-not-present",
+        help=(
+            "Idempotent: if the app is already installed on the site, skip it and "
+            "exit 0 instead of refusing. Does NOT re-install or re-run install "
+            "hooks - it only reports the app as already present."
+        ),
+    ),
 ) -> None:
-    """Fetch and install ONE app on ONE named site; emit the report as TOON.
+    """Ensure and install ONE app on ONE named site; emit the report as TOON.
+
+    An app absent from apps/ is fetched with bench get-app; an app already present
+    skips that fetch and proceeds to the site installation.
 
     Installing an app is the first step of essentially any Frappe app work, and
     without this verb it was the one routine operation with no agent-surface form,
@@ -1711,11 +1723,21 @@ def axi_apps_install(
     `axi migrate`'s absent `--skip-maintenance`. The escape hatch is the human verb,
     which is where a human confirms a reinstall.
 
-    The already-installed case is deliberately NOT reported as an idempotent exit-0
-    no-op, against the general AXI rule that an already-satisfied desired state is a
-    success. The desired state here is "installed FROM this branch", and cwcli
-    cannot confirm the copy already on the site matches the requested `--branch`, so
-    exit 0 would assert something it has not verified.
+    The already-installed case is, BY DEFAULT, deliberately NOT reported as an
+    idempotent exit-0 no-op, against the general AXI rule that an already-satisfied
+    desired state is a success. The desired state here is "installed FROM this
+    branch", and cwcli cannot confirm the copy already on the site matches the
+    requested `--branch`, so a silent exit 0 would assert something it has not
+    verified.
+
+    `--if-not-present` opts INTO the idempotent reading for a caller that just wants
+    the app present: an app already installed on the site is then SKIPPED (reported
+    as an `ok` `skip-install` row, its install hooks NOT re-run) and the verb exits
+    0. It is not a bypass of the safety the refusal guards - it never re-installs
+    over existing data - it is the honest "ensure installed" answer, so a CI step can
+    trust the exit code (a genuine install failure still exits 1) instead of
+    swallowing every failure with `|| true`. It is NOT a `--force`: there is still
+    no way to make the verb re-run install hooks over an app the site already has.
 
     NO --yes and no auto-start: a stopped project is a usage error naming
     `cwcli start`, as every bench-scoped axi verb already does. The private-repo
@@ -1731,7 +1753,10 @@ def axi_apps_install(
             sites=[site],
             branch=branch,
             auto_start=False,
-            require_absent=True,
+            # --if-not-present is the opt-in idempotent path; without it the
+            # already-installed refusal (require_absent) stays the default.
+            require_absent=not if_not_present,
+            if_not_present=if_not_present,
             on_event=_checkout_narrate,
         )
     except CwcliError as error:
@@ -2311,7 +2336,7 @@ def axi_init(
             )
         else:
             for warning in start_result.warnings:
-                if warning.code == "start.web_not_ready":
+                if warning.code in ("start.web_not_ready", "start.no_host_port"):
                     print(f"Warning: {warning.text}", file=sys.stderr, flush=True)
 
     emit_result(bench_result.data, warnings=bench_result.warnings)

{caffeinated_whale_cli-2.2.0 → caffeinated_whale_cli-2.3.1}/src/caffeinated_whale_cli/commands/init.py

@@ -173,6 +173,10 @@ class _InitRenderer:
             stderr_console.print(f"[yellow]Warning: {event.text}[/yellow]")
         elif code == "instance.already_running" and self.verbose:
             stderr_console.print(f"[dim]{event.text}[/dim]")
+        elif code == "ports.retry":
+            # Unmissable in both rendering modes: a caller waiting on this run
+            # needs to know it's retrying, not stuck.
+            stderr_console.print(f"[yellow]{event.text}[/yellow]")
 
     def _on_trace(self, event) -> None:
         if not self.verbose:
@@ -191,7 +195,11 @@ def _render_error_exit(e: CwcliError, project_name: str, *, verbose: bool = Fals
     stderr_console.print(f"[bold red]Error:[/bold red] {e.message}")
     if e.code == "ports.in_use":
         stderr_console.print(
-            "\n[yellow]Tip:[/yellow] Use the [cyan]--port[/cyan] flag to select "
+            "\n[yellow]Tip:[/yellow] If an instance using these ports was just removed, "
+            "they may still be releasing - wait a few seconds and retry."
+        )
+        stderr_console.print(
+            "[yellow]Tip:[/yellow] Otherwise, use the [cyan]--port[/cyan] flag to select "
             "a different starting port."
         )
         stderr_console.print(f"[dim]Example: cwcli init {project_name} --port 10000[/dim]")
@@ -376,10 +384,11 @@ def _start_services(project: str, bench_path: str) -> tuple[bool, bool | None]:
         )
         return False, None
     # core.start now blocks until the web server binds this bench's assigned port, so "running" is
-    # honest by the time we return. If it timed out, surface the warning so the
-    # user isn't told the web is up when it hasn't begun serving yet.
+    # honest by the time we return. If it timed out, or the port never got published
+    # to the host at all, surface the warning so the user isn't told the web is up
+    # when it isn't reachable.
     for warning in result.warnings:
-        if warning.code == "start.web_not_ready":
+        if warning.code in ("start.web_not_ready", "start.no_host_port"):
             stderr_console.print(f"[yellow]Warning:[/yellow] {warning.text}")
     running = result.status is not Status.NEEDS_CHOICE
     web_ready = result.data.web_ready if running and result.data is not None else None

{caffeinated_whale_cli-2.2.0 → caffeinated_whale_cli-2.3.1}/src/caffeinated_whale_cli/commands/start.py

@@ -322,7 +322,12 @@ def _start_project(
     # be visible here too, since restart's whole-stack path and the auto-start
     # path (ensure_containers_running) both funnel through this helper.
     for warning in result.warnings:
-        if warning.code in ("start.uid_align_failed", "bench.default_used", "start.web_not_ready"):
+        if warning.code in (
+            "start.uid_align_failed",
+            "bench.default_used",
+            "start.web_not_ready",
+            "start.no_host_port",
+        ):
             stderr_console.print(f"[yellow]Warning: {warning.text}[/yellow]")
         elif verbose:
             stderr_console.print(f"[dim]{warning.text}[/dim]")
@@ -522,7 +527,12 @@ def _run_start(
     # init.uid_align_failed precedent for the uid remap failure): both signal the
     # bench workspace may not behave as expected, not just verbose diagnostics.
     for warning in result.warnings:
-        if warning.code in ("start.uid_align_failed", "bench.default_used", "start.web_not_ready"):
+        if warning.code in (
+            "start.uid_align_failed",
+            "bench.default_used",
+            "start.web_not_ready",
+            "start.no_host_port",
+        ):
             stderr_console.print(f"[yellow]Warning: {warning.text}[/yellow]")
         elif verbose:
             stderr_console.print(f"[dim]{warning.text}[/dim]")