dotenv-diff Documentation
May 29, 2026 ยท View on GitHub
Welcome to the official documentation for dotenv-diff.
dotenv-diff scans your codebase for environment variable usage and compares it against your .env and/or .env.example files.
It helps you:
- Detect missing environment variables
- Detect unused variables in your
.envfiles - Prevent runtime crashes caused by undefined
process.envusage - Enforce consistent environment configuration across teams
- Apply framework-specific validation rules (SvelteKit, Next.js, etc.)
The tool is designed to be fast, CI-friendly, and safe to run in large projects and monorepos.
Quick Start
Install:
npm install dotenv-diff
Run:
npx dotenv-diff
If no .env files are found, dotenv-diff will prompt you to create one (interactive mode only).
Use --yes to auto-accept prompts, or --ci to disable prompts and run read-only.
If you choose not to create a file, dotenv-diff will still scan your codebase for environment variable usage, but it will not compare results against an .env file.
Table of Contents
| Document | Description |
|---|---|
| Capabilities | What the scanner checks for and how it works |
| Configuration and Flags | Full CLI/config reference for options and behavior |
| Baseline Workflow | Set a warning baseline and suppress already-known findings safely |
| Comparing Files | How to compare two .env files to detect differences |
| Expiration Warnings | How @expire annotations work and strict mode integration |
| Ignore Comments | Suppress false positives with inline/block ignore markers |
| Monorepo Support | Scan shared packages and cross-folder usage in monorepos |
| Git Hooks and CI/CD | Integrate dotenv-diff with Husky, lint-staged, and GitHub Actions |
| Framework Warnings (Index) | Framework detection and links to supported framework rules |
| SvelteKit warnings | SvelteKit-specific env validation rules |
| Next.js warnings | Next.js-specific env validation rules |