Dotenv Doc

Checks your .env against your .env.example and tells you exactly what's missing, empty, or undocumented. Zero runtime dependencies.

$ npx dotenv-doc

Dotenv Doc  checking ./.env against ./.env.example

✓ 8 variables set

✗ 1 missing
  - STRIPE_SECRET_KEY

! 1 empty
  - DATABASE_URL

2 problems found. Run with --fix to resolve them interactively.

Why

You clone a repo, run npm install, run the dev server, and it crashes on a missing env var three files deep in a stack trace. Or a teammate adds a new required variable and doesn't tell anyone, and it only shows up as a production incident. This is the five-second check that catches both, before either happens.

Use it locally

npx dotenv-doc

No install, no config. It looks for .env and auto-detects .env.example / .env.sample / .env.template / .env.dist in the current directory. If .env doesn't exist yet, it lists everything you need to create one — handy right after cloning a repo, before you've even made a .env.

Fix it interactively

npx dotenv-doc --fix

Prompts for each missing or empty value, one at a time, and writes them straight into your .env. Leave a line blank to skip it — nothing is overwritten unless you type a value.

Use it in CI

npx dotenv-doc --strict

Exit code is 0 when everything's fine, 1 otherwise — drop it into any CI pipeline as a required check. See .github/workflows/check-env.yml.example for a ready-made GitHub Action that catches the specific failure mode of "added a var to .env.example, forgot to wire the matching secret into CI or deploy."

Options

| Flag | Effect | |---|---| | --fix | Interactively fill in missing/empty values | | --json | Machine-readable output instead of colored text | | --strict | Also fail if .env has keys not in the example | | --env <path> | Path to your real env file (default: .env) | | --example <path> | Path to the example file (default: auto-detected) | | -h, --help | Show usage | | -v, --version | Show the version |

Install

npm install -g dotenv-doc
# or just use npx, no install needed

Development

npm install
npm run build
npm test

npm test builds the CLI and runs it against real fixture .env / .env.example pairs under test/fixtures — including the --fix flow, piping simulated answers into it — rather than just asserting on individual functions.