Vercel CLI

You are an expert in the Vercel CLI v50.28.0 (

vercel

vc

). The CLI is the primary way to manage Vercel projects from the terminal.

Installation

bash

npm i -g vercel

Login

The CLI uses an OAuth 2.0 Device Flow for authentication.

bash

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

bash

# 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

bash

# 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:

bash

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

bash

# 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.

bash

# 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

bash

# 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

bash

# List DNS records
vercel dns ls example.com

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

Teams

bash

# List teams
vercel teams ls

# Switch to a team
vercel teams switch my-team

Cache Management

bash

# 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

bash

# 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

)

bash

# 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

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.

bash

# 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):

bash

# 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

bash

# 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 — Claude Code can call Vercel APIs with no additional configuration.

bash

# 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

bash

# 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:

bash

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

GitHub Actions Example

yaml

- 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

Flag	Purpose
`--token`	Authentication token (for CI)
`--cwd <dir>`	Working directory
`--debug` / `-d`	Verbose output
`--yes` / `-y`	Skip confirmation prompts
`--scope <team>`	Execute as a team

Common Workflows

First-Time Setup

bash

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

Deploy from CI

bash

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

Quick Preview

bash

vercel               # Creates preview deployment, returns URL

vercel-cli

NPX Install

Tags

SKILL.md Content

Vercel CLI

Installation

Login

Core Commands

Deployment

Development

Deterministic Project Linking (Recommended)

Environment Variables

Logs & Inspection

Domains

DNS

Teams

Cache Management

MCP Server Integration

Programmatic Configuration (
`@vercel/config`
)

Marketplace Integrations

Agent-Optimized:
`discover`
and
`guide`

Project-Level Routing (No Redeploy)

Feature Flags

Direct API Access

Metrics

CI/CD Integration

GitHub Actions Example

Global Options

Common Workflows

First-Time Setup

Deploy from CI

Quick Preview

Official Documentation

vercel-cli

NPX Install

Tags

SKILL.md Content

Vercel CLI

Installation

Login

Core Commands

Deployment

Development

Deterministic Project Linking (Recommended)

Environment Variables

Logs & Inspection

Domains

DNS

Teams

Cache Management

MCP Server Integration

Programmatic Configuration (@vercel/config)

Marketplace Integrations

Agent-Optimized: discover and guide

Project-Level Routing (No Redeploy)

Feature Flags

Direct API Access

Metrics

CI/CD Integration

GitHub Actions Example

Global Options

Common Workflows

First-Time Setup

Deploy from CI

Quick Preview

Official Documentation

Programmatic Configuration (
`@vercel/config`
)

Agent-Optimized:
`discover`
and
`guide`