envdoc-scan

Scan your codebase for environment-variable references and generate a .env.example template or a documentation table. Never let your .env.example drift again.

Why

Every project has a .env.example that's supposed to list all the environment variables the app needs. In practice, it's always out of date — someone adds process.env.NEW_THING to the code and forgets to update the template. New contributors hit cryptic errors because they're missing a var.

envdoc scans your source files for every environment-variable reference and tells you exactly:

• Which vars your code actually uses (and where)
• Which vars are in your .env.example but no longer referenced (dead config)
• Which vars are used in code but missing from .env.example (undocumented)

Install

npm install -g envdoc-scan

Or use it directly with npx:

npx envdoc-scan

Usage

# Print a .env.example template (default)
envdoc-scan

# Print a markdown documentation table
envdoc-scan --markdown

# Merge with your existing .env.example (preserves comments + defaults)
envdoc-scan --existing .env.example

# Flag vars in .env.example that are no longer in source
envdoc-scan --existing .env.example --mark-unused

# Output JSON (for CI checks or tooling)
envdoc-scan src/ --json

# Scan a specific directory
envdoc-scan src/

Output formats

.env.example (default):

# Database connection string
DATABASE_URL=postgres://localhost/mydb

# Auth
# (unused — not found in source)
SECRET_KEY=changeme

API_KEY=

REDIS_URL=

Markdown table:

| Variable | Default | Used | Location | |----------|---------|------|----------| | DATABASE_URL | postgres://localhost/mydb | yes | sample.js:3 (+1) | | SECRET_KEY | changeme | no | — | | API_KEY | — | yes | sample.js:2 |

JSON:

{
  "DATABASE_URL": [{ "file": "config.js", "line": 12, "col": 25 }]
}

Supported patterns

envdoc detects environment-variable access across multiple languages:

| Language | Pattern | |----------|---------| | Node / Bun | process.env.NAME, process.env['NAME'] | | Python | os.environ.get('NAME'), os.getenv('NAME'), os.environ['NAME'] | | Java | System.getenv("NAME") | | Ruby | ENV['NAME'] | | Rust | env::var("NAME") | | Go | os.LookupEnv("NAME") |

What it scans

By default, envdoc scans these file types:

.js, .mjs, .cjs, .ts, .jsx, .tsx, .py, .java, .rb, .rs, .go, .sh, .bash, .yml, .yaml

It automatically skips: node_modules, .git, vendor, dist, build, .next, target, __pycache__, .venv, venv, coverage, .cache, and hidden directories.

CI integration

Use --json to fail CI if your .env.example is missing vars:

# In your CI pipeline:
envdoc --json > /tmp/scanned.json
# ... diff against your committed .env.example

License

MIT © takeaseatventure