envsync

Keep your .env.example in sync with your .env and catch common mistakes. Zero network, zero runtime dependencies.

The pain: you add a variable to .env, forget to add it to .env.example, and a teammate's app breaks on the next clone. envsync catches this drift in one command — ideal as a pre-commit hook or in CI.

Install & usage

Run it directly with npx (no install):

npx @tomi_tom/envsync            # check .env ⇄ .env.example in the current folder

Or install it globally to get the envsync command:

npm install -g @tomi_tom/envsync

envsync                      # = envsync check (compare .env ⇄ .env.example, lint, report)
envsync update               # (re)generate .env.example from .env, values blanked
envsync check --ci           # also fail on warnings (exit ≠ 0)
envsync check --json         # machine-readable JSON report (for CI / tooling)
envsync --env .env.local --example .env.example

Exit code 0 if everything is in order, 1 on drift/errors → pluggable into CI / git hooks.

With --json, the report is emitted as structured JSON (ok, diff, lint, secrets, summary) instead of the coloured text, so CI steps and custom reporters can parse results without scraping the human output.

What it detects

• Drift: keys present in .env but absent from .env.example (and vice versa)
• Duplicate keys (the "last wins" footgun)
• Spaces around =, keys not in UPPER_SNAKE_CASE, unquoted spaced values
• Sensitive keys (*_SECRET, *_TOKEN, API_KEY…) with a real value → reminder before commit

Stack & dev

Node + TypeScript, no runtime dependencies (homemade ANSI colors, node:util.parseArgs, node:fs). Tests: Vitest.

pnpm install
pnpm test         # 16 tests
pnpm build        # tsc → dist/
node dist/cli.js check --env fixtures/.env --example fixtures/.env.example

Architecture

src/
  parser.ts     # parse .env (tolerant, never throws) — pure logic, tested
  diff.ts       # drift .env ⇄ .env.example
  lint.ts       # common mistakes + secret detection
  generate.ts   # .env.example from .env (values blanked, deduplicated)
  format.ts     # colored terminal output (off when piped / NO_COLOR)
  cli.ts        # arg parsing + check/update commands

Differentiation

Existing .env linters (dotenv-linter…) target style/duplicates. envsync focuses on the .env ↔ .env.example synchronization workflow (the real team pain) plus an update mode that regenerates the example without leaking values. Free, local, dependency-free.