vercel-env-sync
Reconcile Vercel project environment variables against the local `.env.local` and your app's env schema. Use when the user wants to verify, diff, add, or remove env vars on Vercel so a deploy will boot — or when diagnosing 401 / `[DISPATCH_FAILED]` symptoms that smell like missing secrets. Read-only by default; mutations require explicit user sign-off.
- License 许可
- MIT
- 所属仓库
- dotlas/skills
- 最近更新
- 2026-10-27
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- vercel-env-sync
- description
- Reconcile Vercel project environment variables against the local `.env.local` and your app's env schema. Use when the user wants to verify, diff, add, or remove env vars on Vercel so a deploy will boot — or when diagnosing 401 / `[DISPATCH_FAILED]` symptoms that smell like missing secrets. Read-only by default; mutations require explicit user sign-off.
03 SKILL.md 正文
Vercel Env Sync
Safety
Non-negotiable:
- 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 onmain. If the user asks for a deploy, refuse and redirect togit push. - NEVER run
vercel linkorvercel env pullwithout first checkinggit 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 rmwithout 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.localas 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 whoamifails, 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,developmentper 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.
04 同仓库更多 Skills
where-were-we
Provide the user with a refresher of existing chat turns. Useful when the user wants to understand where we stand in the conversation.
update-global-dotlas-skills
Sync the globally-installed dotlas/skills catalog and prune stale remnants. Runs the documented global install command, then detects skills that were installed from dotlas/skills but no longer exist in the catalog and removes them (with confirmation). Use when the user wants to update, refresh, or clean up their global Dotlas skills, or invokes /update-global-dotlas-skills.
unpack
Explain an unfamiliar thing plainly and from first principles, structured so the reader sees why it is true. Use when someone is trying to understand something — a dense or jargon-heavy passage, a baffling error, an unfamiliar mechanism, a codebase, or a document — asks to break something down ("walk me through this", "what does this actually mean"), or wants their intent turned into a precise instruction for another agent. Trigger on confusion or a request to understand, not on difficulty alone; technical or long content is not itself a signal.
sum
Use when the previous response is too technical, complex, or jargon-heavy and needs a clear, plain-language explanation
slack
Compose a Slack message, or digest a Slack thread into compact context. Use when the user asks to reply to a person or channel, write a Slack post, or catch up on a thread without reading the whole transcript. This skill covers how to write well for Slack — both jobs share the same standard.
plan-with-me
Collaborative, human-in-the-loop planning for something new that spans several parts and needs human judgement at each fork. A brainstorming partner that funnels — each fork opens up the real options, then narrows to a decision, surfacing caveats and breaking points, and co-authoring the plan instead of guessing alone. Fits any domain where you plan something new against existing context. Resolves one decision at a time, each with a recommendation, then emits a lightweight plan to hand off for implementation. Use when planning alone would make wrong assumptions, or the user wants to shape something new together.