Skip to content

About

CLI tool for .env drift detection — catches missing, extra, and type-invalid variables, scans your codebase for undocumented usage, diffs environments, and audits git safety. Zero config changes required.

Topics

Resources

Stars

18 stars

Watchers

0 watching

Forks

Repository files navigation

env-drift-check

Detect .env drift, enforce schema validation, scan your codebase, diff environments, and audit git safety — zero config required.

npm version npm downloads License: MIT TypeScript Node.js Tests

env-drift-check CLI output

npx env-drift-check

✔ Loaded: .env
✔ Base: .env.example

✖ Missing keys:
  - DATABASE_URL
  - STRIPE_SECRET_KEY

⚠ Unused keys:
  - OLD_API_KEY

❌ Validation failed: PORT must be a number

Fix interactively:

npx env-drift-check -i

Missing environment variables crash apps in production. Wrong types create silent bugs. Leaked .env files in git history are a permanent problem. env-drift-check catches all of this from the CLI — without touching your application code.

  • Compares .env against .env.example and reports missing, extra, and mismatched keys
  • Validates values against a schema (type, range, pattern, enum, email, URL)
  • Scans JS/TS source for process.env.* references — works even without a .env file
  • Flags low-entropy secrets using Shannon entropy math
  • Warns when NEXT_PUBLIC_, VITE_, or REACT_APP_ prefixed variables look like server secrets
  • Checks .env files against .gitignore, git tracking, and full git history
  • Splits .env into Kubernetes ConfigMap + Secret YAML
  • Validates docker-compose.yml environment blocks against your schema
  • Validates across all packages in a monorepo with per-package config

Installation

npm install --save-dev env-drift-check

Works with any Node.js ≥ 16 project.


Commands

npx env-drift-check                          # compare .env against .env.example
npx env-drift-check --strict                 # exit 1 on any issue (CI/CD)
npx env-drift-check --system-env --strict    # validate process.env (containers/serverless)
npx env-drift-check --watch                  # re-validate on file save
npx env-drift-check --format json            # JSON output
npx env-drift-check --format sarif           # SARIF for GitHub Security tab
npx env-drift-check -i                       # interactive setup wizard

npx env-drift-check scan                     # report env references vs .env.example
npx env-drift-check scan --fix               # create/update .env.example from found keys

npx env-drift-check diff .env.staging .env.production    # side-by-side diff of two .env files
npx env-drift-check audit                                # check .env files for git tracking/history leaks
npx env-drift-check gen-example                          # generate .env.example from .env (strips values)
npx env-drift-check gen-configmap                        # split .env into K8s ConfigMap + Secret YAML
npx env-drift-check validate-compose                     # validate docker-compose.yml env blocks
npx env-drift-check monorepo --packages "packages/*"     # validate across all packages, aggregate results
npx env-drift-check init                                 # scaffold envwise.config.json + .env.example

Configuration

envwise.config.json is optional. Add it when you need type validation or custom rules:

{
  "baseEnv": ".env.example",
  "rules": {
    "PORT":         { "type": "number",  "min": 1024, "max": 65535 },
    "NODE_ENV":     { "type": "enum",    "values": ["development", "staging", "production"] },
    "DEBUG_MODE":   { "type": "boolean", "mustBeFalseIn": "production" },
    "DATABASE_URL": { "type": "url",     "required": true },
    "ADMIN_EMAIL":  { "type": "email" },
    "API_KEY":      { "type": "regex",   "regex": "^sk_(test|live)_[0-9a-zA-Z]{24}$" },
    "JWT_SECRET":   { "type": "string",  "checkSecretStrength": true },
    "OLD_KEY":      { "type": "string",  "deprecated": "Use NEW_KEY instead." }
  }
}

Validation types

Type Options Notes
string min, max, checkSecretStrength Entropy check auto-enabled for keys named *SECRET*, *PASSWORD*
number min, max
boolean mustBeFalseIn, mustBeTrueIn Enforce flags per environment
enum values: []
email, url, regex regex for regex type

Rule options

Option Description
required Defaults to true. Set false to make optional.
default Fallback value — key is never reported missing.
requiredIf Required only when another key matches a value: { "STORAGE": "s3" }
deprecated Emits a warning. Pass a string for a migration message.
description Shown in interactive prompts.

Config inheritance

{
  "extends": "../base.config.json",
  "rules": {
    "DATABASE_URL": { "type": "url", "required": true }
  }
}

Child rules override parent on conflict. Circular references exit with an error.


CI/CD

A ready-to-use workflow is at .github/workflows/env-check.yml.

- name: Check environment drift
  run: npx env-drift-check --system-env --strict
  env:
    DATABASE_URL: ${{ secrets.DATABASE_URL }}
    API_SECRET_KEY: ${{ secrets.API_SECRET_KEY }}

Or use the marketplace action:

- uses: shashi089/env-drift-check@v1
  with:
    command: check
    strict: 'true'

Pre-commit hook

npm install --save-dev husky
npx husky init
echo "npx env-drift-check --strict" > .husky/pre-commit

With lint-staged (only runs when .env.example or the config changes):

{
  "lint-staged": {
    ".env.example": "npx env-drift-check --strict",
    "envwise.config.json": "npx env-drift-check --strict"
  }
}

Programmatic usage

import { checkDrift, loadConfig, parseEnv, report } from 'env-drift-check';

const config = loadConfig();
const base = parseEnv('.env.example');
const target = parseEnv('.env');

const result = checkDrift(base, target, config);
if (result.missing.length || result.errors.length) {
  report(result);
  process.exit(1);
}

See the API reference for all exports. examples/demo-app has a real-world integration.


vs. similar tools

Feature dotenv-safe envalid dotenv-linter dotenvx env-drift-check
Missing key detection ✅ ✅ ✅ ⚠️ basic ✅
Runtime library ✅ ✅ ❌ ✅ ⚠️ secondary
CI/CD friendly ✅ ✅ ✅ ✅ ✅
Encryption ❌ ❌ ❌ ✅ ❌
Standalone CLI ❌ ❌ ✅ ✅ ✅
Schema validation (no code changes) ❌ ❌ ❌ ❌ ✅
Interactive fix wizard ❌ ❌ ❌ ❌ ✅
Codebase scanner ❌ ❌ ❌ ❌ ✅
Entropy-based secret scoring ❌ ❌ ❌ ❌ ✅
Git safety audit ❌ ❌ ❌ ❌ ✅
Environment diff ❌ ❌ ✅ ❌ ✅
Framework prefix safety ❌ ❌ ❌ ❌ ✅
Docker / Kubernetes support ❌ ❌ ❌ ❌ ✅

Examples


CHANGELOG · ROADMAP · MIT License · Issues


If this saved you time, a ⭐ on GitHub helps others find it.

About

CLI tool for .env drift detection — catches missing, extra, and type-invalid variables, scans your codebase for undocumented usage, diffs environments, and audits git safety. Zero config changes required.

Topics

Resources

Stars

18 stars

Watchers

0 watching

Forks

Contributors

Languages