envlint

Zero-dependency CLI to validate, secure, and manage your .env files

✓ Zero dependencies    ✓ Zero false positives    ✓ 40+ secret patterns    ✓ Instant

Why envlint?

Every project has .env files. They're also one of the most common sources of:

• Missing variables — "It works on my machine" 🤷
• Leaked secrets — API keys accidentally committed to git
• Inconsistent environments — staging missing production variables
• Duplicated variables — same key defined multiple times

envlint catches all of these issues in milliseconds, with smart secret detection that actually works (no false alarms on URLs, UUIDs, or public keys).

Quick Start

# Just run it in your project directory
npx @asimdelal/envlint

That's it! It validates your .env against .env.example and checks for secrets.

Installation

# Run without installing (recommended for CI/CD)
npx @asimdelal/envlint

# Install globally
npm install -g @asimdelal/envlint

# Install as dev dependency
npm install --save-dev @asimdelal/envlint

Commands

Basic Validation

# Validate .env vs .env.example
envlint

# Validate a specific directory
envlint ./apps/backend

# Strict mode (fail on undocumented variables)
envlint --strict

Generate .env.example

# Generate from .env
envlint -g

# Generate from a specific file
envlint -g .env.production

Compare Environments

# Compare two files (space or comma separated)
envlint -c .env.staging .env.production
envlint -c .env.local,.env.docker

# Exclude environment-specific variables
envlint -c .env.staging .env.prod --exclude NODE_ENV,PORT

# Only check critical variables
envlint -c .env.staging .env.prod --only DATABASE_URL,API_KEY

Multi-Environment Support

envlint automatically handles different env file naming conventions:

# Validate ALL .env files at once
envlint --all

# Smart example file detection
# .env.staging → automatically uses .env.staging.example
envlint -e .env.staging

Auto-pairing logic: | Env File | Tries First | Falls Back To | |----------|-------------|---------------| | .env.staging | .env.staging.example | .env.example | | .env.docker | .env.docker.example | .env.example | | .env.production | .env.production.example | .env.example |

Sync & Create Env Files

# Create .env from .env.example template (for new team members)
envlint --create-env

# Add missing variables to existing .env (when .env.example is updated)
envlint --sync

Example workflow:

# 1. Clone a new project
git clone repo && cd repo

# 2. Create your local .env from the template
envlint --create-env
# ✓ Created .env with 15 variables
# ℹ Fill in the values...

# 3. Later, when .env.example is updated by a teammate
git pull
envlint --sync
# ✓ Added 2 missing variables: NEW_API_KEY, FEATURE_FLAG

Fix Issues

# Auto-remove duplicate variables (keeps first occurrence)
envlint --fix

Protect .env Files

# Add .env patterns to .gitignore
envlint --protect

# Interactive mode (choose which patterns to add)
envlint --protect-interactive

# Check if env files are protected
envlint --check-gitignore

Create Config File

# Generate .envlintrc.json
envlint --init

CLI Reference

| Command | Description | |---------|-------------| | envlint | Validate .env vs .env.example | | envlint --all | Validate ALL .env files (auto-pairs with examples) | | envlint --create-env | Create .env from .env.example template | | envlint --sync | Add missing variables to .env | | envlint -e .env.staging | Validate specific file (auto-finds example) | | envlint -g [file] | Generate .env.example from env file | | envlint -c <f1> <f2> | Compare two env files | | envlint --fix | Auto-fix duplicate variables | | envlint --protect | Add .env to .gitignore | | envlint --init | Create config file | | envlint -h | Show help |

Options

| Option | Description | |--------|-------------| | -e, --env <file> | Env file to validate (auto-finds matching example) | | -x, --example <file> | Override example file (default: auto-detect) | | -a, --all | Validate all .env files in directory | | -s, --strict | Fail on undocumented variables | | --exclude <vars> | Skip variables (comma-separated) | | --exclude-pattern <regex> | Skip variables matching regex | | --only <vars> | Only check these variables | | --no-secrets | Disable secret detection | | --min-confidence <0-1> | Secret detection threshold (default: 0.7) | | --secret-whitelist <vars> | Variables to exclude from secret detection |

What It Checks

1. Missing Variables

Variables in .env.example that are missing from .env:

✗ DATABASE_URL (defined in .env.example but missing in .env)
✗ API_KEY (defined in .env.example but missing in .env)

2. Duplicate Variables

Same variable defined multiple times:

✗ PORT (defined on lines: 3, 15)

Use --fix to automatically remove duplicates (keeps first occurrence).

3. Potential Secrets

Smart detection with zero false positives:

⚠ OPENAI_API_KEY = sk-p***a890
   Line 7: OpenAI API Key
   Confidence: 99%

⚠ STRIPE_SECRET_KEY = sk_l***GHIJ
   Line 12: Stripe Secret Key
   Confidence: 99%

Detected services (40+ patterns):

• OpenAI, Anthropic, HuggingFace, Groq
• GitHub, GitLab, Bitbucket
• AWS, Google Cloud, Azure, DigitalOcean
• Stripe, Square, Plaid
• Slack, Discord, Twilio, SendGrid
• Shopify, Notion, Figma, Postman
• Database connection strings (Postgres, MySQL)
• Private keys (RSA, EC, OpenSSH)
• JWT tokens

