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