Configuration File
dotenv-diff supports a configuration file named dotenv-diff.config.json that allows you to persist your preferred flags. This makes it easier to share consistent settings between local development, teams, and CI/CD environments.
File Location
By default, dotenv-diff automatically looks for a dotenv-diff.config.json file in your project root (same folder as package.json).
You can quickly create one with the --init flag:
⚙️ Example Configuration
This configuration defines default behavior across comparisons, scanning, and output. Every field corresponds to an equivalent CLI flag — meaning you can use dotenv-diff entirely from configuration without passing command line options.
Supported Options
| Option | Type | Description | Equivalent CLI Flag |
|---|---|---|---|
checkValues | boolean | Compare actual values if example has values. | --check-values |
ci | boolean | Run non-interactively and never create files. | --ci |
yes | boolean | Automatically answer “Yes” to prompts. | --yes |
env | string | Path to a specific .env file. | --env <file> |
example | string | Path to your .env.example file. | --example <file> |
allowDuplicates | boolean | Do not warn about duplicate keys in .env files. | --allow-duplicates |
ignore | string[] | List of keys to ignore during comparison or scanning. | --ignore |
ignoreRegex | string[] | Regex patterns to skip matching keys. | --ignore-regex |
fix | boolean | Automatically fix issues (add missing keys, remove duplicates). | --fix |
json | boolean | Output results in JSON format. | --json |
noColor | boolean | Disable colored terminal output. | --no-color |
only | string[] | Only run specific categories: missing, extra, empty, mismatch, duplicate, gitignore. | --only |
scanUsage | boolean | Scan codebase for environment variable usage. | --scan-usage |
compare | boolean | Compare .env and .env.example files. | --compare |
includeFiles | string[] | Additional file patterns to include in scan. | --include-files |
files | string[] | Override default file patterns (replaces built-in ones). | --files |
excludeFiles | string[] | File patterns to exclude from scanning. | --exclude-files |
showUnused | boolean | Show variables defined in .env but unused in code. | --no-show-unused |
showStats | boolean | Display statistics summary at the end of scan. | --no-show-stats |
strict | boolean | Enable fail-on-warning behavior. | --strict |
secrets | boolean | Enable or disable secret detection. | --no-secrets |
ignoreUrls | string[] | URLs to skip in secret detection. | --ignore-urls |
noCompare | boolean | Run scan without comparing against any .env files. | --no-compare |
Behavior Notes
- All options are optional; dotenv-diff uses sensible defaults when omitted.
- CLI flags always take precedence over configuration values.
- 🧩 Loaded dotenv-diff.config.json when a config file is detected.
- The file must be valid JSON