envcheck-cli

Validate .env files against .env.example — find missing, extra, and empty environment variables instantly.

Stop debugging broken deployments caused by missing env vars. Run envcheck in CI/CD or locally to catch issues before they hit production.

Install

npm install -g envcheck-cli

Usage

# Compare .env against .env.example (defaults)
envcheck

# Use a custom template
envcheck --template .env.production

# Strict mode for CI/CD (exits with code 1 if vars missing)
envcheck --strict

# JSON output (pipe to jq, use in scripts)
envcheck --format json

# Custom env file path
envcheck --env .env.local --template .env.example

# Strict mode with additional checks
envcheck --strict --strict-empty --strict-extra

What it reports

• Missing variables — in template but not in your .env
• Extra variables — in your .env but not in template
• Empty variables — defined but have no value
• Template defaults — variables with default values in the template

Example output

envcheck — Environment Variable Validation

  Env file:      /app/.env
  Template file: /app/.env.example

  9 env vars | 11 template vars

  ✗ Missing variables (2):
    - SENDGRID_API_KEY
    - REDIS_URL

  ⚠ Extra variables (1):
    - DEBUG_MODE

  ⚠ Empty variables (1):
    - AUTH_PROVIDER (line 7)

  ℹ Template defaults (3):
    - APP_PORT = 3000
    - APP_ENV = development
    - DATABASE_POOL_SIZE = 10

  ✗ Validation failed: 2 missing variable(s).

JSON output

envcheck --format json

{
  "envFile": "/app/.env",
  "templateFile": "/app/.env.example",
  "isValid": false,
  "summary": {
    "totalEnvVars": 9,
    "totalTemplateVars": 11,
    "missingCount": 2,
    "extraCount": 1,
    "emptyCount": 1,
    "defaultsCount": 3
  },
  "missing": ["SENDGRID_API_KEY", "REDIS_URL"],
  "extra": ["DEBUG_MODE"],
  "empty": ["AUTH_PROVIDER"],
  "withDefaults": [
    { "key": "APP_PORT", "value": "3000" },
    { "key": "APP_ENV", "value": "development" },
    { "key": "DATABASE_POOL_SIZE", "value": "10" }
  ]
}

CI/CD integration

GitHub Actions

- name: Validate env vars
  run: npx envcheck-cli --strict

Pre-commit hook

# .husky/pre-commit
npx envcheck-cli --strict

Options

| Flag | Description | Default | |------|-------------|---------| | -e, --env <path> | Path to .env file | .env | | -t, --template <path> | Path to template file | .env.example | | -s, --strict | Exit code 1 if any vars missing | false | | -f, --format <format> | Output format: text or json | text | | --strict-empty | Also fail on empty variables in strict mode | false | | --strict-extra | Also fail on extra variables in strict mode | false |

License

MIT