vercel-env-sync

Vercel Env Sync

Safety

Non-negotiable:

1. NEVER run vercel deploy, vercel rollback, vercel alias, vercel domains <mut>, vercel project rm, or any deploy / domain / project mutation. Production deploys belong to the GitHub integration on main. If the user asks for a deploy, refuse and redirect to git push.
2. NEVER run vercel link or vercel env pull without first checking git diff .env.local. Both commands overwrite that file. If it’s dirty, back it up (cp .env.local .env.local.bak) and tell the user before proceeding.
3. NEVER run vercel env rm without explicit per-variable, per-environment user sign-off. Removal is destructive (no undo, no version history). Present the list, wait for the user to name each var in their approval, then execute one at a time.
4. NEVER print secret values to the transcript. Echo ${#VAR} (length) or first/last 4 chars only. Treat anything in .env.local as production-grade credentials.
5. NEVER set Vercel-injected vars (VERCEL_URL, VERCEL_PROJECT_PRODUCTION_URL, VERCEL_ENV, VERCEL_GIT_COMMIT_SHA, VERCEL_REGION, …). If you find one set as a project env var, flag it — the dashboard value overrides Vercel’s runtime injection and will silently break URL resolution.
6. NEVER add a NEXT_PUBLIC_* mirror of a server-only secret (CRON_SECRET, VERCEL_AUTOMATION_BYPASS_SECRET, database URLs, API keys). These leak to the browser bundle.
7. Vercel CLI is not signed-in by default in CI. If vercel whoami fails, stop and tell the user — do not try to log in non-interactively.

Discovery

Replace <your-scope> and <your-vercel-project> with the values in <app>/.vercel/project.json. If your project keeps a Vercel conventions doc, read it before doing anything non-trivial. All vercel commands must be detached from stdin (< /dev/null) or they hang in agent shells.

# Auth + scope
pnpm exec vercel whoami < /dev/null
pnpm exec vercel teams ls < /dev/null 2>&1 | cat

# Confirm the link is correct
cat <app>/.vercel/project.json 2>/dev/null \
  || echo "NOT LINKED — run: cd <app> && pnpm exec vercel link --yes --scope <your-scope> --project <your-vercel-project>"

# Project facts
cd <app> && pnpm exec vercel project inspect <your-vercel-project> --scope <your-scope> < /dev/null 2>&1 | cat