Vercel CLI Skill

Purpose: Fast reference for Vercel CLI operations | Target: <500 lines

Overview

What is Vercel: Frontend cloud platform with automatic CI/CD, serverless functions, edge network, and global CDN. Optimized for Next.js, React, Vue, and other frameworks.

When to Use:

•Deploying frontend applications
•Managing serverless functions and domains
•Managing environment variables
•Debugging deployments and logs

Auto-Detection Triggers:

•vercel.json in project root
•.vercel directory present
•VERCEL_TOKEN in .env file

Progressive Disclosure:

•This file: Quick reference for immediate use
•REFERENCE.md: Advanced patterns, CI/CD, troubleshooting deep-dives

•Critical: Avoiding Interactive Mode
•Prerequisites
•Authentication
•CLI Decision Tree
•Command Reference
•Static Reference Data
•Common Workflows
•Error Handling
•Framework Examples
•Agent Integration
•Quick Reference Card

Critical: Avoiding Interactive Mode

Vercel CLI can hang Claude Code. Always use flags to bypass prompts:

Command	WRONG	CORRECT
Deploy	`vercel`	`vercel --yes --token $VERCEL_TOKEN`
Link	`vercel link`	`vercel link --yes --project <name>`
Pull env	`vercel pull`	`vercel pull --yes --environment production`
Add env	`vercel env add`	`vercel env add NAME production < value.txt`
Remove	`vercel env rm NAME`	`vercel env rm NAME --yes`

Required flags: --yes, --token <TOKEN>, explicit names, --no-wait

Never use: vercel login, vercel dev, commands without --yes when modifying

Prerequisites

bash

# Check CLI
vercel --version  # Expects: 30.x.x+

# Install
npm i -g vercel

Authentication

Token Type	Scope	Use Case
Personal	Full account	CI/CD, automation
Team	Team-scoped	Team deployments
Project	Project-scoped	Limited access

bash

# Set token from .env
export VERCEL_TOKEN="$(grep VERCEL_TOKEN .env | cut -d= -f2)"
vercel --token $VERCEL_TOKEN whoami

CLI Decision Tree

Project Operations

code

Link to project      --> vercel link --yes --project <name>
List projects        --> vercel project ls
Create project       --> vercel project add <name>
Remove project       --> vercel project rm <name> --yes
Current user         --> vercel whoami
Switch teams         --> vercel switch <team-slug>

Deployment Operations

code

Deploy preview       --> vercel --yes
Deploy production    --> vercel --prod --yes
Staged production    --> vercel --prod --skip-domain --yes
Promote staged       --> vercel promote <url> --yes
Redeploy existing    --> vercel redeploy <url> --no-wait
Rollback             --> vercel rollback <url>
List deployments     --> vercel list [project]
Inspect deployment   --> vercel inspect <url>
Remove deployment    --> vercel remove <url> --yes

Environment Variables

code

List vars            --> vercel env ls [environment]
Add var              --> echo "value" | vercel env add NAME production
Add from file        --> vercel env add NAME production < secret.txt
Remove var           --> vercel env rm NAME --yes
Pull to .env         --> vercel pull --yes --environment production

Domains

code

List domains         --> vercel domains ls
Add domain           --> vercel domains add <domain> [project]
Force add            --> vercel domains add <domain> <project> --force
Remove domain        --> vercel domains rm <domain> --yes
Inspect domain       --> vercel domains inspect <domain>

Debugging

code

View logs            --> vercel logs <deployment-url>
Logs as JSON         --> vercel logs <url> --json
Inspect details      --> vercel inspect <url>
HTTP status          --> vercel httpstat <url>

For DNS, certificates, and advanced operations, see REFERENCE.md

Command Reference

Core Commands

Command	Description	Example
`vercel`	Deploy preview	`vercel --yes`
`vercel --prod`	Deploy production	`vercel --prod --yes`
`vercel link`	Link to project	`vercel link --yes --project myapp`
`vercel project ls`	List projects	`vercel project ls --json`
`vercel list`	List deployments	`vercel list --json`
`vercel logs`	View logs	`vercel logs <url>`
`vercel inspect`	Deployment details	`vercel inspect <url>`

Environment Variables

Command	Description	Example
`vercel env ls`	List variables	`vercel env ls production`
`vercel env add`	Add variable	`echo "val" \| vercel env add KEY prod`
`vercel env rm`	Remove variable	`vercel env rm KEY --yes`
`vercel pull`	Pull env + settings	`vercel pull --yes --environment prod`

Domains

Command	Description	Example
`vercel domains ls`	List domains	`vercel domains ls`
`vercel domains add`	Add domain	`vercel domains add api.example.com myapp`
`vercel domains rm`	Remove domain	`vercel domains rm api.example.com --yes`

Static Reference Data

Deployment Regions (Key Regions)

