vercel-cli

Vercel CLI

You are an expert in the Vercel CLI v50.28.0 (vercel or vc). The CLI is the primary way to manage Vercel projects from the terminal.

Installation

npm i -g vercel

Login

The CLI uses an OAuth 2.0 Device Flow for authentication.

vercel login

Deprecation notice: Email-based login (vercel login your@email.com) and the flags --github, --gitlab, --bitbucket, --oob were removed February 26, 2026. The team method (SAML-based login) remains supported until June 1, 2026, then will also be removed.

Core Commands

Deployment

# Preview deployment (from project root)
vercel

# Production deployment
vercel --prod

# Build locally, deploy build output only
vercel build
vercel deploy --prebuilt

# Build for production (uses production env vars)
vercel build --prod
vercel deploy --prebuilt --prod

# Force a new deployment (skip cache)
vercel --force

# Promote a preview deployment to production
vercel promote <deployment-url>

# Rollback to previous production deployment
vercel rollback

Development

# Start local dev server with Vercel features
vercel dev

# Link current directory to a Vercel project
vercel link

# Deterministic non-interactive link (recommended for bootstrap/automation)
vercel link --yes --project <name-or-id> --scope <team>

# Pull environment variables and project settings
vercel pull

# Pull specific environment
vercel pull --environment=production

# Open linked project in the Vercel Dashboard
vercel open

Deterministic Project Linking (Recommended)

Prefer explicit non-interactive linking for bootstrap and automation:

vercel link --yes --project <name-or-id> --scope <team>

This is more reliable than interactive prompt-driven linking, which can pick the wrong project or team in multi-account setups. If there is any ambiguity, run vercel open to confirm the dashboard project, then relink with explicit --project and --scope.

Environment Variables

# List all environment variables
vercel env ls

# Add an environment variable
vercel env add MY_VAR

# Add for specific environments
vercel env add MY_VAR production
vercel env add MY_VAR preview development

# Add branch-scoped variable
vercel env add MY_VAR preview --branch=feature-x

# Add sensitive (write-only) variable
vercel env add MY_SECRET --sensitive

# Remove an environment variable
vercel env rm MY_VAR

# Pull all env vars to .env.local
vercel env pull
vercel env pull .env.production.local --environment=production

Logs & Inspection

The vercel logs command (rebuilt February 2026) supports historical log querying and uses git context by default — it automatically scopes logs to your current repository when run from a project directory.

# View runtime/function logs (real-time)
vercel logs <deployment-url>

# Follow logs in real-time (streaming mode)
vercel logs <deployment-url> --follow

# Query historical logs (no longer limited to live-only)
vercel logs --since 24h
vercel logs --since 7d

# Filter by time range
vercel logs <deployment-url> --since 1h
vercel logs <deployment-url> --since 30m

# Filter by log level
vercel logs <deployment-url> --level error
vercel logs <deployment-url> --level warning

# Filter by deployment ID, request ID, or arbitrary string
vercel logs --deployment-id dpl_xxxxx
vercel logs --request-id req_xxxxx
vercel logs --query "TypeError"

# Output as JSON (for piping to jq or other tools)
vercel logs <deployment-url> --json

# Combine filters: stream errors from the last hour as JSON
vercel logs <deployment-url> --follow --since 1h --level error --json

# Inspect a deployment (build details, metadata, function list)
vercel inspect <deployment-url>

# List recent deployments
vercel ls

Note: vercel logs shows runtime request logs only. For build output, use vercel inspect <deployment-url> or view build logs at https://vercel.com/{team}/{project}/deployments → select deployment → Build Logs.

Drains and advanced observability: Log drains, trace export, and analytics data forwarding are configured via the Vercel Dashboard at https://vercel.com/dashboard/{team}/~/settings/log-drains or REST API (/v1/drains), not the CLI. See ⤳ skill: observability for drain setup, payload schemas, and signature verification.

Domains

# List domains
vercel domains ls

# Add a domain to a project
vercel domains add example.com

# Remove a domain
vercel domains rm example.com

DNS

# List DNS records
vercel dns ls example.com

# Add a DNS record
vercel dns add example.com @ A 1.2.3.4

Teams

# List teams
vercel teams ls

# Switch to a team
vercel teams switch my-team

Cache Management

# Purge all cache (CDN + Data cache) for current project
vercel cache purge

# Purge only CDN cache
vercel cache purge --type cdn

# Purge only Data cache
vercel cache purge --type data

# Purge without confirmation prompt
vercel cache purge --yes

# Invalidate by tag (stale-while-revalidate)
vercel cache invalidate --tag blog-posts

# Invalidate multiple tags
vercel cache invalidate --tag blog-posts,user-profiles,homepage

