envcheck

Validate .env files against .env.example --- catch missing variables before runtime.

Every dev team has this problem: someone adds a new env var to .env.example but another developer's .env is missing it, leading to a cryptic runtime error. envcheck catches that instantly.

• Zero dependencies --- pure Node.js
• Works in any project that uses .env files
• CI/CD friendly with JSON output and non-zero exit codes
• Respects NO_COLOR for accessibility

Install

# Global
npm install -g envcheck-cli

# Per-project (recommended)
npm install --save-dev envcheck-cli

Usage

# Compare .env against .env.example in current directory
envcheck

# Custom file paths
envcheck --env config/.env.local --example config/.env.example

# Strict mode: fail if .env has extra vars not in .env.example
envcheck --strict

# Fail if any variable has an empty value
envcheck --no-empty

# Combine flags
envcheck --strict --no-empty

# JSON output (for CI pipelines)
envcheck --format json

# CI mode: exit code 1 on any issue
envcheck --ci

Options

Flag	Description	Default
--env <path>	Path to the .env file	.env
--example <path>	Path to the .env.example file	.env.example
--strict	Fail if .env has extra vars not in .env.example	false
--no-empty	Fail if any variable has an empty value	false
--format json	Output results as JSON	text
--ci	Exit code 1 on any issue (extra vars, empty values)	false
-h, --help	Show help message
-v, --version	Show version number

Exit Codes

Code	Meaning
0	All checks passed
1	Issues found (missing, extra in strict mode, or empty vars)
2	Configuration error (file not found, unknown flag)

CI/CD Integration

GitHub Actions

# .github/workflows/envcheck.yml
name: Environment Check
on: [push, pull_request]

jobs:
  envcheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx envcheck-cli --strict --no-empty --ci

GitLab CI

# .gitlab-ci.yml
envcheck:
  stage: validate
  image: node:20-alpine
  script:
    - npx envcheck-cli --strict --no-empty --ci
  rules:
    - changes:
        - .env.example

Pre-commit Hook

Add to your package.json:

{
  "scripts": {
    "prestart": "envcheck --strict --no-empty"
  }
}

Or with Husky:

# .husky/pre-commit
npx envcheck --strict --no-empty

JSON Output

When using --format json, envcheck outputs structured data for programmatic use:

{
  "ok": false,
  "missing": ["DATABASE_URL", "REDIS_URL"],
  "extra": ["DEBUG_MODE"],
  "empty": ["API_KEY"],
  "summary": {
    "missingCount": 2,
    "extraCount": 1,
    "emptyCount": 1
  }
}

How It Works

1. Parses both .env and .env.example files
2. Compares the variable names (keys) between the two files
3. Reports missing variables (in .env.example but not in .env)
4. Reports extra variables (in .env but not in .env.example)
5. Optionally checks for empty values (--no-empty)
6. Ignores comments (#) and blank lines
7. Handles quoted values ("value" and 'value')

License

MIT --- Tate Lyman

---

Support

If you find this useful, consider supporting the project:

SOL Wallet: NaTTUfDDQ8U1RBqb9q5rz6vJ22cWrrT5UAsXuxnb2Wr

• DevTools.run — Free developer tools
• @solscanitbot — Solana trading bot on Telegram
• GitHub Sponsors