vercel: env pull merge mode (don't override unrelated .env keys)

[exisz]

Source: vercel/vercel#13365 (1 reaction, open since 2025-05)
Pain
vercel env pull overwrites the entire .env.local file. Users who keep local-only secrets (DB URLs to localhost, dev API keys not in Vercel) get them wiped on every pull. Comment thread shows users want merge behavior — replace only Vercel-sourced keys, preserve everything else.
Our solution
avercel env pull --merge (or set as default via avercel.yaml: env.pull.mode: merge):
Read existing target file into key-value map

Run vercel env pull to a tempfile

Read tempfile into Vercel-sourced map

Merge: existing.update(vercel) — Vercel keys overwrite, but local-only keys survive

Preserve comments and ordering when possible (use a proper dotenv parser that retains AST)

Print summary: avercel: merged N Vercel vars, preserved M local vars

Bonus: avercel env pull --diff — show what would change without writing.
DoD
[ ] --merge flag implemented

[ ] Comments preserved

[ ] Local-only keys preserved

[ ] --diff mode (no write, prints unified diff)

[ ] Config option env.pull.mode (overwrite|merge)

[ ] Tests with mixed local/remote .env files

---

Migrated from NEBULA-95 | Parent: NEBULA-18 | Original status: To Do