Smart filtering (won't flag):

• URLs (https://api.example.com)
• UUIDs (550e8400-e29b-41d4-a716-446655440000)
• Booleans (true, false, enabled)
• Numbers (3000, 0.5)
• Email addresses ([email protected])
• File paths (/etc/ssl/cert.pem)
• Public keys (only private keys are flagged)
• Color codes (#FF5733)

4. Undocumented Variables

Variables in .env but not in .env.example:

ℹ DEBUG (exists in .env but not in .env.example)

In --strict mode, these become errors.

Configuration File

Create a .envlintrc.json for consistent settings across your team:

envlint --init

Example configuration:

{
  "$schema": "https://raw.githubusercontent.com/asimd/envlint/main/schema.json",
  "strict": false,
  "checkSecrets": true,
  "minSecretConfidence": 0.7,
  "exclude": ["NODE_ENV", "PORT", "DEBUG"],
  "excludePattern": "^(TEST_|MOCK_)",
  "secretWhitelist": ["PUBLIC_KEY", "JWKS_URI"],
  "gitignore": {
    "enabled": true,
    "patterns": [".env", ".env.local", ".env.*.local"],
    "autoProtect": false
  }
}

| Option | Type | Default | Description | |--------|------|---------|-------------| | strict | boolean | false | Fail on undocumented variables | | checkSecrets | boolean | true | Enable secret detection | | minSecretConfidence | number | 0.7 | Minimum confidence (0-1) for secrets | | exclude | string[] | [] | Variables to skip | | excludePattern | string | - | Regex pattern to exclude variables | | only | string[] | - | Only check these variables | | secretWhitelist | string[] | [] | Variables excluded from secret detection | | envFile | string | .env | Default env file | | exampleFile | string | .env.example | Default example file |

CLI flags override config file settings.

CI/CD Integration

GitHub Actions

name: Validate Env Files
on: [push, pull_request]

jobs:
  envlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx @asimdelal/envlint --strict

Compare environments in CI:

- run: npx @asimdelal/envlint -c .env.staging .env.production --exclude NODE_ENV

GitLab CI

envlint:
  script: npx @asimdelal/envlint --strict

env-compare:
  script: npx @asimdelal/envlint -c .env.staging .env.prod

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit
npx @asimdelal/envlint --strict || exit 1

Or use with husky:

{
  "husky": {
    "hooks": {
      "pre-commit": "npx @asimdelal/envlint --strict"
    }
  }
}

Programmatic API

Use envlint as a library in your Node.js code:

import {
  validateEnv,
  parseEnvFile,
  detectSecrets,
  hasErrors,
} from '@asimdelal/envlint';

// Parse an env file
const vars = parseEnvFile('.env');

// Detect secrets
const secrets = detectSecrets(vars, {
  whitelist: ['PUBLIC_KEY'],
  minConfidence: 0.8,
});

// Full validation
const result = validateEnv({
  envPath: '.env',
  examplePath: '.env.example',
  checkSecrets: true,
  strict: false,
});

if (hasErrors(result, false)) {
  console.log('Issues found:', result.missingInEnv);
}

Exported Functions

| Function | Description | |----------|-------------| | validateEnv(options) | Full validation of env files | | parseEnvFile(path) | Parse env file to array of {key, value, lineNumber} | | detectSecrets(vars, options) | Detect potential secrets in variables | | findDuplicates(vars) | Find duplicate variable definitions | | filterVariables(vars, options) | Filter variables by exclude/only rules | | generateExample(vars, path) | Generate .env.example file | | hasErrors(result, strict) | Check if validation has errors |

Examples

Validate a Clean Project

$ envlint

envlint v1.2.5

Directory: /Users/me/project

══════════════════════════════════════════════════
✓ All checks passed! Your .env files are clean.

Issues Found

$ envlint

envlint v1.2.5

Missing in .env
──────────────────────────────────────────────────
✗ DATABASE_URL (defined in .env.example but missing in .env)

Duplicate Variables in .env
──────────────────────────────────────────────────
✗ PORT (defined on lines: 1, 3)

⚠️  Potential Secrets Detected
──────────────────────────────────────────────────
⚠ OPENAI_API_KEY = sk-p***a890
   Line 7: OpenAI API Key
   Confidence: 99%

══════════════════════════════════════════════════
✗ Found 3 issue(s)

Compare Environments

$ envlint -c .env.staging .env.production

envlint v1.2.5

ℹ Compare mode: .env.staging ↔ .env.production

Missing in .env.staging
──────────────────────────────────────────────────
✗ REDIS_URL (defined in .env.production but missing in .env.staging)
✗ CDN_URL (defined in .env.production but missing in .env.staging)

══════════════════════════════════════════════════
✗ Found 2 issue(s)

Generate .env.example

$ envlint -g

envlint v1.2.5

ℹ Generating .env.example from .env...
✓ .env.example generated at /Users/me/project/.env.example

Auto-fix Duplicates

$ envlint --fix

envlint v1.2.5

Fixing Issues
──────────────────────────────────────────────────
✓ Removed 2 duplicate variable(s) from .env
  • PORT
  • API_KEY

ℹ Re-run envlint to verify fixes

Exit Codes

| Code | Meaning | |------|---------| | 0 | All checks passed | | 1 | Issues found (or error occurred) |

Use exit codes in CI/CD to fail pipelines when issues are detected.

Why envlint vs Other Tools?

| Feature | envlint | dotenv-linter | dotenv-safe | |---------|---------|---------------|-------------| | Zero dependencies | ✅ | ❌ | ❌ | | Secret detection | ✅ (40+ patterns) | ❌ | ❌ | | Zero false positives | ✅ | - | - | | Compare any two files | ✅ | ❌ | ❌ | | Exclude/filter variables | ✅ | ❌ | ❌ | | Auto-fix duplicates | ✅ | ❌ | ❌ | | Generate .env.example | ✅ | ❌ | ❌ | | Gitignore protection | ✅ | ❌ | ❌ | | Config file support | ✅ | ❌ | ❌ | | TypeScript types | ✅ | - | - |

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

git clone https://github.com/asimd/envlint.git
cd envlint
npm install
npm run build
npm test

License

MIT © asimd