Workers Doctor

Inspect and safely run multi-Worker Cloudflare projects.

Website · GitHub Action · Report an issue

Workers Doctor turns a directory of Wrangler files into one understandable development plan. It resolves the selected environment, maps service and resource bindings, identifies local and remote state, checks local secret names, and can start the stack only after the plan is visible.

$ npx workers-doctor inspect --env staging

Workers Doctor
2 workers · 3 bindings · 1 remote
Environment: staging

doctor-api-staging  apps/api/wrangler.jsonc
  d1               DB → doctor-preview  remote
  service          AUTH → doctor-auth-staging  local

doctor-auth-staging  apps/auth/wrangler.jsonc
  kv                SESSIONS → local-id  local

i NOTICE WD002  Remote bindings will be used

Inspect a stack

npx workers-doctor
npx workers-doctor ./apps --env staging
npx workers-doctor --json
npx workers-doctor --github --strict
npx workers-doctor graph > workers.dot

Wrangler JSONC, JSON, and TOML configurations are supported. Common generated directories are skipped during discovery.

Start the development plan

Preview the exact processes and ports first:

npx workers-doctor dev --env staging --dry-run

Then start every discovered Worker in dependency order:

npx workers-doctor dev --env staging

Workers Doctor uses the repository's lockfile to select pnpm, npm, Bun, or Yarn. It does not deploy, create resources, or call the Cloudflare API.

GitHub Actions

- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
- uses: loke-dev/[email protected]
  with:
    environment: staging

The reusable Action annotates configuration problems and fails on errors. Its inputs are path, environment, and strict. It runs the reviewed CLI bundle from the selected repository tag without downloading executable code from npm.

Diagnostics

| Rule | Check | | --- | --- | | WD001 | Selected environment exists in every scanned Worker | | WD002 | Remote bindings are clearly reported | | WD003 | Local and remote state are not mixed accidentally | | WD004 | A project does not mix .dev.vars and .env | | WD005 | Names declared in secrets.required exist locally | | WD006 | Service binding targets resolve inside the scanned stack | | WD007 | Service binding cycles, including self-cycles, are visible | | WD008 | Effective Worker names are unique inside the scanned stack | | WD009 | Binding names are unique inside each Worker |

Secret values are never reported. inspect, graph, and CI output are fully offline and require no Cloudflare account.

Development

pnpm install
pnpm check
pnpm dev -- tests/fixtures/healthy --env staging
pnpm site:dev

License

MIT