envdiff

Solve "works on my machine" in 30 seconds.

You know the drill: the code runs fine on your machine, your teammate pulls it — and it breaks. Same code, different computers. envdiff takes a snapshot of both environments, diffs them, and tells you the most likely culprit first: a missing tool, a different Node version, one env var. No more "what version do you have?" ping-pong.

Secrets are masked before anything touches disk, so snapshots are safe to send to a teammate.

Why

"Works on my machine" is never magic. It's a different Node version, a missing tool on PATH, or one env var. Finding which one by hand takes an hour of back-and-forth. envdiff finds it in seconds — and ranks the differences so the real suspect is at the top, not buried under noise.

Install

npx envdiffer snapshot -o mine.json

No install needed. (Or npm i -g envdiffer.)

Usage

# On your machine (where it works)
envdiff snapshot -o mine.json

# On the machine where it breaks (send them the one-liner)
npx envdiffer snapshot -o theirs.json

# Anywhere — compare
envdiff compare mine.json theirs.json

Output:

7 difference(s) — most suspicious first
left = merts-laptop, right = ci-runner

[tools]
  ~ node: v24.18.0 → v18.19.0
  - docker (only left)
[system]
  ~ platform: win32 → linux
[env]
  ~ NODE_ENV: development → production
...

Exit code is 1 when differences exist (diff convention), so it drops into scripts and CI.

"Why does it only break in CI?"

envdiff init-ci

Writes .github/workflows/envdiff.yml — every CI run uploads a snapshot of the runner's environment as an artifact. Download it and diff against your machine:

gh run download -n envdiff-snapshot
envdiff compare mine.json ci-snapshot.json

What gets captured

| Section | Contents | |---|---| | system | OS, arch, CPU count, RAM, shell, locale, timezone | | tools | Versions of 24 common dev tools (node, python, go, docker, git, ...) | | env | Environment variables — values matching secret patterns are masked | | path | Deduplicated PATH entries |

Security

Env values are masked by name pattern (*KEY*, *TOKEN*, *SECRET*, ...) and by value shape (long high-entropy strings), before the snapshot is written. Review the JSON before sharing anyway — it's your environment.

Roadmap

• [x] init-ci: snapshot your CI runner via GitHub Actions artifact
• [ ] Custom tool probes via .envdiffrc
• [x] envdiff compare --json machine-readable output

License

MIT