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.
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.
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.
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.
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.
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.
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

Expected: scope <your-scope>, project <your-vercel-project>, root directory <app>. If anything else, stop — you are pointed at the wrong project and any mutation will hit production for a different app.

Diff

This is the default mode. Produce a three-way diff of:

Local — names declared in repo-root .env.local.
Schema — names declared in <app>/env.ts (server + client) and any <packages>/*/keys.ts.
Vercel — names present in production, preview, development per the CLI.

Pull the three lists

# Local names
grep -E '^[A-Z_][A-Z0-9_]*=' <repo-root>/.env.local \
  | sed 's/=.*//' | sort -u > /tmp/local-keys.txt

# Vercel names per environment
cd <app>
for ENV in production preview development; do
  pnpm exec vercel env ls "$ENV" < /dev/null 2>&1 \
    | awk 'NR>3 && $1 ~ /^[A-Z_][A-Z0-9_]*$/ {print $1}' | sort -u > "/tmp/vercel-$ENV-keys.txt"
done

# Schema names
{
  grep -oE '^\s*[A-Z_][A-Z0-9_]*:' <app>/env.ts | sed 's/[: ]//g'
  find <packages> -name keys.ts -exec grep -hoE '^\s*[A-Z_][A-Z0-9_]*:' {} \; | sed 's/[: ]//g'
} | sort -u > /tmp/schema-keys.txt

Compute the delta sets

# (A) In local but missing on Vercel production — likely deploy-breakers
comm -23 /tmp/local-keys.txt /tmp/vercel-production-keys.txt

# (B) On Vercel but not in local — possibly orphaned, or production-only secrets
comm -13 /tmp/local-keys.txt /tmp/vercel-production-keys.txt

# (C) In schema but missing on Vercel production — runtime will throw on boot
comm -23 /tmp/schema-keys.txt /tmp/vercel-production-keys.txt

# (D) On Vercel production but not in schema — dead weight or undeclared
comm -13 /tmp/schema-keys.txt /tmp/vercel-production-keys.txt

Repeat (A)/(C) against preview and development separately — the three environments diverge intentionally.

Classify each delta

For every name in the diff:

Question	Where to look	Implication
Declared in `<app>/env.ts`?	grep `env.ts` for the name	Required-everywhere if no `.optional()`; build fails without it
Declared in any `<packages>/*/keys.ts`?	grep `<packages>/*/keys.ts`	Required for the package consumer
Mentioned in latest changeset?	`ls -lt .changeset/*.md \| head -5` then grep	Authoritative environment targeting (prod-only vs all envs)
Vercel-injected?	Match against `VERCEL_*` in Safety rule 5	DO NOT set; flag as foot-gun
`NEXT_PUBLIC_*`?	Prefix check	Safe to expose; inlined into client bundle at build time
Sensitive?	`vercel env ls` “Type” column	`pull` returns empty string; can only re-add to edit

A var in .env.local but not declared anywhere in the repo is dead weight — recommend removing from .env.local, not adding to Vercel.

Plan

Output as a table grouped by action. Add operations for vars declared in schema with values sourced from .env.local can proceed after overall plan approval; rm always requires per-variable sign-off.

ADD to production:
  CRON_SECRET            (declared: env.ts server, sensitive: yes, source: .env.local len=64)

ADD to preview:
  CRON_SECRET            (same value as prod)

REMOVE from production (DESTRUCTIVE — needs sign-off):
  OLD_FEATURE_FLAG       (not declared in schema, last referenced in commit abc1234)

FLAG (do not change without discussion):
  VERCEL_PROJECT_PRODUCTION_URL = http://localhost:3000   ← overrides Vercel injection; almost certainly wrong

Wait for the user to approve the plan before running any add, and per-variable before any rm.

Execute

cd <repo-root> && \
set -a && source .env.local && set +a && \
cd <app> && \
add() {
  local name="$1" envname="$2" val="$3"
  echo "→ $name [$envname] (len=${#val})"   # length only — never the value
  if [[ "$envname" == "preview" ]]; then
    # preview always prompts for git branch — pass "" to mean "all preview branches"
    pnpm exec vercel env add "$name" preview "" --value "$val" --yes < /dev/null 2>&1 | tail -2
  else
    # use --value to avoid stdin consumption conflicts with the branch prompt
    pnpm exec vercel env add "$name" "$envname" --value "$val" --yes < /dev/null 2>&1 | tail -2
  fi
} && \
add CRON_SECRET production "$CRON_SECRET" && \
add CRON_SECRET preview    "$CRON_SECRET" && \
echo DONE

tail -2 keeps each add’s output to Saving + the success line.

Editing an existing var

There is no in-place edit. Sequence:

pnpm exec vercel env rm NAME production --yes < /dev/null   # DESTRUCTIVE — needs sign-off
pnpm exec vercel env add NAME production --value "$VAL" --yes < /dev/null

If the var was sensitive, you cannot pull the old value first — confirm the new value before removing.

Sensitive-flag note

The CLI defaults to Plain. To mark a value sensitive (encrypted at rest, unreadable via pull), set it in the dashboard — this skill does not cover the sensitive flag because the CLI doesn’t expose it cleanly. Note which vars should be sensitive (*_SECRET, *_KEY, *_TOKEN, database URLs, API keys) and ask the user to flip them in the dashboard.

Verify

cd <app>
for ENV in production preview development; do
  echo "=== $ENV ==="
  pnpm exec vercel env ls "$ENV" < /dev/null 2>&1 | grep -E "<added-var-names>"
done

Then tell the user: “Env-var changes only take effect on the next deploy. Trigger a redeploy by pushing a commit to main (production) or your PR branch (preview).”

Diagnostic shortcuts

Symptom	First env-var to check
`[DISPATCH_FAILED] HTTP 401 — <!doctype html>...` (HTML, not JSON)	`VERCEL_AUTOMATION_BYPASS_SECRET` missing on production
`[DISPATCH_FAILED] HTTP 401 — {"error":"Unauthorized"}` (JSON)	`CRON_SECRET` missing or mismatched
`[DISPATCH_FAILED] fetch failed [ECONNREFUSED] ... 127.0.0.1:3000`	`NEXT_PUBLIC_APP_URL` missing AND `VERCEL_PROJECT_PRODUCTION_URL` overridden to localhost
`[DISPATCH_FAILED] fetch failed [ENOTFOUND]`	`NEXT_PUBLIC_APP_URL` points at a dead domain or wrong subdomain
Cron route returns 401 HTML	Same as row 1 — Deployment Protection without bypass secret
Cron route returns 404 + `x-middleware-rewrite` header	Not an env issue — route prefix missing from the public-route allowlist in your auth middleware
App boots then crashes on first request with Zod validation error	Var declared required (no `.optional()`) in `env.ts` is missing from production

For each, rule out non-env causes before recommending a fix — several of these symptoms have non-env causes that look identical.

vercel-env-sync

Vercel Env Sync

Safety