env-doctor

The eslint of environment variables — catch missing env vars before they hit production.

env-doctor-web.vercel.app · npm · GitHub Action · VS Code Extension

The Problem

Developers lose hours debugging "works on my machine" failures caused by missing, misconfigured, or undocumented environment variables. env-doctor gives you a fast, zero-config CLI that scans your codebase, detects all env var references, and cross-checks them against your .env and .env.example files.

VS Code Extension

Get inline squiggles directly in your editor — no terminal needed. Install env-doctor from the VS Code Marketplace.

Features

• Zero config — works out of the box on Node.js, Python, Go, Rust, Ruby, PHP, and Shell projects
• Multi-language detection — process.env, os.environ, os.Getenv, env::var, ENV[], and more
• CI-ready — meaningful exit codes (0 = clean, 1 = errors, 2 = warnings, 3 = fatal)
• Three output formats — pretty terminal output, JSON for tooling, Markdown for PR comments
• Auto-fix — --fix updates .env.example automatically
• Health scoring — doctor command gives a 0–100 score with trend tracking

Installation

npm install -g @neerav34/env-doctor
# or use without installing
npx @neerav34/env-doctor check

Quick Start

# Check for discrepancies
env-doctor check

# Generate / update .env.example from your code
env-doctor init

# Full diagnostic with health score
env-doctor doctor

Commands

env-doctor check

Scans your codebase and reports all environment variable discrepancies.

env-doctor check [options]

Options:
  --fix                    Auto-update .env.example to match code references
  --strict                 Treat warnings as errors (exit 1)
  --env-file <path>        Path to .env file (default: .env)
  --example-file <path>    Path to .env.example file (default: .env.example)
  --ignore <patterns...>   Additional glob patterns to skip
  --format <fmt>           Output format: pretty | json | markdown (default: pretty)
  --no-color               Disable ANSI color output
  --root <path>            Project root directory (default: cwd)

Exit codes: | Code | Meaning | |------|---------| | 0 | All clear | | 1 | ERROR-level issues found (or --strict with warnings) | | 2 | Only WARN-level issues | | 3 | Fatal error (crash, bad arguments) |

env-doctor init

Generates or updates .env.example from all env var references found in your code.

env-doctor init [options]

Options:
  --env-file <path>        Source .env file (default: .env)
  --example-file <path>    Target file (default: .env.example)
  --with-comments          Add source file comments to each variable
  --ignore <patterns...>   Additional glob patterns to skip
  --no-color               Disable ANSI color output
  --root <path>            Project root directory

env-doctor doctor

Full diagnostic with a health score (0–100) and trend analysis vs. previous scans.

env-doctor doctor [options]

Same flags as check. Stores scan history in .env-doctor/cache.json.

What It Detects

| Check | Severity | Description | |-------|----------|-------------| | Missing Required | ERROR | Var referenced in code but absent from both .env and .env.example | | Missing Optional | WARN | Var referenced in code and in .env.example but not in .env | | Unused Variable | WARN | Var defined in .env but never referenced in code | | Example Drift | WARN | Var in .env but not in .env.example (or vice versa) |

Supported Languages

| Language | Detected Patterns | |----------|------------------| | JavaScript / TypeScript | process.env.VAR, process.env['VAR'], import.meta.env.VAR | | Python | os.environ['VAR'], os.environ.get('VAR'), os.getenv('VAR') | | Go | os.Getenv("VAR") | | Rust | env::var("VAR") | | Ruby | ENV['VAR'] | | PHP | $_ENV['VAR'], getenv('VAR') | | Shell / Docker | ${VAR} in .sh, Dockerfile, docker-compose.yml |

CI Integration

GitHub Actions

- name: Check environment variables
  run: npx env-doctor check --strict --format markdown >> $GITHUB_STEP_SUMMARY

GitLab CI

env-check:
  script:
    - npx env-doctor check --strict

Output Examples

Pretty (default)

  ERRORS (1)

  ✗  DATABASE_URL  [Missing Required]
     DATABASE_URL is referenced in 2 location(s) but not defined in .env or .env.example
     └─ src/db.ts:14  const pool = new Pool({ connectionString: process.env.DATABASE_URL });
     → Add DATABASE_URL to .env.example

  WARNINGS (2)

  ⚠  OLD_API_KEY  [Unused Variable]
     OLD_API_KEY is defined in .env but never referenced in source code
     → Remove OLD_API_KEY from .env or check for typos in variable name

  Scanned 142 files in 45ms

JSON (--format json)

{
  "success": false,
  "summary": { "errors": 1, "warnings": 2, "scannedFiles": 142, "duration": 45 },
  "issues": [...]
}

Development

git clone https://github.com/your-username/env-doctor.git
cd env-doctor
npm install
npm run dev -- check          # run in dev mode
npm test                      # run tests
npm run build                 # build to dist/
npm run dogfood               # run against itself

License

MIT © Neerav Jha