envdiff

Catch config drift in CI — fail a deploy before it ships with a missing or wrong environment variable, instead of finding out from a crash report.

Free to compare two local files, or read a docker-compose.yml service's vars. Connecting to a live provider account (Vercel, Netlify, Heroku, or DigitalOcean, with more on the way) needs a one-time EnvDiff license — the same one that unlocks the web app.

Install

npm install -g @envdiff/cli

Or skip the install and use npx @envdiff/cli directly in a pipeline.

Quick start

Compare two local files — free, no license, no network call beyond reading the files:

envdiff check --local .env --against .env.production

Pull straight from Vercel instead:

envdiff license set ENVDIFF-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX   # once, saves it to ~/.envdiff/config.json
envdiff check --local .env --vercel-project my-app --vercel-token $VERCEL_TOKEN

Or from Netlify:

envdiff check --local .env --netlify-site my-app --netlify-token $NETLIFY_TOKEN

Or from Heroku:

envdiff check --local .env --heroku-app my-app --heroku-token $HEROKU_TOKEN

Or from a DigitalOcean App Platform app (optionally merging in one component's own vars over the app-level ones):

envdiff check --local .env --do-app my-app --do-component web --do-token $DIGITALOCEAN_TOKEN

Or read a service's vars straight out of a docker-compose.yml — free, no license, no account, and it resolves any env_file: the service references relative to the compose file's own directory:

envdiff check --local .env --compose-file docker-compose.yml --compose-service web

Or check that a fixed list of keys exists, with nothing to compare against:

envdiff check --local .env --required DATABASE_URL,STRIPE_KEY,JWT_SECRET

In CI (GitHub Actions example)

- name: Check env vars before deploy
  run: npx @envdiff/cli check --local .env.example --vercel-project my-app
  env:
    VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
    ENVDIFF_LICENSE: ${{ secrets.ENVDIFF_LICENSE }}

envdiff check exits 1 when drift is found (per --fail-on) and 0 when it's clean — that's what fails the pipeline step. It exits 2 for a setup problem (bad license, unreachable provider, missing file), so you can tell "your config is broken" apart from "the check itself couldn't run."

envdiff check

| Flag | Default | What it does | |---|---|---| | --local <path> | .env | The file to check | | --against <path> | — | Compare against another local file. Free, no license. | | --vercel-project <idOrName> | — | Pull the comparison side from a Vercel project. Requires a license. | | --vercel-env <target> | production | production, preview, or development | | --vercel-token <token> | $VERCEL_TOKEN | Vercel access token | | --netlify-site <idOrName> | — | Pull the comparison side from a Netlify site. Requires a license. | | --netlify-context <context> | production | production, deploy-preview, or dev | | --netlify-token <token> | $NETLIFY_TOKEN | Netlify personal access token | | --heroku-app <idOrName> | — | Pull the comparison side from a Heroku app's config vars. Requires a license. | | --heroku-token <token> | $HEROKU_TOKEN | Heroku API key | | --do-app <idOrName> | — | Pull the comparison side from a DigitalOcean App Platform app. Requires a license. | | --do-component <name> | — | Merge in one component's own vars over the app-level ones. Omit to use app-level vars only. | | --do-token <token> | $DIGITALOCEAN_TOKEN | DigitalOcean access token | | --compose-file <path> | — | Read the comparison side from a docker-compose.yml service. Free, no license. | | --compose-service <name> | — | Which service in --compose-file to read. Required alongside it. | | --license <key> | $ENVDIFF_LICENSE or the saved one | Required only when using --vercel-project, --netlify-site, --heroku-app, or --do-app | | --required <keys> | — | Comma-separated keys that must exist in --local. No second source needed. | | --fail-on <mode> | missing | missing, different, any, or none (report only, never fail) | | --api <url> | https://envdiff.dev | Override the API base — useful against a local dev Worker | | --json | — | Machine-readable output instead of a table |

envdiff license

envdiff license set <key>     # validate and save a license locally
envdiff license show          # print the saved key, masked
envdiff license remove        # clear it

The license is stored in ~/.envdiff/config.json (mode 0600). In CI, skip this and pass --license/ENVDIFF_LICENSE per-run instead — most CI runners are ephemeral, so there's nothing to persist between builds anyway.

Privacy

Only key names and statuses (match / different / missing) are ever printed or exported. Provider tokens go straight from your machine to the provider's own API — never through EnvDiff's servers. See envdiff.dev for the full privacy write-up.