Local-first consistency checker for environment variables. Detects missing, unused, duplicate, and mismatched variables across .env files, Docker Compose, Kubernetes manifests, GitHub Actions, and source code — no network calls, no telemetry, no values ever printed.

Available for six ecosystems — Node, Python, Go, Ruby, PHP, and Java — as native ports, each installable from its own package manager.

📖 Documentation: arun-skg.github.io/envdoctor — full guides, per-language references, and examples.

_{Auto-refreshed daily by the Downloads chart workflow. Click for interactive history on npm-stat.}

┌─────────────────────────────────────────────────────────────────┐
│  ENVIRONMENT AUDIT                                              │
│  ════════════════════════════════════════════════════════════════│
│                                                                 │
│  Missing (error)                                                │
│  ─────────────────────────────────────────────────────────────  │
│  ❌  COMPOSE_ONLY       docker-compose.yml:9   referenced but   │
│                          not defined in any environment file   │
│  ❌  NEW_FEATURE_FLAG   src/index.ts:5         used in source   │
│                          code but not defined in any           │
│                          environment file                      │
│                                                                 │
│  Unused (warning)                                               │
│  ─────────────────────────────────────────────────────────────  │
│  ⚠  DEBUG_MODE          .env:7               defined but never │
│                          referenced anywhere                    │
│                                                                 │
│  Duplicates (error)                                             │
│  ─────────────────────────────────────────────────────────────  │
│  ❌  NODE_ENV            .env:2,12           defined 2 times   │
│                                                                 │
│  Type mismatch (error)                                          │
│  ─────────────────────────────────────────────────────────────  │
│  ❌  PORT                expected: integer · found: string      │
│                                                                 │
│  Summary: 8 files scanned · 15 variables · 4 errors · 16 warns │
└─────────────────────────────────────────────────────────────────┘

• Why
• Supported formats
• Installation
• Native ports
• Quick start
• Detectors
• Commands
• Configuration
• Environment labels
• Output formats
• CI integration
• Security
• Architecture
• Development
• Contributing
• License

Environment drift is a silent class of bug: a variable is used in code but never documented, defined in .env but dead, present in development but forgotten in production, or a secret accidentally shipped to the client bundle behind a NEXT_PUBLIC_ prefix. envdoctor reconciles every place a variable can appear — .env files, Docker Compose, Kubernetes manifests, GitHub Actions, and your source code — into one normalized model, then runs a suite of detectors over it.

It is local-first: everything runs on your machine, nothing is uploaded, and variable values are never printed or written into generated artifacts.

# From npm
npm install -g @arunskg/envdoctor

# Or run directly with npx
npx @arunskg/envdoctor scan

Using another language? See native ports below.

envdoctor is published as a standalone native implementation for each ecosystem — no Node required, no wrappers. Every port scans its own language's environment idioms, reconciles them against your .env files, and exits 1 on errors so it drops straight into CI.

All ports share the same CLI shape:

envdoctor scan --dir .        # audit; exit 1 on errors
envdoctor scan --strict       # treat warnings as errors too

Note: the Python distribution is named arun-envdoctor on PyPI (the bare name is blocked as too similar to an existing project), but the installed command and importable package are both envdoctor.

Each port has its own README, test suite, and CI workflow, and they are kept behaviour-identical — the same project produces byte-for-byte-equivalent findings (and --json output) in every language. The native ports are now at full feature parity with the Node reference: all ten detectors, the scan / diff / sync / init / fix subcommands, --json output, and Docker Compose / Kubernetes / GitHub Actions scanning.

Schema validation reads an envdoctor.schema.json at the project root, e.g.:

{
  "PORT":  { "type": "integer", "min": 1, "max": 65535 },
  "LEVEL": { "enum": ["debug", "info", "warn", "error"] },
  "API":   { "type": "url" },
  "TOKEN": { "type": "string", "optional": true }
}

Note: run npx @arunskg/envdoctor from your project directory, not from inside a checkout of this repo — npx resolves the local package first, whose envdoctor bin isn't on your PATH, and you'll see envdoctor: command not found. After a global install, the short envdoctor command works anywhere.

# Bootstrap config + .env.example + ENVIRONMENT.md in your project
envdoctor init

# Scan for issues (exits 1 on errors, 0 on clean)
envdoctor scan

# Compare two environments
envdoctor diff development production

# Copy missing keys from .env to .env.local
envdoctor sync development local

# Scan only files changed on this branch
envdoctor scan --since HEAD

# Generate/update docs (dry-run first)
envdoctor fix --dry-run
envdoctor fix

Any detector can be downgraded or disabled via the rules config or an inline ignore.

Bootstraps a project:

• Creates envdoctor.config.ts with commented defaults (if missing)
• Generates .env.example from discovered variables (if missing)
• Generates ENVIRONMENT.md documentation (if missing)

Never overwrites existing files without --force.

Runs the full audit.

Exit codes: 0 = clean, 1 = errors found, 2 = usage/config error

The --baseline / --write-baseline pair lets you adopt envdoctor on a legacy project: snapshot today's findings, then fail CI only on new ones.

--staged and --since are useful in pre-commit hooks and CI to audit only the files touched by a changeset instead of the whole repository.

Generates/updates safe artifacts based on the audit:

• .env.example — all known variables with placeholders (secrets get empty values)
• ENVIRONMENT.md — reference table + per-environment sections
• .github/ENVIRONMENT.md — checklist of secrets.*/vars.* for GitHub Actions (if applicable)
• env.d.ts — TypeScript ambient declaration for process.env variables
• envdoctor.schema.ts — inferred Zod-style validation schema from observed values (e.g. integer ranges, enum sets). Import and merge it into envdoctor.config.ts to enable the schema-validation detector.

Focused comparison between two environments (e.g. dev prod, development production). Shows per-variable status: ✓ same, ⚠ different, ❌ missing.

Copy missing variable keys from one environment file to another without overwriting existing values. Useful for keeping .env.local or .env.production up to date after adding variables to .env.

# Append keys that exist in .env but are missing from .env.local
envdoctor sync development local

# Or by explicit file suffix
envdoctor sync .env .env.production

Only keys are copied; values are left untouched so target-specific values and secrets stay safe.

Configuration is optional — defaults are sensible for most projects. Create envdoctor.config.ts (or .js/.mjs/.cjs, or an envdoctor key in package.json):

export default {
  // Glob patterns for dotenv files
  envFilePatterns: [".env", ".env.*"],

  // Docker Compose file patterns
  composeFilePatterns: ["**/docker-compose*.y*ml", "**/compose*.y*ml"],

  // GitHub Actions workflow patterns
  actionsFilePatterns: [".github/workflows/**/*.y*ml"],

  // Kubernetes manifest patterns
  k8sFilePatterns: ["**/k8s/**/*.y*ml", "**/manifests/**/*.y*ml"],

  // Source file extensions to scan
  sourceExtensions: ["ts", "tsx", "js", "jsx", "mjs", "cjs"],

  // Variable names to ignore entirely (glob patterns, e.g. "AWS_*")
  ignoreVariables: [],

  // File paths to ignore (glob patterns)
  ignoreFiles: [],

  // Explicit environment label → file list overrides
  environments: {
    // development: [".env", ".env.local"],
    // production: [".env.production"],
  },

  // Fail the audit when only warnings are present
  strict: false,

  // Per-detector severity overrides: "error", "warning", or "off"
  rules: {
    // unused: "off",
    // "environment-diff": "error",
  },

  // Per-variable value validation (feeds the schema-validation detector)
  schema: {
    // PORT: { type: "integer", min: 1024 },
    // RATE: { type: "float", min: 0, max: 1 },
    // NODE_ENV: { enum: ["development", "production", "test"] },
    // API_URL: { type: "url" },
    // FEATURE_FLAGS: { type: "json" },
    // Optional variables are allowed to be empty/missing
    // LOG_LEVEL: { type: "string", optional: true },
  },
};

Suppress a detector for a specific variable with a comment on the preceding line:

# envdoctor:ignore unused
DEBUG_MODE=true

# envdoctor:ignore unused, weak-secret
MY_TOKEN=placeholder

Aliases: dev → development, prod → production for the diff command.

Colorized, sectioned report as shown above.

{
  "exitCode": 1,
  "summary": {
    "filesScanned": 8,
    "variablesFound": 15,
    "errors": 4,
    "warnings": 16,
    "infos": 0,
    "total": 20
  },
  "findings": [
    {
      "id": "missing.COMPOSE_ONLY",
      "ruleId": "missing",
      "severity": "error",
      "variable": "COMPOSE_ONLY",
      "message": "referenced but not defined in any environment file",
      "locations": [
        { "file": "docker-compose.yml", "line": 9, "kind": "definition" }
      ]
    }
  ]
}

Emits SARIF 2.1.0 for upload to GitHub code scanning or any SARIF-aware tool.

# .github/workflows/env-audit.yml
name: Environment Audit
on: [push, pull_request]
jobs:
  envdoctor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with:
          node-version: '22'
      - run: npx @arunskg/envdoctor scan --strict

For code scanning, add --format sarif and upload the result with github/codeql-action/upload-sarif.

• Values are never printed to stdout/stderr (even with --verbose).
• Secrets are never written to generated files (.env.example, ENVIRONMENT.md, .github/ENVIRONMENT.md, env.d.ts).
• No network calls, no telemetry — everything runs locally.
• Secret heuristic: name matches /(SECRET|TOKEN|PASSWORD|PASS|API[_A-Z]*KEY|PRIVATE[_-]?KEY|CREDENTIALS)/i.
• Unreadable directories are skipped rather than aborting the scan.

discovery (fast-glob)
    │
    ▼
parsers (dotenv, docker-compose, kubernetes, github-actions, source)
    │
    ▼
normalized ProjectModel (definitions + usages per file)
    │
    ▼
index (buildIndex: maps by name + environment)
    │
    ▼
detectors (missing, undefined-in-source, unused, duplicates,
           environment-diff, type-mismatch, schema-validation,
           public-prefix, weak-secret, typo)
    │
    ▼
AuditResult (Findings + Summary + ExitCode)
    │
    ▼
generators (env-example, environment-doc, env-types, schema, github-actions)

Every parser implements a common Parser interface and every detector a common Detector interface — new formats and rules can be added without touching the others.

npm install       # install deps
npm test          # run the test suite (vitest)
npm run typecheck # tsc --noEmit
npm run lint      # eslint
npm run build     # tsup → dist/

# Local smoke test
node dist/index.js scan --dir tests/fixtures/sample-project

Issues and pull requests are welcome. See CONTRIBUTING.md for the development workflow — please run npm test, npm run lint, and npm run typecheck before opening a PR. See CHANGELOG.md for release history and SECURITY.md to report a vulnerability.

MIT