# Hard delete by tag (blocks until revalidated — use with caution)
vercel cache dangerously-delete --tag blog-posts

# Hard delete with revalidation deadline (deletes only if not accessed within N seconds)
vercel cache dangerously-delete --tag blog-posts --revalidation-deadline-seconds 3600

# Invalidate cached image transformations by source path
vercel cache invalidate --srcimg /api/avatar/1

# Hard delete cached image transformations
vercel cache dangerously-delete --srcimg /api/avatar/1

Key distinction: invalidate serves STALE and revalidates in the background. dangerously-delete serves MISS and blocks while revalidating. Prefer invalidate unless you need immediate freshness.

Note: --tag and --srcimg cannot be used together.

MCP Server Integration

# Initialize global MCP client configuration for your Vercel account
vercel mcp

# Set up project-specific MCP access for the linked project
vercel mcp --project

The vercel mcp command links your local MCP client configuration to a Vercel Project. It generates connection details so AI agents and tools can call your MCP endpoints deployed on Vercel securely.

Programmatic Configuration (@vercel/config)

# Compile vercel.ts to JSON (stdout)
npx @vercel/config compile

# Validate configuration and show summary
npx @vercel/config validate

# Generate vercel.json locally for development
npx @vercel/config generate

Use vercel.ts (or .js, .mjs, .cjs, .mts) instead of vercel.json for type-safe, dynamic project configuration. Only one config file per project — vercel.json or vercel.ts, not both.

Note: Legacy now.json support will be removed on March 31, 2026. Rename to vercel.json (no content changes needed).

Marketplace Integrations

Auto-provisioning is the default for vercel integration add — the CLI automatically creates resources and sets environment variables without extra prompts.

# List installed integrations
vercel integration list

# Add an integration (auto-provisions env vars by default)
vercel integration add neon

# Open an integration's dashboard
vercel integration open neon

# Remove an integration
vercel integration remove neon

Agent-Optimized: discover and guide

AI agents can autonomously discover, install, and retrieve setup instructions for Marketplace integrations (added March 2026):

# Search the integration catalog (returns JSON for automation)
vercel integration discover --format=json

# Search with a keyword filter
vercel integration discover database --format=json

# Get agent-friendly setup guide with code snippets
vercel integration guide neon

# Full workflow: discover → add → guide
vercel integration discover storage --format=json
vercel integration add neon
vercel integration guide neon

• discover — Searches the Vercel Marketplace catalog. Use --format=json for non-interactive output suitable for scripting and agent pipelines.
• guide <name> — Returns getting-started documentation in agent-friendly markdown: environment variables, SDK setup, and code snippets.
• Human-in-the-loop safety: the CLI prompts for developer confirmation when accepting Terms of Service.

Full subcommands: discover, guide, add, list (alias ls), balance, open, remove.

Project-Level Routing (No Redeploy)

Create and update routing rules — headers, rewrites, redirects — without building a new deployment. Rules take effect instantly.

Available via dashboard (CDN tab), API, CLI, and Vercel SDK. Project-level routes run after bulk redirects and before deployment config routes.

Feature Flags

# Create a feature flag
vercel flags add redesigned-checkout --kind boolean --description "New checkout flow"

# List SDK keys
vercel flags sdk-keys ls

# Enable/disable, archive, and manage flags from CLI
vercel flags --help

See ⤳ skill: vercel-flags for full flag configuration and adapter patterns.

Direct API Access

The vercel api command (added January 2026) gives direct access to the full Vercel REST API from the terminal. Designed for AI agents — call Vercel APIs with no additional configuration.

# Call any Vercel REST API endpoint
vercel api GET /v9/projects
vercel api GET /v13/deployments
vercel api POST /v9/projects/:id/env --body '{"key":"MY_VAR","value":"val","target":["production"]}'

# Pipe JSON output to jq
vercel api GET /v9/projects | jq '.[].name'

Metrics

# Query project metrics (rich text output with sparklines)
vercel metrics

# Raw values for scripting
vercel metrics --raw-values

CI/CD Integration

Required environment variables for CI:

VERCEL_TOKEN=<your-token>
VERCEL_ORG_ID=<org-id>
VERCEL_PROJECT_ID=<project-id>

GitHub Actions Example

- name: Deploy to Vercel
  run: |
    vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
    vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
    vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

Global Options

Common Workflows

First-Time Setup

vercel link          # Connect to Vercel project
vercel env pull      # Get environment variables
vercel dev           # Start local dev

Deploy from CI

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

Quick Preview

vercel               # Creates preview deployment, returns URL

Official Documentation

• Vercel CLI
• Cache Management
• MCP Integration
• Deployments
• REST API
• GitHub: Vercel CLI