Vercel CLI — Preview-then-Promote Workflow

A practical command guide for testing builds on preview before they go live.

One-time setup

You only do these once per machine / project.

After vercel link, all the commands below act on that linked project automatically.

The everyday loop

This is the core cycle: deploy a preview, test it, promote it when happy.

1. Deploy a preview

vercel

Running vercel with no flags creates a preview deployment. It builds your current local code and returns a unique preview URL. This uses your preview environment variables, and does not touch your live site.

vercel deploy is the same thing — vercel on its own is just shorthand.

2. See what's deployed

vercel list --status READY

Lists deployments that finished building and are ready to serve, with their URLs, timestamps, and Git branch. Use this to grab the URL of the preview you want to test or promote.

3. Inspect a specific deployment

vercel inspect <deployment-url>

Shows the commit, branch, build duration, and function config for that deployment — so you can confirm it's the exact code you think it is before promoting.

4. Check it for errors

vercel logs <deployment-url>

Streams the logs for that deployment. To narrow to just problems:

vercel logs <deployment-url> --level error --limit 50

If that comes back clean, the deployment is safe to promote.

5. Promote to production

vercel promote <deployment-url>

Points your production domain at that deployment, making it live. Note: promoting triggers a fresh rebuild using your production environment variables — so the live build isn't byte-identical to the preview if your prod/preview env vars differ.

Check how the promotion is going:

vercel promote status

Add --yes to skip the confirmation prompt (useful in scripts):

vercel promote <deployment-url> --yes

Deploying straight to production (when you skip the preview gate)

vercel --prod

Builds your current local code and pushes it directly to production. This is the fast path when you don't need a preview step.

Variant: staged production build

If you want the actual production build (with production env vars) sitting ready but not yet live, so you can verify it first:

vercel --prod --skip-domain

The --skip-domain flag builds a production deployment but does not assign your domain to it — the site stays on the old version. When you've verified it:

vercel promote <deployment-url>

This finishes the domain assignment and makes it live, without another rebuild.

Safety net: rollback

If a bad deployment does reach production, revert fast:

vercel rollback <deployment-url>

Points production back at a previous, known-good deployment. It just reassigns the domain (no rebuild), so recovery is near-instant. Run vercel rollback with no URL to roll back to the immediately previous production deployment.

Handling environment variables

Because preview and production can use different env vars, it's worth pulling them locally so your local builds match:

vercel pull --environment=preview      # pull preview env vars
vercel pull --environment=production   # pull production env vars

This writes the values into a local .env file so vercel build / local runs use the right ones.

Quick reference — the minimal flow

vercel                              # 1. build a preview
vercel list --status READY          # 2. find its URL
vercel logs <url> --level error     # 3. check for errors
vercel promote <url>                # 4. go live
# ...if something breaks:
vercel rollback                     # 5. revert instantly