⚡ env-patrol

Zero-config CLI to detect dead, ghost, and drifted environment variables in your codebase.

Stop guessing if that secret from two years ago is still being used, or debugging why production crashed because someone forgot to add a variable to .env.example.

🚀 Quick Start

Run it instantly in any JavaScript or TypeScript project without installing:

npx env-patrol

Or install it globally:

npm install -g env-patrol
env-patrol

🔍 What env-patrol Detects

        ┌─────────────────────────────────────────────────────────┐
        │                       env-patrol                        │
        └───────────────────────────┬─────────────────────────────┘
                                    │
         ┌──────────────────────────┼──────────────────────────┐
         ▼                          ▼                          ▼
   1. Dead Vars              2. Ghost Vars              3. Env Drift
 (In .env, never used)     (In code, not in .env)     (.env vs .env.example)

1. ❌ Ghost Variables (Breaking Risk)

Variables referenced in your source code (process.env.STRIPE_KEY or import.meta.env.VITE_API_URL) that are completely missing from your .env or .env.example files.

2. ⚠️ Dead Variables (Configuration Bloat)

Variables defined in your .env or .env.example files that are never referenced anywhere in your codebase. Safe to prune!

3. 🔄 Environment Drift

Detects discrepancies between your different env files (e.g., keys defined in .env.local that were never documented in .env.example, or staging keys missing in production).

💻 Sample Output

⚡ env-patrol v0.1.0 — Environment Variable Health Report
─────────────────────────────────────────────────────────────────
Scanned: 48 source files, 2 env files (.env, .env.example)

❌ GHOST VARIABLES (2)
   Referenced in source code, but NOT declared in any .env file:
   • STRIPE_WEBHOOK_SECRET
     └─ src/api/webhooks.ts:14:22 [process.env]
   • NEXT_PUBLIC_POSTHOG_KEY
     └─ src/app/providers.tsx:8:10 [destructured]

⚠️  DEAD VARIABLES (1)
   Declared in .env files, but never used in any source code file:
   .env.local:
     • OLD_REDIS_PASSWORD (line 12)

🔄 ENVIRONMENT DRIFT (1)
   Keys inconsistent across different .env files:
   • FEATURE_BETA_FLAG: Present in [.env.local] | Missing in [.env.example]

─────────────────────────────────────────────────────────────────
Status: Found 2 ghost vars, 1 dead vars, 1 drift items. (Tip: run with --sync to add missing keys to .env.example)

⚙️ CLI Options & Flags

| Flag | Description | | :--- | :--- | | [dir] | Target directory to scan (default: current working directory) | | --ci | Exit with status code 1 if any ghost or dead variables are detected | | --sync | Automatically append missing ghost variables to .env.example | | --ignore <keys> | Comma-separated list of keys to ignore (e.g. --ignore FOO,BAR) | | -v, --version | Output version number | | -h, --help | Display CLI help |

🛠️ Supported Syntax & Frameworks

env-patrol uses full AST (Abstract Syntax Tree) parsing, supporting:

• Node / Express / Next.js:

  process.env.DATABASE_URL
  process.env['DATABASE_URL']
  const { DB_HOST, DB_PORT } = process.env;

• Vite / Astro / Nuxt / Modern ESM:

  import.meta.env.VITE_API_URL
  import.meta.env['VITE_API_URL']
  const { VITE_TITLE } = import.meta.env;

• TypeScript & JSX/TSX: Fully supported out of the box.

Standard runtime platform variables (NODE_ENV, PORT, HOST, CI, PATH, etc.) are automatically ignored.

🤖 CI/CD Integration

Catch missing environment variables in your pull requests before deploying:

# .github/workflows/env-patrol.yml
name: Audit Environment Variables

on: [push, pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx env-patrol --ci

📄 License

MIT © Yaseen Jabir