https://github.com/lorenzopant/envdrift
CLI that finds keys missing or extra across your .env files — catch config drift between local, staging, and production before it breaks a deploy.
https://github.com/lorenzopant/envdrift
cli diff drift drift-detection drift-monitoring env env-dev env-drift environment-variables
Last synced: 4 days ago
JSON representation
CLI that finds keys missing or extra across your .env files — catch config drift between local, staging, and production before it breaks a deploy.
- Host: GitHub
- URL: https://github.com/lorenzopant/envdrift
- Owner: lorenzopant
- License: mit
- Created: 2026-06-07T10:30:19.000Z (27 days ago)
- Default Branch: main
- Last Pushed: 2026-06-07T10:53:14.000Z (27 days ago)
- Last Synced: 2026-06-07T12:19:29.774Z (27 days ago)
- Topics: cli, diff, drift, drift-detection, drift-monitoring, env, env-dev, env-drift, environment-variables
- Language: TypeScript
- Homepage:
- Size: 43.9 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# envdrift 🌱⚡
CLI that detects drift between `.env*` files in a project — catches the case
where a variable is set in `.env.local` but missing from `.env.production`
(or vice versa) before it causes a runtime surprise.
It compares **keys only**, never values — no secrets are read into memory or
printed. 🔒
## 📦 Install / run
Published as a scoped package — install globally and run as `envdrift`:
```bash
npm install -g @lorenzopant/envdrift
envdrift [dir]
```
Or run it ad-hoc without installing:
```bash
npx @lorenzopant/envdrift [dir]
```
### From source
```bash
pnpm install
pnpm run build
node dist/index.js [dir]
```
Or during development, skip the build step:
```bash
pnpm dev [dir]
```
`[dir]` defaults to the current directory.
## 🚀 Usage
```bash
envdrift [dir] [options]
```
| Option | Description |
| --- | --- |
| `--depth ` | max directory depth to scan (default: `5`) |
| `--autofix` | append missing keys (empty value) to files where they're absent, marked with a `# --- added by envdrift --autofix ---` comment |
| `--md [path]` | write a Markdown drift report to `` (default: `envdrift-report.md`) |
| `--fail-on-drift` | exit with code `1` when drift is found (CI/CD gate) |
### Example
```
$ envdrift .
Scanned 3 env file(s):
- .env (4 keys)
- .env.local (4 keys)
- .env.production (7 keys)
Drift found in 3 key(s):
Legend:
F1 = .env
F2 = .env.local
F3 = .env.production
F1 F2 F3
------------ -- -- --
GITHUB_TOKEN ✗ ✓ ✗
RATE_LIMIT_MAX ✗ ✗ ✓
SENTRY_DSN ✗ ✗ ✓
```
By default, exit code is always `0` — envdrift reports drift without failing
your build. Pass `--fail-on-drift` to exit with code `1` when drift is found,
turning it into a CI/CD gate:
```bash
envdrift . --fail-on-drift
```
Use `--md` to produce a file you can attach to CI artifacts or PRs if you want
drift to be visible in review regardless of whether the build fails.
## ⚙️ How it works
1. **Scan** — recursively find `.env*` files (skips `node_modules`, `.git`,
build output dirs).
2. **Parse** — read each file's keys via `dotenv` (values discarded).
3. **Diff** — build a presence matrix across all files; any key not present
in every file counts as drift.
4. **Report** — render as a terminal matrix, optionally a Markdown file, and
optionally autofix by appending missing keys with empty values.
## 🗂️ Project layout
```
src/
scanner.ts find .env* files on disk
parser.ts parse a file into its set of keys
diff.ts build the drift report (presence matrix)
report.ts render the report (terminal matrix, Markdown)
autofix.ts append missing keys to files
index.ts CLI entry point (commander)
```
## 🤝 Contributing
Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for setup,
dev workflow, and conventions. Please follow our
[Code of Conduct](CODE_OF_CONDUCT.md).
## 📄 License
[MIT](LICENSE) © Lorenzo Pantano