env-guard

Catch stupid .env mistakes before deploy. No sync. No presets. Just validation.

Why?

Because you've broken production due to:

• Missing env variable
• Typo in variable name
• Empty value you forgot to fill
• DEBUG=true in production

This tool catches those. Nothing more.

Install

npm install -g env-guard

Usage

# Check current directory
env-guard

# Check specific file
env-guard .env.production

Common Options

# Compare against a specific example file
env-guard --example .env.template

# Strict mode (treat all empty values as errors)
env-guard --strict

# CI mode (GitHub Actions annotations)
env-guard --ci

Note: If .env.example (or the specified example file) is missing, comparison checks are skipped.

That's it. It will:

1. Read .env
2. Compare with .env.example (if exists)
3. Print errors/warnings
4. Exit with code 1 if errors found

What it checks

| Check | Type | Description | |-------|------|-------------| | Missing vars | Error | Key in example but not in env | | Duplicates | Error | Same key defined twice | | Empty values | Warning* | Key has no value | | Unused vars | Warning | Key in env but not in example | | Unsafe defaults | Warning | DEBUG=true, NODE_ENV=development, etc. |

Empty values become errors in --strict mode or for sensitive keys (DATABASE_, PASSWORD, etc.)

Example output

🔍 env-guard validation report

Errors (2)
  ❌ Missing variable: DATABASE_URL (defined in example)
  ❌ Duplicate key: API_KEY (lines 5 and 12)

Warnings (3)
  ⚠️ Empty value: OPTIONAL_VAR
  ⚠️ Unused variable: OLD_CONFIG (not in example)
  ⚠️ Unsafe default: DEBUG=true (may not be suitable for production)

─────────────────────────────
Total: 2 error(s), 3 warning(s)

env-guard: 2 errors, 3 warnings

CI/CD Usage

GitHub Actions

- name: Validate env
  run: npx env-guard --ci --strict

The --ci flag outputs GitHub Actions annotations:

::error file=.env,line=5::Missing variable: DATABASE_URL
::warning file=.env,line=12::Unsafe default: DEBUG=true

Pre-commit Hook

This uses the CLI via a local hook, not a custom pre-commit plugin.

Add to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/YOUR_USERNAME/env-guard
    rev: v1.0.0
    hooks:
      - id: env-guard

What this tool does NOT do

• ❌ Sync files
• ❌ Generate example files
• ❌ Manage secrets
• ❌ Framework integrations
• ❌ Custom rules
• ❌ Type validation

If you need those, use something else.

Security & Privacy

• Runs locally: Your env vars never leave your machine.
• No telemetry: We don't track you.
• No logging: Values are never printed to stdout (except masked) or logged to files.
• No external calls: No analytics, no updates checks, nothing.

MIT