Vercel: deploy with approval

Hard rule. Never run a command from the "needs approval" list until the user has, in this conversation, said yes to that specific action after you showed them the command, the team and project it targets, whether it is a preview or production deployment, and what it changes. An earlier yes does not cover a later, different command.

Pushing a commit is a deploy when the project has Git integration: a push to the production branch (usually main) creates a production deployment, and a push to any other branch creates a preview. Treat git push, merging a pull request and vercel --prod the same way.

Preview versus production

	Preview	Production
Created by	vercel, vercel deploy, push to a non-production branch, a PR	vercel --prod, vercel deploy --target=production, push to the production branch, promoting a deployment
URL	unique per deployment (and a branch URL)	your production domains
Env vars	Preview environment (optionally per branch)	Production environment
Risk	low, but may still run build hooks and write to shared services	real users, real data

The first deployment of a brand-new project is always production, even if you omit --prod. So vercel run in a directory that is not yet linked to a project can create the project and make a production deployment. Check for .vercel/project.json first (the /vercel-preflight command reports it); if it is absent, say so and ask before linking or creating anything. Never use --yes to skip the project-setup questions without approval; it answers them with guessed defaults.

Custom environments (for example staging) are targeted with vercel deploy --target=staging.

Commands by risk

Safe without approval (local or read-only):

• vercel --version, vercel whoami, vercel list, vercel inspect <url>
• vercel logs ... (read-only; see vercel-logs-debug)
• vercel deploy --dry (CLI 59.x: reports the detected framework preset and the files that would be uploaded, without creating a deployment; it needs the user to be logged in, and you should confirm with vercel deploy --help on their version)
• vercel build (builds locally into .vercel/output; needs vercel pull first)
• vercel env ls (names and types, not values); vercel env run -- <cmd> with the default Development values (production or preview values go to the command's process, so ask first)
• /vercel-preflight

Needs approval (changes the account, creates a deployment, or writes secrets):

• vercel, vercel deploy (preview), vercel --prod (shorthand for --target=production), vercel deploy --prebuilt, and vercel deploy --temporary (uploads the source to a temporary public deployment without a login)
• vercel link, vercel project add|rm, vercel git connect
• vercel promote, vercel rollback, vercel redeploy, vercel remove
• vercel env add|update|rm, and vercel env pull / vercel pull (they write environment values to files on disk; use vercel env run when you only need them for one command)
• vercel domains ..., vercel alias ..., vercel dns ..., vercel certs ...
• vercel login and anything that opens a browser OAuth flow: the user does this
• git push / opening or merging a PR on a Vercel-connected repository
• Vercel MCP tools that deploy, change settings, or buy anything

Never ask for a Vercel token in chat and never print one. Authentication is the user's vercel login or a VERCEL_TOKEN they export themselves. A Vercel command run without credentials may start a browser login flow instead of failing; if you see "No existing credentials found", stop and tell the user to run vercel login. Do not drive the login yourself.

Agent-run CLIs are non-interactive by default (--non-interactive), so prompts fail instead of waiting. Do not "fix" that by adding --yes; ask the user.

Workflow

1. Preflight. Run /vercel-preflight. Fix errors; explain warnings.
2. Identify the target. vercel whoami, then read .vercel/project.json (project name and org) or the Git remote. State team, project and branch. If the team is ambiguous, ask.
3. Build and test locally with the project's own commands. To reproduce Vercel's build: vercel pull --environment=preview then vercel build (--environment=production and vercel build --prod for production settings). Pulling writes env files under .vercel/; keep them gitignored.
4. Choose preview first. Even for a production release, deploy a preview, verify it, then promote or merge. Say that in the plan.
5. Ask. Present a short plan:
   • exact command, team/project, environment (preview, production, custom)
   • what changes: new deployment, domains, env vars, build cache (--force)
   • how you will verify, and how to roll back Then stop and wait for an explicit yes.
6. Run only the approved command. vercel prints the deployment URL on stdout; use --logs if you need build logs, --no-wait only if asked.
7. Verify. vercel inspect <url> for status. Request the URL with curl -sS -o /dev/null -w "%{http_code}\n" <url>. A preview behind Deployment Protection answers 401 or redirects to login: that is expected. Do not disable protection or generate bypass links; ask the user to open it signed in, or to use the documented vercel curl helper themselves.
8. Report the deployment URL and ID from the command output. If it failed, show the error text, run vercel inspect <url> --logs, and only then propose a fix.

Promote and rollback

• vercel promote <deployment-url-or-id> makes an existing deployment the current production deployment (promoting a preview creates a production deployment and asks for confirmation; --yes bypasses it, so do not add it without approval). vercel promote status shows pending promotions.
• vercel rollback [deployment-url-or-id] points production back at an earlier deployment. On the Hobby plan only the previous production deployment is eligible. vercel rollback status shows pending rollbacks. To undo a rollback, vercel promote a deployment.
• A rollback restores code and its build-time configuration, not data. Database changes made by the bad release are not reverted.

Prebuilt deploys

vercel build followed by vercel deploy --prebuilt (optionally --archive=tgz for thousands of files) deploys local build output. System environment variables such as VERCEL_ENV are missing at build time then, so use Git-based or plain vercel deploys if the build reads them.

If the user did not approve

Say what was done (preflight, local build), what was not, and the exact command they can run or approve. Do not deploy "to see if it works".