Skip to content
Munim · OSS

dotcheck

Validate your .env against a contract. dotcheck compares your real .env file against a committed .env.example and flags the keys that have drifted — locally and in CI.

The .env.example in your repo is supposed to document every variable the app needs. In practice it drifts: someone adds a variable to their local .env and forgets the example, or a teammate clones the repo, copies the example, and ships with a blank API_KEY. dotcheck turns that implicit contract into something you can actually enforce. It tells you what’s missing, what’s extra, and what’s present but empty, then exits non-zero on problems so it drops straight into a pipeline as a gate.

When something has drifted, you get a grouped, colour-coded report:

Terminal window
Missing (1)
  • LOG_LEVEL


Empty (1)
  • API_KEY


Extra (1)
  • EXTRA_THING
  • Missing — the example defines LOG_LEVEL, but your .env never sets it.
  • Empty — API_KEY exists in your .env, but its value is blank.
  • Extra — your .env defines EXTRA_THING, which the example doesn’t know about (suppress with --allow-extra).

On a clean run, there’s a single line and an exit code of 0:

Terminal window
All environment variables present.

Zero config

Auto-detects .env and .env.example in the current directory. Point at other paths with --env and --example when you need to.

Three kinds of drift

Catches keys the example expects but your .env is missing, keys your .env defines that the example doesn’t know about (extra), and required keys that are present but empty.

CI-ready exit codes

Exits 0 when clean, 1 on problems, 2 on a runtime error — a non-zero exit fails the job with no extra wiring.

Library API included

Ships parseEnv and compareEnv alongside the CLI, with one tiny dependency. Works with any dotenv-style project — not framework-specific.

Next steps

Section titled “Next steps”
Quick start From install to a CI gate in a few steps.
CLI Every flag, exit code, and example.
CI Gate pull requests on a drifted env contract.
API Use parseEnv and compareEnv as a library.

MIT   github.com/abdulmunimjemal/dotcheck