env-lint-cli 🔍

Lint and validate your .env files against .env.example. Find missing vars, extra vars, empty values, and type mismatches instantly.

Why?

Ever deployed and realized you forgot to set DATABASE_URL? Or had a teammate onboard with a stale .env? env-lint catches these issues before they become runtime errors.

• ✅ Zero dependencies — just Node.js built-ins
• ✅ Fast — runs in milliseconds, even on large .env files
• ✅ CI-ready — --strict mode exits non-zero on any issue

Install

npm install -g env-lint-cli

Or run directly without installing:

npx env-lint-cli

Usage

# Compare .env with .env.example (default)
env-lint

# Compare specific files
env-lint .env.staging .env.example

# Full audit with type checking
env-lint --types --verbose

# Use in CI (fails on any issue)
env-lint --strict

What It Checks

Check	Flag	Description
Missing vars	always	Variables in .env.example but not in .env
Extra vars	always	Variables in .env but not in .env.example
Empty values	always	Vars that are empty but have example values
Type mismatches	--types	Different types between files (url vs string, boolean vs integer, etc.)

Example Output

🔍 env-lint: comparing .env against .env.example

❌ 2 missing variable(s):
  MISSING DATABASE_URL (example: postgresql://localhost:5432/mydb)
  MISSING REDIS_URL (example: redis://localhost:6379)

⚠ 1 extra variable(s) not in example:
  EXTRA   DEBUG_MODE

⚠ 1 empty variable(s) that should have values:
  EMPTY   API_KEY (example: your-api-key-here)

2 error(s) | 2 warning(s) | 3/5 variables matched

Options

-t, --types     Check type consistency between files
-v, --verbose   Show detailed variable listing
-s, --strict    Treat warnings as errors (for CI)
-h, --help      Show help
--version       Show version

CI Integration

GitHub Actions

- name: Validate environment config
  run: npx env-lint-cli --strict

GitLab CI

env-check:
  script:
    - npx env-lint-cli --strict
  rules:
    - changes:
        - .env.example

Pre-commit Hook

#!/bin/sh
# .git/hooks/pre-commit
npx env-lint-cli --strict || exit 1

package.json

{
  "scripts": {
    "env:check": "env-lint --strict",
    "pretest": "env-lint --strict"
  }
}

Use Cases

• Onboarding — New teammate clones the repo, runs env-lint, instantly sees what's missing
• Pre-deploy gate — Catch missing config before it hits production
• Docker builds — Validate .env against .env.example in your Dockerfile
• Monorepos — Run per-package: env-lint packages/api/.env packages/api/.env.example
• Staging vs Production — Compare .env.staging against .env.production for drift

Comparison with Alternatives

Feature	env-lint-cli	dotenv-safe	envalid	env-cmd
CLI tool	✅	❌ (library)	❌ (library)	❌ (runner)
Missing var detection	✅	✅	✅	❌
Extra var detection	✅	❌	❌	❌
Empty value detection	✅	❌	✅	❌
Type checking	✅	❌	✅	❌
Zero dependencies	✅	✅	❌	❌
Works without code changes	✅	❌	❌	❌
CI-friendly exit codes	✅	N/A	N/A	N/A

Key difference: env-lint-cli is a standalone CLI that works without modifying your application code. dotenv-safe and envalid require importing them into your app.

Best Practices for .env.example

# .env.example — commit this to your repo
# Use realistic placeholder values that hint at the expected format

DATABASE_URL=postgresql://localhost:5432/mydb
REDIS_URL=redis://localhost:6379
API_KEY=your-api-key-here
PORT=3000
DEBUG=false
LOG_LEVEL=info

Tip: Never put real secrets in .env.example. Use descriptive placeholders like your-api-key-here instead.

Related Tools

• commitwiz-ai — AI-powered git commit messages
• npm-name-check — Check npm package name availability
• dep-size — Check npm package size before installing
• license-maker — Generate LICENSE files from CLI

License

MIT © kszongic

Support

If this tool saved you from a deployment disaster, consider sponsoring! ☕