nwire doctor — preflight diagnostic

A single command that runs every common-failure check against your workspace and prints a colored table. Use it before your first nwire dev of the day, in CI, or whenever Studio is showing data that doesn't match reality.

nwire doctor

  nwire doctor  /Users/alex/Projects/my-app

  ✓ node-version              Node 24.15.0
  ✓ package-manager           pnpm 10.33.2
  ✓ workspace                 apps:true src:false config:true
  ⚠ nwire-cache               manifest is 197h old
      run `nwire cache` to rebuild — Studio renders stale data otherwise
  ✓ probe-port                :9400 is free
  ✓ studio-port               :7777 is free
  ✓ compose-port-collisions   no collisions with 9400/7777
  ✓ inspect-mount             all L4 mains mount inspect
  ✓ tsconfig                  moduleResolution: "Bundler"
  ✓ env-files                 no plaintext secrets detected

  9 pass  1 warn  0 fail  0 info

What it checks

Check	Catches
node-version	Node < 22
package-manager	pnpm not on PATH
workspace	No package.json / no recognizable Nwire shape
nwire-cache	.nwire/manifest.json missing or > 24h stale (Studio renders old data)
probe-port	Lightship default port :9400 already in use
studio-port	Studio's :7777 already in use
compose-port-collisions	docker-compose.yml binds :9400 or :7777 — would shadow Nwire defaults
inspect-mount	An L4 app (createApp + app.start()) forgets api.inspect(app) — Studio Live 404s
tsconfig	moduleResolution is not Bundler (Nwire's convention)
env-files	*.env files contain plaintext-looking secrets (*_SECRET=..., etc.)

Failures (fail) exit code 1 so CI can gate on them. Warnings stay 0.

Flags

Flag	Effect
--json	Machine-readable output — same shape as the in-process result
--check=<sub>	Substring filter — --check=port runs just the port checks

CI usage

- run: nwire doctor

The command exits 1 on failures; warnings + info don't gate CI. Combine with --json if you want to parse results in a custom CI step.

Extending

Every check is a { name, description, run() } entry in CHECKS inside packages/nwire-cli/src/commands/doctor.ts. To add one, append to the array — the renderer handles the rest.