EnvSync
Install

🧩 EnvSync — Keep your .env aligned across the team

EnvSync is an open‑source CLI that keeps every teammate's .env aligned. It syncs keys between local env files and their tracked .env.example counterparts, updating only the variable names (never the values). Perfect for shipping config updates without leaks and making sure nobody pulls missing variables again.

EnvSync - Keep your .env files aligned across the team | Product Hunt

🚀 Why EnvSync exists

“Hey, can you send me the latest .env file?” 😅

EnvSync keeps every .env in lockstep with a single command.

✨ What it does

⚙️ Prerequisites

🧰 Installation

Via npm (global) - Consigliato
npm install -g @passasooz/envsync

Dopo l'installazione globale, usa semplicemente envsync in qualsiasi directory.

Via npm (locale in un progetto)
npm install @passasooz/envsync

Dopo l'installazione locale, usa npx envsync nel tuo progetto.

From source (local)
git clone https://github.com/passasooz/envsync.git
cd envsync
npm install
npm install --global .

Pro tip: you can also run the CLI directly from the repo with npx envsync (after npm install) or npm run envsync -- --help.

🕹️ Quick usage

Auto‑align missing keys in .env.example from .env 
envsync

By default, the CLI scans all files starting with .env in the current directory (e.g., .env, .env.local, .env.production, …). For each one, it creates/updates the related .example (e.g., .env.local.example, .env.production.example, …) keeping variables separated.

Run a check without modifying files (great for CI/CD)
envsync --check
Specify custom paths
envsync --env .env --env .env.production
# or
envsync --env config/.env.local --env config/.env.production
# single file with custom example
envsync --env config/.env --example config/.env.sample
Align local .env files with examples (without losing existing values)
envsync --from-example

In --check mode, the CLI exits with code 1 when it finds differences between files.

🛠️ How it works

  1. For each .env* file, it auto‑finds (or generates) the related .env*.example.
  2. In default mode, it copies all missing keys from env to example, preserving comments, order, and actual values.
  3. With --from-example, it does the reverse: adds new keys to local env files and removes obsolete ones, never touching existing values.
  4. In both cases, it reports (or removes) keys left behind.

The result? Every teammate keeps an up‑to‑date .env automatically, while committed examples stay ready to version.

🧪 Testing

npm test

Run the internal test suite after cloning the repo.

🔐 Git hooks (pre‑commit & post‑merge)

Pre‑commit

  1. Run npm install once (will auto‑activate Husky thanks to the prepare script).
  2. During commit, if any .env*.example isn't up‑to‑date, the commit gets blocked and you see the list of keys to fix.
  3. Fix it with npx envsync (or node bin/envsync.js) and retry the commit.

Post‑merge

Right after you complete a git pull or merge, envsync --from-example runs to auto‑update your local .env files (adds new empty keys and removes obsolete ones, leaving values intact).

Use pull with merge (Git's default behavior). In case of git pull --rebase, manually run npx envsync --from-example.

Both hooks run only locally and don't affect CI, which can still use envsync --check as an additional step.

🤝 Contributing

Bug fixes, ideas, and improvements are welcome! Open an issue or send a pull request — just make sure the tests (npm test) pass before shipping it.

🍺 Buy me a beer

If EnvSync has made your life easier, you can support development by buying me a beer 🍺.