Env Diff Checker

Catch configuration drift before it becomes a runtime problem or a contributor onboarding failure. env-diff-checker compares .env.example with a real .env file and reports missing keys, extra keys, blank values, duplicates, invalid dotenv lines, placeholder-looking values, and simple format mismatches.

The tool is built for local checks and CI. It reads plain dotenv-style files and does not load or export variables into the current process.

Why Maintainers Use It

Open-source projects often lose maintainer time to broken local setup, stale examples, and release configuration drift. Env Diff Checker gives maintainers a small CI guardrail that keeps documented environment variables aligned with the actual project.

Installation

From source:

git clone https://github.com/chunjiegame-cpu/env-diff-checker.git
cd env-diff-checker
npm install
node bin/env-diff.js --help

As a package after publishing:

npm install -g env-diff-checker
env-diff

Usage

env-diff
env-diff --example .env.example --env .env.local
env-diff --json
env-diff --allow-extra
env-diff --out env-diff-report.md
env-diff --no-fail

Sample Output

Env Diff Checker report
Example: .env.example
Actual: .env
Status: CHECK

Missing variables
- DATABASE_URL (line 2 in example)

Blank values
- SESSION_SECRET (line 8)

Suspicious values
- API_TOKEN: actual value still looks like a placeholder

What It Detects

Finding	Example
Missing variable	DATABASE_URL exists in .env.example but not .env.
Extra variable	.env contains a key not documented in .env.example.
Blank value	API_TOKEN= is present but empty.
Duplicate declaration	The same key appears more than once.
Invalid line	A non-comment line is not valid KEY=value syntax.
Placeholder value	The real env still says changeme, replace-me, or matches the example.
Type mismatch	Example says PORT=3000, actual says PORT=abc.

CLI Reference

Option	Description
--example <file>	Path to the example file. Defaults to .env.example.
--env <file>	Path to the actual env file. Defaults to .env.
--json	Print machine-readable JSON.
--allow-extra	Do not treat extra actual variables as a failure.
--no-fail	Always exit 0 if files can be read. Useful for reports.
-o, --out <file>	Write a Markdown report.
-h, --help	Show help.

CI Example

name: env drift
on: [pull_request]
jobs:
  env:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npx env-diff --example .env.example --env .env.ci

Maintainer Workflow

1. Keep .env.example reviewed as part of every config change.
2. Run env-diff --example .env.example --env .env.ci in pull requests.
3. Use --out env-diff-report.md when filing setup issues for new contributors.
4. Pair JSON output with Codex or another automation to propose safer .env.example updates.

Programmatic API

import { compareEnv } from "env-diff-checker";

const result = compareEnv(exampleText, actualText, { allowExtra: false });
if (!result.ok) {
  console.log(result.missing, result.suspicious);
}

Parser Notes

• Supports KEY=value and export KEY=value.
• Ignores blank lines and full-line comments.
• Preserves # inside quoted values.
• Strips inline comments such as DEBUG=true # local.
• The last duplicate value wins, but duplicates are still reported.

Exit Codes

Code	Meaning
0	No findings, or --no-fail was used.
1	Files could not be read, arguments were invalid, or drift was found.

Known Limits

• It does not decrypt secret managers or read shell profile files.
• Type inference is intentionally conservative and based on example values.
• It does not validate whether URLs or credentials are reachable.

Development

npm install
npm test
node bin/env-diff.js --help

Parser changes should include cases for quoted values, inline comments, duplicates, and malformed lines.

Codex for OSS Notes

See docs/codex-for-oss.md for a concise maintainer-oriented project summary and API-credit usage plan.

License

MIT