vercel-management

What this skill does

# Vercel Management

Comprehensive guide for managing Vercel projects entirely via CLI and API, eliminating the need for dashboard access.

## Quick Reference

| Task | Command | Notes |
|------|---------|-------|
| **Deploy** | `vercel --prod` | Production deployment |
| **Deploy preview** | `vercel` | Preview deployment |
| **Link project** | `vercel link` | Link local directory |
| **Pull config** | `vercel pull` | Download settings & env vars |
| **Env add** | `echo "value" \| vercel env add KEY production` | Add environment variable |
| **Env pull** | `vercel env pull .env.local` | Pull dev env vars to file |
| **List deployments** | `vercel list` | Recent deployments |
| **Promote** | `vercel promote <url>` | Make deployment current |
| **Rollback** | `vercel rollback` | Revert to previous |
| **Domain add** | `vercel domains add example.com` | Add custom domain |
| **DNS add** | `vercel dns add example.com www A 1.2.3.4` | Add DNS record |
| **Logs** | `vercel logs <url>` | Stream deployment logs |
| **Team context** | `vercel --team=myteam deploy` | Deploy to team |

## Installation & Authentication

### Install CLI

```bash
# Global installation
npm install -g vercel@latest

# Or use with npx
npx vercel@latest
```

### Authentication

```bash
# Interactive login
vercel login

# Login with email
vercel login [email protected]

# CI/CD authentication (use token)
vercel --token $VERCEL_TOKEN deploy --prod

# Create token at: https://vercel.com/account/tokens
export VERCEL_TOKEN="your-token-here"
```

### Check Authentication

```bash
vercel whoami
# Shows current user or team
```

## Project Management

### Initialize & Link Projects

```bash
# Initialize new project
vercel init nextjs-app

# Link existing directory to Vercel project
vercel link

# Link with specific scope
vercel link --scope=my-team

# Pull project settings and environment variables
vercel pull
vercel pull --environment=production
vercel pull --yes  # Skip prompts
```

### Project Configuration

The `vercel pull` command creates:
- `.vercel/project.json` - Project metadata
- `.vercel/README.txt` - Configuration info
- `.env.local` - Development environment variables

### Open in Dashboard (when necessary)

```bash
vercel open
# Opens current project in browser
```

## Deployment

### Basic Deployment

```bash
# Deploy to preview environment
vercel

# Deploy to production
vercel --prod

# Deploy from specific directory
vercel /path/to/project --prod

# Deploy with custom working directory
vercel --cwd /path/to/project --prod
```

### Advanced Deployment Options

```bash
# Force deployment (skip cache)
vercel --force --prod

# Force with cache retention
vercel --force --with-cache --prod

# Deploy prebuilt output (no build step)
vercel deploy --prebuilt --prod

# Deploy without waiting
vercel --no-wait --prod

# Deploy with build logs
vercel --logs --prod

# Skip auto-assigning production domain
vercel --prod --skip-domain

# Deploy to specific regions (functions)
vercel --regions sfo1,iad1 --prod

# Add metadata to deployment
vercel --meta commit=abc123 --meta branch=main --prod

# Set environment variables at runtime
vercel -e NODE_ENV=production --prod

# Set build-time environment variables
vercel -b API_URL=https://api.example.com --prod

# Archive deployment (for large file counts)
vercel --archive=tgz --prod
```

### Capture Deployment URL

```bash
# Deployment URL always goes to stdout
vercel --prod > deployment-url.txt
url=$(vercel --prod)
echo "Deployed to: $url"

# In CI/CD scripts
if vercel --prod > deployment-url.txt 2> error.txt; then
  DEPLOY_URL=$(cat deployment-url.txt)
  echo "Success: $DEPLOY_URL"
else
  echo "Failed: $(cat error.txt)"
  exit 1
fi
```

## Environment Variables

### List Environment Variables

