Vercel CLI

Safety-first wrapper for the Vercel CLI (vercel, alias vc). Every command is classified by risk tier before execution — full project control, with anything irreversible gated behind explicit confirmation.

When to Use

• Deploy projects (preview/production), build locally, or run vercel dev
• Manage env vars, secrets, and pull project settings (env, pull)
• Manage domains, DNS records, certificates, and aliases
• Manage projects, teams/scopes, and Git connections
• Inspect deployments, read logs, roll back, promote, or redeploy
• Configure firewall, routes, redirects, cache, flags, rolling releases
• Make authenticated vercel api calls or manage blob storage & integrations

Prerequisites

1. Install: npm i -g vercel (or pnpm/yarn). Native binary (experimental): pnpm i -g @vercel/vc-native -f
2. Auth: vercel login — or for CI/CD set VERCEL_TOKEN (preferred over the --token flag, which leaks into process lists). Tokens: https://vercel.com/account/tokens
3. Verify: vercel --version and vercel whoami
4. Link: vercel link in the project dir (creates .vercel/)
5. Scope: confirm the active team with vercel teams ls; switch with vercel switch

Safety Model

Tier	Action Required	Examples
Safe	Execute immediately	vercel ls, inspect, env ls, whoami
Write	Inform user, then execute	deploy (preview), env add, alias set, dns add, staged routes/firewall rules edits
Destructive	AskUserQuestion BEFORE executing	deploy --prod, remove, rollback, promote, env rm, alias rm, domains rm, certs rm, cache purge, firewall publish
Forbidden	Multi-step typed confirmation, NEVER auto-confirm	project rm, domains buy/transfer-in, buy, cache dangerously-delete, firewall system-mitigations pause, git disconnect, bulk destructive loops

Full classification + confirmation templates: references/safety-rules.md.

Decision Flow

Command received
  → Classify risk tier (see Safety Model + references/commands.md)
  → Safe?        Execute immediately
  → Write?       State what will happen → execute
  → Destructive? AskUserQuestion with options → wait → execute or cancel
  → Forbidden?   Warn → typed confirmation → final confirm → execute or cancel
On failure → Self-Healing (fetch the command's doc URI)

Forbidden Commands (never auto-confirm)

These need typed multi-step confirmation — keep them visible. The full Destructive list and per-command tiers live in references/safety-rules.md and references/commands.md.

Command	Why
vercel project rm	Deletes project AND all its deployments — permanent
vercel domains buy / domains transfer-in / buy	Spends money
vercel domains move	Transfers domain to another scope
vercel cache dangerously-delete	Hard-deletes cached data
vercel firewall system-mitigations pause	Removes DDoS protection; you owe fees for abusive traffic
vercel git disconnect	Breaks auto-deploy on push
vercel logout	Destroys the local session
Bulk destructive loops	Multiplies blast radius

AskUserQuestion Integration

For Destructive ops, present tailored options with a "Cancel". Examples:

Q: "Roll back production for <project>?"
  - "Roll back to previous" — vercel rollback
  - "Roll back to specific deployment" — vercel rollback <id>
  - "Cancel"

Q: "Remove env var <NAME> from <environment>?"
  - "Remove it" — vercel env rm <NAME> <env>
  - "Cancel"

For Forbidden ops, follow the triple-confirmation protocol in references/safety-rules.md.

Production Deploy Protocol

--prod, promote, rollback, and *-release/publish change live traffic. Before running:

1. Confirm linked project & active scope (vercel project inspect, vercel teams ls)
2. Confirm git state (right branch/commit)
3. AskUserQuestion to confirm production intent (template in safety-rules.md)
4. After deploy, verify with vercel inspect <url> and vercel logs <url>

Self-Healing

The CLI changes often (subcommands get renamed). On any error or unexpected behavior: read the error → vercel help <command> → if still unclear, WebFetch https://vercel.com/docs/cli/<command> → adjust → re-run. If a command was renamed/removed, surface that with the doc link rather than guessing repeatedly. Key URIs:

• Overview & command list: https://vercel.com/docs/cli
• Per-command: https://vercel.com/docs/cli/<command>
• Global options: https://vercel.com/docs/cli/global-options
• vercel.json config: https://vercel.com/docs/project-configuration
• REST API (for vercel api): https://vercel.com/docs/rest-api

Full URI map: references/commands.md.

Common Flags

Flag	Description
--token <t>	Auth token (prefer VERCEL_TOKEN env var)
--scope <team>	Team/scope to operate in
--cwd <dir>	Run as if in a different directory
--target <env>	Target a custom environment
--yes / -y	Skip prompts (NEVER on Forbidden ops)
--debug	Verbose output for troubleshooting
--json	Machine-readable output where supported

Error Handling

Error	Cause	Fix
command not found: vercel	Not installed	npm i -g vercel
Not authorized / No existing credentials	Not logged in	vercel login or set VERCEL_TOKEN
Your codebase isn't linked	Dir not linked	vercel link
The provided token is not valid	Bad/expired token	Regenerate at /account/tokens
Can't find the specified scope	Wrong team	vercel teams ls → vercel switch
unknown or unexpected option	Flag renamed	Self-heal: fetch /docs/cli/<command>

Shell Safety

• Never pass --yes/-y to Destructive or Forbidden ops
• Prefer VERCEL_TOKEN env var over --token (argv is visible in process lists)
• Quote multi-word values, env values, and DNS records
• Append | cat if a command might invoke a pager
• Verify team/project before any production or delete op

Integration

Pairs with: github-cli (repo/PRs that trigger deploys), nextjs-senior-dev / next-upgrade (the apps deployed), supabase-cli / neon-postgres-agent-platforms (data services), code-quality (review before a prod deploy).