Code	Location	AWS Region
`iad1`	Washington DC (default)	us-east-1
`sfo1`	San Francisco	us-west-1
`fra1`	Frankfurt	eu-central-1
`lhr1`	London	eu-west-2
`hnd1`	Tokyo	ap-northeast-1
`sin1`	Singapore	ap-southeast-1
`syd1`	Sydney	ap-southeast-2

Full 19-region list in REFERENCE.md

Environment Types

Environment	Use Case
`production`	Main branch deployments
`preview`	PR/branch previews
`development`	Local dev (`vercel dev`)

System Variables

Variable	Description
`VERCEL`	Always `1` on Vercel
`VERCEL_ENV`	`production`, `preview`, `development`
`VERCEL_URL`	Deployment URL (no protocol)
`VERCEL_REGION`	Region code (e.g., `iad1`)
`VERCEL_GIT_COMMIT_SHA`	Git commit SHA

Common Workflows

1. Project Setup

bash

vercel link --yes --project myapp
vercel pull --yes --environment development

2. Deploy

bash

vercel --yes                    # Preview
vercel --prod --yes             # Production

3. Staged Production

bash

vercel --prod --skip-domain --yes > staged-url.txt
# Test the staged deployment
vercel promote $(cat staged-url.txt) --yes

4. Environment Variables

bash

vercel env ls production
echo "secret" | vercel env add API_KEY production
vercel env rm OLD_KEY --yes

5. Debug Deployment

bash

vercel logs <deployment-url>
vercel logs <url> --json | jq '.message'
vercel inspect <url>

6. Rollback

bash

vercel rollback <deployment-url>

Advanced workflows (CI/CD, blue-green, canary) in REFERENCE.md

Error Handling

Error	Cause	Resolution
`command not found: vercel`	Not installed	`npm i -g vercel`
`Not authorized`	Invalid token	Check VERCEL_TOKEN
`Project not found`	Wrong name	`vercel project ls`
`No project linked`	Not linked	`vercel link --yes --project <name>`
`Domain already in use`	On other project	Use `--force`
`Deployment failed`	Build error	Check `vercel logs`

Quick Troubleshooting

bash

vercel whoami                    # Verify auth
vercel --token $VERCEL_TOKEN whoami  # Check token
vercel logs <url>                # View errors
vercel inspect <url>             # Deployment details

Deep troubleshooting in REFERENCE.md

Framework Examples

Next.js

json

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "framework": "nextjs",
  "regions": ["iad1", "sfo1"]
}

React (Vite)

json

{
  "framework": "vite",
  "buildCommand": "npm run build",
  "outputDirectory": "dist"
}

More frameworks in REFERENCE.md

Agent Integration

Auto-Detection Triggers

•vercel.json or .vercel directory
•VERCEL_TOKEN in .env
•User mentions "Vercel", "deploy to Vercel"

Pattern Recognition

yaml

High-confidence:
  - "Deploy to Vercel"
  - "vercel deploy", "Vercel logs"
  - "Add domain to Vercel"

Medium-confidence:
  - "Deploy frontend"
  - "Next.js deployment"

Handoff to Deep-Debugger

•Build failures with unclear errors
•Runtime errors in serverless functions
•Performance issues requiring profiling

Provide: vercel logs output, vercel inspect output, vercel.json

Quick Reference Card

bash

# Auth
export VERCEL_TOKEN="xxx"
vercel --token $VERCEL_TOKEN whoami

# Project
vercel link --yes --project myapp
vercel project ls
vercel project rm myapp --yes

# Deploy
vercel --yes                          # Preview
vercel --prod --yes                   # Production
vercel promote <url> --yes            # Promote

# Rollback
vercel rollback <url>

# Env Vars
vercel env ls production
echo "value" | vercel env add KEY production
vercel env rm KEY --yes
vercel pull --yes --environment production

# Domains
vercel domains ls
vercel domains add api.example.com myapp
vercel domains rm api.example.com --yes

# Debug
vercel logs <url>
vercel inspect <url>
vercel list --json

See Also: REFERENCE.md for CI/CD integration, multi-region config, security, cost optimization

managing-vercel

Vercel CLI Skill

Overview

Table of Contents

Critical: Avoiding Interactive Mode

Prerequisites

Authentication

CLI Decision Tree

Project Operations

Deployment Operations

Environment Variables

Domains

Debugging

Command Reference

Core Commands

Environment Variables

Domains

Static Reference Data

Deployment Regions (Key Regions)

Environment Types

System Variables

Common Workflows

1. Project Setup

2. Deploy

3. Staged Production

4. Environment Variables

5. Debug Deployment

6. Rollback

Error Handling

Quick Troubleshooting

Framework Examples

Next.js

React (Vite)

Agent Integration

Auto-Detection Triggers

Pattern Recognition

Handoff to Deep-Debugger

Quick Reference Card