cwp doctor

cwp doctor [flags]

Acts on dev unless another environment is named.

Flag	What it does	Default
--env <env>	environment to diagnose remotely	dev

Plus the shared flags --json, --verbose and --dry-run.

What it does

Read-only diagnostics. Each check reports ok, warn or fail, and every failure prints a copy-pasteable fix. It exits non-zero if anything failed.

It checks the Node version, the Docker runtime, DDEV, mkcert, the host CLI and its login, both config files, that the remote app is reachable and its wp responds, PHP parity between local and remote, that the configured package matches the probed remote wp-content path, that WordPress core is present in the docroot, whether DDEV is running, and — on pull.uploads: proxy — whether the uploads fallback actually serves a file.

That last one is a live request, not an inventory: one uploads path the database knows and the filesystem does not, expecting a 200. Under proxy almost every file is missing locally by design, so “there are attachments without files” says nothing, and a fallback that is installed but not working looks exactly like one that is.

WordPress core is never committed, so a freshly cloned or freshly scaffolded project has none. doctor flags that before cwp pull runs into it: the import would succeed and then wp search-replace would fail with no installation to load. The fix is ddev wp core download.

With a builder configured

On builder.id: bricks it also checks, on both sides: Bricks ≥ 2.4, WordPress ≥ 6.9, whether the Bricks AI surface is switched on, that an ability user resolves, and that the abilities answer. Then the MCP exposure of the remote, the adapter plugin, and the custom post types — which exist on only one side, and which are registered but will not open in the builder.

On a project on builder: none none of that runs, rather than printing a screen of skips. The builder contributes those checks itself: doctor asks whichever builder the project configured and splices in what comes back, so it holds no Bricks-specific knowledge of its own.

These are separate checks on purpose. Bricks registers no abilities at all when its AI surface is off — not even the ones its documentation calls always-on — so “the abilities are missing” has four causes with four different fixes: WordPress too old, Bricks too old, the surface switched off, or BRICKS_DISABLE_MCP set. doctor reads the versions and settings directly rather than inferring them from a failed call, so it names the one that applies. It also distinguishes an AI tab that was switched off from one that has never been saved, which is the same screen but not the same sentence.

BRICKS_DISABLE_MCP reports as ok — pinning the AI surface off per environment is what it is for.

Example

cwp doctor
# ✓ Node 22.x
# ✗ Cloudron logged in — run: cloudron login my.example.com

What it does not do

It changes nothing. It only reports, which is why --dry-run is accepted and ignored.

It does not fix what it finds. Every failure carries the command that would, and typing it is yours.