🩺 dotenv-scan

One command to catch every missing, unused, and undocumented .env variable.

---

Why dotenv-scan?

Every developer has deployed to production only to watch it crash because of a missing .env variable. dotenv-scan scan finds those variables before they cause downtime — and cleans up stale ones while it's at it.

Three problems, one command:

Problem	What happens	How dotenv-scan helps
Missing variables	Code uses DATABASE_URL but .env doesn't have it	Detected as ❌ Missing
Unused variables	.env has OLD_REDIS_URL nobody uses anymore	Detected as 🗑️ Unused
Undocumented variables	.env has INTERNAL_API_KEY but .env.example doesn't	Detected as ⚠️ Undocumented

---

✨ Features

• 🚀 Zero config — run npx dotenv-scan in any project directory
• 🔍 Multi-language — JavaScript, TypeScript, Python, Go, Ruby
• 📊 Structured output — pretty terminal tables or JSON for tooling
• 🔁 Auto-generate .env.example — keeps docs in sync with one command
• 🤖 CI-ready — dotenv-scan check exits with code 1 on missing variables
• ⚡ Fast — scans hundreds of files in under 500ms

---

🚀 Quick Start

npx dotenv-scan scan

That's it. No install needed.

dotenv-scan v1.0.0  ·  scanned 47 files in 284ms

❌  Missing  (3)
   DATABASE_URL      src/db.ts:12, src/config.ts:8
   JWT_SECRET        src/auth/middleware.ts:4
   STRIPE_API_KEY    src/payments/stripe.ts:22

⚠️  Undocumented  (2)
   INTERNAL_API_KEY
   DEBUG_MODE

🗑️  Unused  (1)
   OLD_REDIS_URL

✅  OK  (8)
   PORT, NODE_ENV, API_BASE_URL, ... (and 5 more)

────────────────────────────────────────
Run `dotenv-scan generate` to update .env.example

---

📦 Installation

Run without installing (recommended):

npx dotenv-scan scan

Install globally:

npm install -g dotenv-scan

From source:

git clone https://github.com/dotenv-scan/dotenv-scan
cd dotenv-scan && npm install && npm run build

---

📖 Commands

dotenv-scan scan

Scan and report env variable issues. Always exits 0.

dotenv-scan scan                          # scan current directory
dotenv-scan scan --dir ./src              # scan specific directory
dotenv-scan scan --dotenv .env.local    # use specific .env file
dotenv-scan scan --format json            # JSON output
dotenv-scan scan --no-color               # disable colors
dotenv-scan scan -i "**/vendor/**"        # ignore additional patterns

dotenv-scan check

Same as scan, but exits 1 if missing variables found. Perfect for CI.

dotenv-scan check                         # fails on missing vars
dotenv-scan check --strict                # also fail on unused/undocumented

CI example (GitHub Actions):

- name: Check env variables
  run: npx dotenv-scan check

dotenv-scan generate

Generate or update .env.example from scan results.

dotenv-scan generate                      # creates/updates .env.example
dotenv-scan generate --example .env.tmpl  # custom output path

---

⚙️ Options

Flag	Short	Default	Description
--dir <path>	-d	./	Directory to scan
--dotenv <path>	-e	.env	Path to .env file
--example <path>	-x	.env.example	Path to .env.example file
--ignore <patterns>	-i	—	Additional glob patterns to ignore
--format <type>	-f	text	Output format: text or json
--no-color		—	Disable colored output
--strict		—	(check only) Fail on unused/undocumented too
--version		—	Print version
--help		—	Print help

---

🗺️ Supported Languages

Language	Patterns detected
JavaScript / TypeScript	process.env.VAR, process.env['VAR'], process.env["VAR"]
Python	os.environ.get('VAR'), os.environ['VAR'], os.getenv('VAR')
Go	os.Getenv("VAR")
Ruby	ENV['VAR'], ENV.fetch('VAR')

Dynamic access warning: Patterns like process.env[dynamicKey] can't be statically analyzed. dotenv-scan detects these and reports them as warnings.

---

🏗️ Architecture

CLI Entry (Commander.js)
    │
    ├── Scanner ──── Walker (fast-glob) ──── Extractors (per-language regex)
    │                                                    │
    │                                          EnvRef[] (used variables)
    │
    ├── Parser ──── Dotenv parser ──── EnvDef[] (defined variables)
    │
    └── Analyzer ── compares used ↔ defined ↔ documented
                         │
                    AnalysisResult
                         │
                    ┌────┴────┐
                 Reporter   Generator
                (text/json)  (.env.example)

---

🧪 Development

git clone https://github.com/dotenv-scan/dotenv-scan && cd dotenv-scan
npm install
npm run build          # build first (required for integration tests)
npm test               # run test suite
npm run test:coverage  # run with coverage report
npm run lint           # check code style

See CONTRIBUTING.md for full guidelines.

---

🗺️ Roadmap

• v1.0 — Core scan, check, generate commands
• v1.1 — PHP and Rust extractors
• v1.2 — dotenv-scan.config.ts support
• v2.0 — Monorepo multi-.env support, VSCode extension

---

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md.

---

📄 License

Apache-2.0 — see LICENSE for details.

---

Made with ❤️ for developers tired of "undefined is not a string" · Star this repo ⭐