vercel-cli

# vercel-cli — official Vercel CLI wrap The `vercel` binary (Vercel CLI 50.x, installed via mise as part of Node) is the canonical deployment tool. This skill wraps the same surface the claude.ai Vercel MCP exposed but with no boot-time token cost — `vercel` is lazy, only invoked when the skill triggers. ## When to use this skill Any time the user references Vercel work — deploys, projects, deployments, env vars, domains, logs, teams. **Never** use the `mcp__claude_ai_Vercel__*` tools when this skill is loaded. If the user explicitly asks for an MCP tool by name, fall back to the MCP. Otherwise default to `vercel`. ## Auth `vercel` reads its token from `~/.local/share/com.vercel.cli/auth.json` (set up via `vercel login` once). If `vercel whoami` fails, the user needs to re-authenticate: ```sh vercel login ``` For a CI-style or token override, use `vercel --token <TOKEN>` or set `VERCEL_TOKEN` in env. ## Commands (the daily-use 80%) ```bash # Identity / status vercel whoami # current user / team vercel teams ls # list accessible teams vercel switch <team-slug> # switch active team scope # Projects vercel projects ls # list projects in current scope vercel projects inspect <project> # project details + linked git vercel link # link cwd to a Vercel project vercel pull # pull project env to .vercel/.env.* # Deployments vercel ls [project] # list deployments (most recent first) vercel inspect <deployment-url-or-id> # deployment details vercel logs <deployment-url-or-id> # runtime logs vercel logs <url> --next 100 # build logs # Deploy vercel # deploy cwd as preview vercel --prod # deploy to production vercel deploy --prebuilt # deploy a pre-built output # Promotion vercel promote <deployment> # promote a preview to production vercel rollback <deployment> # rollback prod to a prior deployment # Env vars vercel env ls # list env vars (per-environment) vercel env add <KEY> <env> # add env var (production|preview|development) vercel env rm <KEY> <env> # remove vercel env pull .env.local # pull dev env to a file # Domains vercel domains ls # list domains in current scope vercel domains add <domain> # attach a domain to a project vercel domains rm <domain> # detach vercel certs ls # SSL cert status # Aliases vercel alias ls vercel alias set <deployment> <alias> # Misc vercel --help # full reference vercel <subcommand> --help # per-command help ``` Add `--scope <team>` to any command to operate against a specific team. Add `--cwd <dir>` to run from a different project root. ## Validation playbook 1. `vercel whoami` — confirms auth, shows current user/team 2. `vercel projects ls` — confirms read path against the active scope 3. `vercel ls` (in a project dir) — confirms deployment listing If `whoami` returns `Not authenticated`, run `vercel login` and retry. ## ⚠️ Post-merge deploy guardrail (read before any `vercel --prod` from a working tree) **`gh pr merge` does NOT update local `main`.** It advances `origin/main` on GitHub but leaves your local branch at the pre-merge SHA. If you then `git checkout main && vercel --prod`, Vercel deploys the stale code and ships a broken artifact missing whatever was just merged. **Always do this before any local `vercel --prod`:** ```bash git fetch origin main git checkout main git merge --ff-only origin/main # fails loud if local main has diverged # now safe to deploy ``` **Or skip the local deploy entirely.** Vercel's GitHub integration auto-deploys `main` on every merge. If you need to redeploy with new env vars, use: ```bash vercel redeploy <prior-prod-deployment-url> --target=production ``` This rebuilds from the SHA Vercel has on file (always equals `origin/main` HEAD via the git integration) with fresh env. Same artifact, fresh env, zero dependency on local working tree state. **A safer wrapper is installed at `~/.local/bin/vercel-safe-prod`** — it does the `git fetch + ff-only` check before invoking `vercel --prod` and refuses to proceed if local main is stale. Use it instead of raw `vercel --prod` from a working tree. See: [[reference_vercel_post_merge_deploy_gotcha]] for the 2026-05-25 incident this guardrail prevents. ## Cost & migration context | Path | Context cost at boot | Cost per call | |---|---|---| | `mcp__claude_ai_Vercel__*` (~16 tools) | ~5-7k tokens estimated | full schema + JSON response | | `vercel` CLI via this skill | 0 (lazy) | ~200 tokens (CLI's own concise output) | Strategic context: `~/claude/claudeopedia/entities/decisions/MCP to CLI Migration.md`. After the user disconnects `claude.ai Vercel` from https://claude.ai/settings/connectors, the next session's `/context` should show the Vercel MCP tokens drop to zero. Until that disconnect lands, both paths coexist — prefer `vercel`. ## Implementation notes - No new binary needed — this is a skill-only wrap of the official `vercel` CLI installed via mise. - The CLI's own output is already agent-friendly (terse, structured); no further summarization needed. - For programmatic JSON output, append `--scope` and parse stdout — the CLI emits clean JSON for `inspect` and `ls` with appropriate flags. - Deeper Vercel work (Workflow, AI Gateway, Marketplace) has its own dedicated `vercel:*` skills already loaded; defer to those for specialized tasks. ## Source - Binary: `vercel` (installed via mise; bundled with Node) - Vercel docs: `https://vercel.com/docs/cli` - Claude.ai connector to disconnect: https://claude.ai/settings/connectors → Vercel