vercel — Vercel frontend cloud CLI

What it is

vercel is the official CLI for Vercel's frontend cloud. It links a local directory to a Vercel project, deploys (preview + production), manages environment variables, tails logs, and configures domains and certificates. The CLI wraps the Vercel REST API — anything you can do in the dashboard, you can usually do here.

Reach for it whenever you deploy outside of the Git integration, need to sync env vars to .env.local for next dev / astro dev, or want to roll back a bad deploy from your terminal. There's no Vercel-specific alternative — for other platforms see wrangler (Cloudflare), netlify-cli (Netlify), or flyctl (Fly.io).

Install

Vercel recommends global install so the CLI is available outside any project's node_modules. Use the package manager you already have on PATH.

npm install -g vercel

Output: added 1 package; vercel on PATH

pnpm add -g vercel

Output: added vercel globally

bun add -g vercel

Output: added vercel globally

Per-project install (pins the version in CI):

npm install -D vercel
npx vercel --version

Output: prints installed vercel version

Verify and log in:

vercel --version
vercel login

Output:

Vercel CLI 47.x.x
> Log in to Vercel — opens browser
Success! GitHub authentication complete for alice@example.com

Day-to-day commands

Common scenarios

These cover the day-to-day flows. Pair them with project-level config in vercel.json.

First-time setup on a clean clone

vercel login
cd my-app
vercel link
vercel env pull .env.local
npm run dev

Output: .vercel/project.json is written (gitignored), and .env.local is populated from the dev environment. The dev server now has all the env vars production sees.

For non-interactive linking in CI / scripts:

vercel link --project my-project --yes --token $VERCEL_TOKEN

Output: writes .vercel/project.json without prompts.

Preview vs production deploy

vercel deploy defaults to a preview deploy — its own URL, isolated from production.

vercel deploy                              # preview
vercel deploy --prod                       # production
vercel deploy --prebuilt --prod            # production using a local .vercel/output/

Output: each command prints a single-line deployment URL. Capture with URL=$(vercel deploy).

The --prebuilt flow is recommended in CI:

vercel pull --yes --environment=production --token $VERCEL_TOKEN
vercel build --prod --token $VERCEL_TOKEN
vercel deploy --prebuilt --prod --token $VERCEL_TOKEN

Output: three sequential commands; the third uploads the pre-built .vercel/output/ directly without remote build.

Manage env vars

vercel env ls                                            # show all vars per env
vercel env add DATABASE_URL production                   # prompts for value
vercel env add STRIPE_KEY preview development            # add to two envs at once
vercel env rm DEBUG production                           # remove

Output:

> Adding Environment Variable DATABASE_URL to Production
✔ What's the value of DATABASE_URL? ********
✓ Added Environment Variable DATABASE_URL to Project alice-api [200ms]

Pull current env to a local file:

vercel env pull .env.local                                  # development env
vercel env pull .env.production --environment=production    # production env

Output: writes the file; prints how many vars were pulled. Overwrites existing — back up local-only overrides first.

Tail Function logs

vercel logs alice-api.vercel.app           # latest production logs
vercel logs alice-api.vercel.app --since 1h --follow  # tail
vercel logs <preview-url> --output raw

Output: request lines with status code, latency, region, and any console.log output from the Function.

Roll back to a previous deploy

Vercel rollback is "re-alias the production domain to a previous deployment":

vercel ls                                  # find a known-good deployment URL
vercel alias set <previous-url> alice-api.example.com

Output: the production alias now points at the chosen deployment; the rollback takes effect within seconds.

Or use vercel promote if the previous deploy is a preview you want to ship:

vercel promote <preview-deployment-url>

Output: alias of the production domain updates instantly.

Custom domains and certificates

vercel domains add example.com
vercel domains inspect example.com         # DNS records needed
vercel certs ls                            # list issued certs
vercel certs issue example.com www.example.com

Output: Vercel prints the DNS records to add at your registrar. Once propagated, certs are issued via Let's Encrypt automatically.

Local dev with Vercel parity

vercel dev runs the full Vercel build pipeline locally — slower than next dev / astro dev, but faithful to the production routing rules in vercel.json.

vercel dev --listen 3000

Output:

> Ready! Available at http://localhost:3000

Use this when you need to test rewrites, headers, or Edge / Node Function behaviour that differs from the framework's own dev server.

Useful flags

Configuration

Most configuration lives in vercel.json at the project root and is committed to the repo. The CLI does not write vercel.json automatically — you author it manually.

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "framework": "nextjs",
  "buildCommand": "pnpm run build",
  "installCommand": "pnpm install --frozen-lockfile",
  "outputDirectory": ".next",
  "regions": ["iad1"],
  "headers": [
    {
      "source": "/static/(.*)",
      "headers": [{ "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }]
    }
  ],
  "redirects": [
    { "source": "/old", "destination": "/new", "permanent": true }
  ],
  "rewrites": [
    { "source": "/api/(.*)", "destination": "https://upstream.example.com/api/$1" }
  ],
  "crons": [
    { "path": "/api/cron/cleanup", "schedule": "0 3 * * *" }
  ]
}

The CLI reads vercel.json for every deploy, and the dashboard merges it with project settings. Routing config (headers, redirects, rewrites) in vercel.json wins over project-level settings; build inputs (build / install command) from the dashboard win over vercel.json unless you set them as part of "Override" in the dashboard UI.

Per-machine config lives in ~/.local/share/com.vercel.cli/ (Linux/macOS) or %APPDATA%\com.vercel.cli\ (Windows). Per-project linking lives in .vercel/project.json (gitignored).

Common pitfalls

1. vercel deploy without --prod is a preview deploy. Many teams accidentally update production by leaving the flag off in CI scripts — be explicit. Mirror the inverse in dev — never run vercel --prod from your laptop.
2. .vercel/project.json is per-directory. A monorepo needs vercel link run in each deployable app folder. Without it, deploys go to whichever project the root was linked to.
3. vercel env pull overwrites .env.local. No prompt, no merge. Back up local-only overrides first or use --environment=preview / --environment=development to scope.
4. vercel dev ≠ next dev. It runs the full Vercel build pipeline. Slower but reflects production routing. If you only care about app logic, next dev / astro dev is faster.
5. Aliases are how rollback works. There is no vercel rollback. Re-alias the production domain to a previous deployment URL via vercel alias set.
6. Tokens scope to whole accounts by default. When generating a token in the dashboard, scope it to a specific team. Rotate every 90 days.
7. vercel.json settings vs framework config drift. Headers in next.config.js AND vercel.json produce a merged result that's hard to reason about. Pick one source of truth.
8. Function maxDuration matters. Default is 10s (Hobby) / 60s (Pro). Long requests fail with FUNCTION_INVOCATION_TIMEOUT. Set in vercel.json functions.<path>.maxDuration or per-route.

See also

• Packages-npm: vercel — package-level reference (Node support, ecosystem, security)
• JavaScript: wrangler — peer CLI for Cloudflare Workers / Pages
• JavaScript: npm — installing the CLI globally vs per-project
• JavaScript: package-json — engines, scripts, framework-detect markers