Dev Setup Doctor

Stop losing your first hour to missing env files, stale installs, blocked ports, and setup notes that worked on someone else's laptop.

Dev Setup Doctor checks whether a project is ready to run. It works with Node.js, Python, and PHP apps, including monorepos with several projects inside.

npx dev-setup-doctor check

It gives you a plain-language report:

PATIENT CHART

Health Score      B  (82%)
Passed            9/11
Failed            1/11
Warnings          1/11

Diagnosis
Missing .env
The project has .env.example, but no .env file.

How to fix
Copy .env.example to .env and fill in the values for your machine.

Why Use It?

Use Dev Setup Doctor when:

• You cloned a repo and want to know what is missing before running the app.
• A teammate says "it works for me" and you need a concrete setup report.
• Your repo has Node, Python, PHP, or several apps in apps/, services/, or backend/.
• You want CI to catch broken setup instructions before contributors do.
• You want safe fixes for common local setup problems.

Install

Run it once without installing:

npx dev-setup-doctor check

Install it on your machine:

npm install -g dev-setup-doctor
dev-doctor check

Add it to a project:

npm install --save-dev dev-setup-doctor
npx dev-doctor check

Requires Node.js 18 or newer.

30-Second Start

Check the current project:

dev-doctor check

Show the full explanation:

dev-doctor explain

Skip checks that need local services, such as ports and Docker:

dev-doctor check --offline

Scan a monorepo:

dev-doctor check --workspaces

Scan one app inside a repo:

dev-doctor check --workspace services/api

Get JSON for scripts or CI:

dev-doctor explain --json

Let the CLI offer safe fixes:

dev-doctor fix --wizard

What It Checks

