🪄 env-parity

Keep your team's .env files perfectly aligned.
No missing keys. No exposed secrets. No more "works on my machine."

The Problem

You push a feature. A teammate pulls it. Their app crashes because STRIPE_WEBHOOK_SECRET was never added to .env.example. Sound familiar?

env-parity solves this by scanning your entire repository, detecting which .env files have drifted from their templates, and letting you fix everything interactively — in seconds.

Features

• 🔒 Zero-value policy — Only variable names are ever read. Your secrets are never echoed, stored, or copied.
• 📦 Monorepo-native — Recursively scans your entire codebase and isolates comparisons per directory scope.
• 🧠 Smart pairing — Auto-detects .env.example / .env.sample / .env.template as the source of truth. Falls back to .env if none exists.
• 🛠️ Interactive fixes — A beautiful terminal UI to safely append missing keys across your project.
• 🤖 CI-safe — analyze always exits 0. fix requires a real TTY and exits 1 in headless environments to prevent blocking pipelines.

Quick Start

No installation required:

# See what's out of sync (read-only)
npx env-parity analyze

# Interactively fix the drift
npx env-parity fix

# Generate missing .env.example files
npx env-parity generate

Or install globally:

npm install -g env-parity
env-parity analyze

Commands

analyze [root]

Scans from root (defaults to cwd) and prints a human-readable drift report.

npx env-parity analyze
npx env-parity analyze ./apps/api

Non-destructive. Always exits with code 0. Safe to run anywhere.

fix [root]

Launches an interactive session to repair drift. Shows you exactly which keys are missing, asks for confirmation, and safely appends KEY= (without values) to the target files.

npx env-parity fix
npx env-parity fix ./apps/api

Requires a real TTY. Exits with code 1 in headless/CI environments.

generate [root]

For every directory that has a .env but no .env.example, generates a pristine example file with all keys and empty values.

npx env-parity generate
npx env-parity generate ./apps

Values are always stripped. Never overwrites an existing .env.example.

Example Output

╭──────────────────────────────╮
│  env-parity  · drift report   │
╰──────────────────────────────╯

  ✔  In sync  (2 pairs)
     apps/api      → .env.local
     apps/frontend → .env.local

  ✖  Drift detected  (1 pair)

     apps/worker   .env.example ↔ .env
       - Missing:  REDIS_URL, WORKER_CONCURRENCY
       + Extra:    TEST_MODE_ENABLED

──────────────────────────────────────────────────
  1 pair has drift — run npx env-parity fix to repair

How It Works

env-parity groups your files by directory. Each directory is its own isolated scope.

1. Establishing the Reference

The reference file is the source of truth for a given scope:

1. Preferred: .env.example, .env.sample, or .env.template (if any exist)
2. Fallback: .env is promoted to reference if no example file is found

2. Calculating Drift

Every other env file in the scope (.env.local, .env.test, .env.staging, etc.) is compared against the reference:

| Status | Meaning | |--------|---------| | Missing | Key is in the reference but absent from the target | | Extra | Key is in the target but absent from the reference |

Project Structure

src/
├── cli.ts              # CLI entry point (Commander)
├── commands/
│   ├── analyze.ts      # Drift report orchestration
│   ├── fix.ts          # Interactive TTY repair
│   └── generate.ts     # .env.example generation
├── core/
│   ├── scanner.ts      # File discovery, classification, grouping
│   ├── comparer.ts     # Drift model, key parsing, repair logic
│   └── transformer.ts  # Example file content builder
├── infra/
│   ├── fs.ts           # Atomic file writes
│   └── ui.ts           # Terminal UI rendering
└── types.ts            # Public type exports

Contributing

Issues and pull requests are welcome!

git clone https://github.com/lucas-burlot/env-parity.git
cd env-parity
npm install

# Run in dev mode
npm run dev -- analyze ./path/to/test-project

# Run tests
npm test

# Build for production
npm run build

Please run npm test before submitting a PR to verify snapshot determinism and pure logic tests.

License

MIT © Lucas Burlot