env-drift-hunter

When to use this skill

• A user has two or more .env files and wants to compare them.
• A user is debugging "works locally, breaks in prod" — almost always env drift.
• A user is deploying to a new environment and needs to verify all required vars are set.
• A user is onboarding a new developer and wants to generate a .env.example.
• A user asks "what environment variables does this project actually use?"

Environment drift is the #1 cause of "works on my machine" failures. A variable
that's set in .env.local but missing in .env.production — or worse, set to a
different value — causes silent failures, wrong API endpoints, and 3am pages.

How env drift happens

.env.local           .env.staging         .env.production
─────────────        ─────────────        ─────────────────
DATABASE_URL=...     DATABASE_URL=...     DATABASE_URL=...     ✓ same
REDIS_URL=...        REDIS_URL=...        (missing)           ✗ MISSING in prod
LOG_LEVEL=debug      LOG_LEVEL=info       LOG_LEVEL=warn      ~ CHANGED
API_KEY=dev_xxx      API_KEY=stg_xxx      (missing)           ✗ MISSING in prod
STRIPE_KEY=          STRIPE_KEY=sk_...    STRIPE_KEY=sk_live  ~ CHANGED
NEW_FEATURE_FLAG=1   (missing)           (missing)           ✗ ONLY in local

The dangerous ones are missing in prod (the app crashes) and changed (the app
points to the wrong service). Extra-in-local is less dangerous but causes confusion.

How to hunt drift

Step 1: Find all .env files

# All env files in the project (excluding node_modules, .git)
find . -name ".env*" -not -path "*/node_modules/*" -not -path "*/.git/*" | sort

Common patterns: .env, .env.local, .env.development, .env.staging,
.env.production, .env.test, .env.example, .env.defaults.

Step 2: Parse and compare

For each .env file, extract the variable names and values. Compare them:

• Missing: present in one file but not another → potential crash in the missing env.
• Extra: present only in one file → may be a stale var or a new var not yet deployed.
• Changed: same name, different value → verify this is intentional (e.g. different

API endpoints per environment is normal; different LOG_LEVEL might be a mistake).

Parsing rules:

• KEY=VALUE — standard
• KEY="VALUE" / KEY='VALUE' — quoted values (strip quotes)
• export KEY=VALUE — shell-style (strip export)
• # comment — ignore (but note commented-out vars, they may be intentionally disabled)
• Empty value KEY= is different from missing KEY — an empty value means "explicitly

set to nothing", missing means "not set at all."

Step 3: Find what the code actually uses (12-language scan)

Don't just compare files — find which env vars the codebase actually references. A var
in .env that no code reads is dead config. A var that code reads but isn't in .env
will crash at runtime.

Language-specific env var reference patterns:

| Language | Pattern | Example |
|----------|---------|---------|
| Node.js | process.env.KEY | process.env.DATABASE_URL |
| Python | os.environ['KEY'] / os.getenv('KEY') | os.getenv('API_KEY') |
| Ruby | ENV['KEY'] | ENV['STRIPE_SECRET'] |
| Go | os.Getenv("KEY") | os.Getenv("PORT") |
| Rust | env::var("KEY") / env!("KEY") | env::var("DATABASE_URL") |
| Java | System.getenv("KEY") | System.getenv("JWT_SECRET") |
| PHP | getenv('KEY') / $_ENV['KEY'] | getenv('API_KEY') |
| Dockerfile | ENV KEY=value / ARG KEY | ENV NODE_ENV=production |
| Shell | $KEY / ${KEY} | ${DATABASE_URL} |
| YAML/CI | ${{ secrets.KEY }} / ${KEY} | ${{ secrets.DOCKER_PASSWORD }} |
| TOML | in [env] or inline | database_url = "..." |
| JS/TS (Vite) | import.meta.env.KEY / VITE_KEY | import.meta.env.VITE_API_URL |

Regex for finding all env var references across a codebase:

process\.env\.([A-Z_][A-Z0-9_]*)
os\.(?:environ|getenv)\(?['"]([A-Z_][A-Z0-9_]*)['"]\)?
ENV\[(['"]?[A-Z_][A-Z0-9_]*)['"]?\]
os\.Getenv\("([A-Z_][A-Z0-9_]*)"\)
env(?:!)?::var\("([A-Z_][A-Z0-9_]*)"\)
System\.getenv\("([A-Z_][A-Z0-9_]*)"\)
getenv\(['"]([A-Z_][A-Z0-9_]*)['"]\)
\$\{?\{([A-Z_][A-Z0-9_]*)\}?

Step 4: Generate the drift report

Present the results as a clear diff table:

Variable              .env.local     .env.staging   .env.production    Status
───────────────────── ────────────── ────────────── ────────────────── ────────
DATABASE_URL          ✓ postgres://… ✓ postgres://… ✓ postgres://…     ✓ same
REDIS_URL             ✓ redis://…    ✓ redis://…    ✗ MISSING          ⚠️ MISSING
LOG_LEVEL             = debug        = info         = warn             ~ changed
API_KEY               ✓ dev_xxx      ✓ stg_xxx      ✗ MISSING          ⚠️ MISSING
SENTRY_DSN            ✗ missing      ✗ missing      ✓ https://…        ◯ prod-only
NEW_FEATURE_FLAG      = 1            ✗ missing      ✗ missing          ◯ local-only
DEPRECATED_VAR        ✓ (commented)  ✓ old_value    ✓ old_value        💀 dead code

Code references found but not in ANY .env file:
  → JWT_SECRET (used in src/auth.js:42)
  → SMTP_PASSWORD (used in src/email.js:18)

In .env files but no code reference found:
  → LEGACY_API_KEY (dead config, safe to remove)

Common pitfalls to flag

1. Secrets in .env.example: .env.example should have placeholder values

(STRIPE_KEY=sk_test_xxx), never real secrets. If you see a real-looking key,
flag it — it may have been committed by mistake.

1. Production secrets in local .env: if .env.local contains sk_live_...

(live Stripe key) or a production database URL, that's a security risk. Developers
should use test/sandbox keys locally.

1. Commented-out vars: # DATABASE_URL=... means the var is disabled. This is

different from the var being absent. Commented vars may indicate a feature that was
toggled off and forgotten.

1. .env committed to git: check .gitignore. If .env is NOT in .gitignore,

real secrets may be in git history. Run git log --all -- .env to check.

1. Empty vs missing: KEY= (empty string) behaves differently from the key being

entirely absent. Code like if (process.env.FEATURE_FLAG) will be falsy for empty
string, but process.env.FEATURE_FLAG ?? 'default' will use empty string not default.

Generating .env.example

When generating a .env.example from a real .env:

1. Copy all variable names, keep the structure.
2. Replace all values with descriptive placeholders: DATABASE_URL=postgres://user:pass@host:5432/db
3. Detect sensitive keys by name pattern: KEY, SECRET, PASSWORD, TOKEN, CREDENTIAL

and add a comment: # Keep this secret — never commit the real value

1. Add type hints as comments: # boolean: set to "true" or "false"
2. Group related vars: database, cache, auth, feature-flags.