envsync

Keep .env and .env.example files in sync.

Problem statement

Environment files drift easily: a new required variable gets added to .env, but its placeholder never makes it into .env.example. That leaves teammates, deploys, and fresh checkouts guessing which configuration they need. envsync finds those mismatches and can regenerate a safe example file without copying secrets.

Demo

The recording is reproducible from demo/envsync-demo.tape: run npm run build, then vhs demo/envsync-demo.tape. The tape writes assets/envsync-demo.gif.

Install

npm install -g envsync

Usage

Check for drift

$ envsync check

📁 .
Missing in .env.example:
  - API_KEY

Use --ci to return exit code 1 when mismatches are found, --json for machine-readable output, --quiet to hide successful checks, and --verbose to list matching keys.

$ envsync check --json
[
  {
    "dir": ".",
    "result": {
      "missingInExample": ["API_KEY"],
      "missingInEnv": [],
      "emptyValues": []
    }
  }
]

Generate an example file

sync creates a new example file from .env, retaining comments and keys while blanking every value.

$ envsync sync --yes
Preview of new .env.example:

PORT=
API_KEY=

✓ .env.example updated

Omit --yes to preview the change and confirm before overwriting the example file.

Configure a different example filename

Create .envsyncrc.json in the directory where you run the command:

{
  "exampleFileName": ".env.template",
  "ignore": ["LOCAL_ONLY_KEY"]
}

Development

npm install
npm test

Why I built this

I built envsync because configuration drift is a tiny, recurring source of friction that a focused command-line tool can remove before it reaches a teammate or deployment.

License

MIT