Baseline Workflow

The --baseline flag helps you adopt dotenv-diff in projects that already contain known warnings. It records the current warning state into a baseline file, so future runs can focus on newly introduced issues.

What --baseline Does

CLI
dotenv-diff --baseline

When you run this, dotenv-diff will:

  • scan your codebase as normal
  • collect the warnings from the current scan result
  • write a dotenv-diff.baseline.json file in the working directory
  • exit cleanly with exit code 0 after writing the file

On later runs without --baseline, dotenv-diff automatically loads this file and suppresses matching warnings.

Baseline File Location

The baseline file is written in your current working directory as dotenv-diff.baseline.json. In monorepos, this means each app or package can keep its own baseline by running dotenv-diff from that folder.

Supported Warning Categories

Baseline suppression supports the same categories produced by scan usage checks, including:

  • missing variables
  • unused variables
  • duplicate keys in .env and .env.example
  • framework warnings
  • uppercase key warnings
  • inconsistent naming warnings
  • expiration warnings
  • secret findings, stored as fingerprints
  • .env.example secret warnings
  • logged variable usages (console.log of env variables)

JSON Mode

You can combine baseline with JSON output.

CLI
dotenv-diff --baseline --json

Success output includes file and warningsStored. If writing fails, the process exits with exit code 1.

Recommended Workflow

  • Create a baseline once for the current state.
  • Commit dotenv-diff.baseline.json.
  • Run dotenv-diff normally in local development and CI.
  • Fix issues incrementally and remove stale baseline entries over time.
  • Recreate the baseline only when you intentionally accept a new known warning set.

Best Practices

  • Review baseline changes in pull requests like any other code change.
  • Keep the baseline file small by removing entries after fixes.
  • Prefer fixing warnings over growing the baseline indefinitely.
  • Avoid regenerating the baseline automatically in CI — treat it as a reviewed artifact.
← Monorepos Next →