```bash
# List all environment variables
vercel env ls

# List for specific environment
vercel env ls production
vercel env ls preview
vercel env ls development

# List with git branch filter
vercel env ls preview main
```

### Add Environment Variables

```bash
# Add to production (prompts for value)
vercel env add API_KEY production

# Add from stdin
echo "secret-value" | vercel env add API_KEY production

# Add to multiple environments
vercel env add API_KEY production
vercel env add API_KEY preview

# Add sensitive variable (hidden in dashboard)
echo "secret" | vercel env add SECRET production --sensitive

# Add from file
cat cert.pem | vercel env add CERTIFICATE production
```

### Update Environment Variables

```bash
# Update existing variable
vercel env update API_KEY production

# Update from stdin
echo "new-value" | vercel env update API_KEY production

# Update from file
cat ~/.npmrc | vercel env update NPM_RC preview
```

### Remove Environment Variables

```bash
# Remove from specific environment
vercel env rm API_KEY production

# Remove from all environments
vercel env rm API_KEY production
vercel env rm API_KEY preview
vercel env rm API_KEY development
```

### Pull Environment Variables to File

```bash
# Pull development variables to .env.local
vercel env pull .env.local

# Pull production variables
vercel env pull --environment=production .env.production

# Pull preview variables for specific branch
vercel env pull --environment=preview --git-branch=feature-x .env.preview

# Auto-confirm
vercel env pull --yes .env.local
```

### Run Commands with Environment Variables

```bash
# Run command with Vercel environment variables (no file write)
vercel env run -- next dev
vercel env run -- npm test
vercel env run -- node script.js

# Specify environment
vercel env run -e production -- npm run migration
vercel env run -e preview -- npm run seed

# With git branch
vercel env run -e preview --git-branch feature-x -- npm start
```

## Deployment Management

### List Deployments

```bash
# List recent deployments
vercel list
vercel ls

# List for specific project
vercel list my-project

# Filter by environment
vercel list --environment=production
vercel list --environment=preview

# Filter by metadata
vercel list --meta commit=abc123
vercel list --meta branch=main

# Production deployments only
vercel list --prod
```

### Promote Deployments

```bash
# Promote deployment to production
vercel promote https://my-app-xyz123.vercel.app
vercel promote <deployment-id>

# Typical workflow: staged production deployment
vercel --prod --skip-domain > staging-url.txt
# Test the deployment
# If good, promote:
vercel promote $(cat staging-url.txt)
```

### Redeploy

```bash
# Redeploy existing deployment
vercel redeploy https://my-app-xyz123.vercel.app

# Rebuild with latest code
vercel redeploy <deployment-url>
```

### Rollback

```bash
# Rollback to previous production deployment
vercel rollback

# Rollback to specific deployment
vercel rollback https://my-app-xyz123.vercel.app
```

### Remove Deployments

```bash
# Remove specific deployment
vercel remove <deployment-url>
vercel rm <deployment-id>

# Remove with confirmation bypass
vercel remove <deployment-url> --yes
```

### Inspect Deployments

```bash
# Get detailed deployment information
vercel inspect <deployment-url>
vercel inspect <deployment-id>
```

## Domain Management

### List Domains

```bash
vercel domains ls
```

### Add Domain

```bash
# Add domain to current project
vercel domains add example.com

# Vercel will provide DNS configuration instructions
```

### Remove Domain

```bash
vercel domains rm example.com
```

### Inspect Domain

```bash
# Check domain configuration
vercel domains inspect example.com
```

### Aliases

```bash
# List aliases
vercel alias ls

# Set custom alias
vercel alias set <deployment-url> custom.example.com

# Remove alias
vercel alias rm custom.example.com
```

## DNS Management

### List DNS Records

```bash
vercel dns ls

# List for specific domain
vercel dns ls example.com
```

### Add DNS Records

```bash
# Add A record
vercel dns add example.com www A 76.76.21.21

# Add CNAME record
vercel dns add example.com blog CNAME myblog.vercel.app

# Add TXT record