| Area | Checks | | --- | --- | | Project type | Node.js, Python, PHP, Next.js, Vite, Django, FastAPI, Flask, Laravel | | Workspaces | Root project plus apps/*, packages/*, services/*, backend/*, frontend/* | | Node.js | npm, pnpm, yarn, Bun, lockfiles, engines.node, node_modules, Yarn PnP | | Python | pyproject.toml, requirements.txt, Pipfile, Poetry, Pipenv, .venv, Python version files | | PHP | composer.json, composer.lock, vendor/, Laravel artisan, PHP version constraints | | Env files | .env.example, .env, missing keys | | Config | doctor.config.json, required env vars, expected runtime, required ports | | Local services | Common dev ports, Dockerfile, Compose files, Docker availability | | Docs and CI | README setup commands, GitHub Actions workflows |

Real Examples

Node app

cd my-vite-app
dev-doctor check

Issues it can catch:

• package-lock.json exists, but node_modules is missing.
• package.json asks for Node >=20, but your terminal runs Node 18.
• The README does not tell a new contributor how to install and start the app.

Python API

cd services/api
dev-doctor check

Issues it can catch:

• pyproject.toml exists, but .venv is missing.
• FastAPI or Flask is detected from dependencies and app files.
• The project declares requires-python, so the report can show the expected Python version.

Laravel app

cd backend/admin
dev-doctor check

Issues it can catch:

• composer.json exists, but vendor/ is missing.
• composer.lock is missing from an app repo.
• Laravel is detected from artisan or laravel/framework.

Monorepo

my-company-app/
  apps/web/
  services/api/
  backend/admin/

Run:

dev-doctor check --workspaces

Dev Setup Doctor gives each project its own report, so you can see whether apps/web, services/api, or backend/admin needs attention.

Commands

dev-doctor check

Runs setup checks and prints a compact report.

dev-doctor check
dev-doctor check --offline
dev-doctor check --json
dev-doctor check --workspaces
dev-doctor check --workspace services/api

dev-doctor explain

Prints the detailed report with what happened, why it matters, and how to fix it.

dev-doctor explain
dev-doctor explain --json

dev-doctor fix

Runs checks and offers safe fixes.

dev-doctor fix
dev-doctor fix --wizard
dev-doctor fix --wizard --yes

Current fixes:

• Create .env from .env.example when .env does not exist.
• Add missing .env.example keys to .env.
• Add required doctor.config.json env keys to .env.
• Install Node dependencies with the detected package manager.

Python and PHP checks are diagnostic in this release. Their auto-fixes will stay conservative until the CLI can avoid guessing how each team manages virtual environments and Composer installs.

dev-doctor init

Creates doctor.config.json.

dev-doctor init --yes
dev-doctor init --name my-api --node ">=20" --ports 3000,5432 --yes

dev-doctor install-hook

Adds a Git pre-commit hook that runs dev-doctor check --offline.

dev-doctor install-hook

dev-doctor doctor

Checks Dev Setup Doctor itself.

dev-doctor doctor

Options

| Option | Use | | --- | --- | | --json | Print machine-readable JSON | | --offline | Skip port and Docker checks | | --skip <ids> | Skip checks by id prefix | | --workspaces | Scan supported projects under common workspace folders | | --workspace <path> | Scan one project by path | | --no-color | Remove terminal colors | | --no-emoji | Use plain symbols |

Examples:

dev-doctor check --offline
dev-doctor check --skip docker,ports
dev-doctor check --workspaces
dev-doctor check --workspace services/api
dev-doctor explain --json --no-color --no-emoji

Project Config

Use doctor.config.json when your project has rules the CLI cannot infer.

{
  "name": "example-api",
  "runtime": {
    "language": "python",
    "version": ">=3.11"
  },
  "env": {
    "required": ["DATABASE_URL", "STRIPE_SECRET_KEY"]
  },
  "ports": [3000, 5432],
  "services": [
    {
      "name": "postgres",
      "host": "localhost",
      "port": 5432
    }
  ],
  "setup": {
    "install": "poetry install",
    "dev": "poetry run uvicorn app.main:app --reload"
  }
}

Existing Node configs still work:

{
  "runtime": {
    "node": ">=20"
  },
  "packageManager": "pnpm"
}

Start with:

dev-doctor init --yes

Then edit the file for your project.

Ignore Checks

Create .doctorignore in the project root:

docker
ports
github-actions

You can also skip checks from the command line:

dev-doctor check --skip docker,ports

Skip values match check id prefixes. ports skips ports-3000, ports-5173, and config-port-3000.

JSON Output

Single-project JSON:

{
  "healthScore": 80,
  "total": 10,
  "passed": 8,
  "failed": 1,
  "warnings": 1,
  "results": []
}

Workspace JSON:

{
  "healthScore": 70,
  "total": 20,
  "passed": 14,
  "failed": 1,
  "warnings": 5,
  "projects": [
    {
      "root": "services/api",
      "language": "python",
      "framework": "fastapi",
      "dependencyManager": "poetry",
      "markers": ["pyproject.toml"],
      "results": []
    }
  ]
}

Exit codes:

• 0: all checks passed
• 1: at least one check failed
• 2: warnings exist, no failures

GitHub Actions

name: setup-check

on:
  pull_request:

jobs:
  dev-doctor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx dev-setup-doctor explain --offline

Use --offline in CI when Docker or local port checks do not make sense for the runner.

FAQ

Do I need to install it?

No. Use npx dev-setup-doctor check for a single run. Install it on your machine or as a dev dependency when you use it often.

Which project types does it support?

Node.js, Python, and PHP. It detects Next.js, Vite, Django, FastAPI, Flask, and Laravel when common project markers are present.

Does it work in monorepos?

Yes. Run dev-doctor check --workspaces from the repo root. It scans supported projects under apps, packages, services, backend, and frontend.

Can I scan one app inside a repo?

Yes. Use dev-doctor check --workspace services/api.

Why did it fail because my package manager is unclear?

The repo has mixed signals, such as package-lock.json and pnpm-lock.yaml together. Remove the wrong lockfile or set packageManager in package.json.

Does fix overwrite my .env file?

No. It creates .env only when the file does not exist. For missing keys, it appends blank entries and leaves existing values alone.

Why did it skip Docker or port checks?

You used --offline, .doctorignore, or --skip. Run without those options if you want local Docker and port checks.

Does it support Bun and Yarn PnP?

Yes. It detects Bun lockfiles and Yarn Plug'n'Play files.

Why does it warn about an empty GitHub Actions folder?

.github/workflows only counts when it contains .yml or .yaml workflow files. An empty folder does not run CI.

Local Development

npm install
npm run typecheck
npm run build
npm run dev -- explain --offline

Project layout:

src/
  checks/       setup checks
  commands/     CLI commands
  core/         runner, result types, reporter
  fixes/        automatic fixes
  ui/           terminal report, menu, wizard
  utils/        file, env, ports, package manager helpers

License

MIT