Vercel CLI Management

Vercel CLI Management

Skill para gestionar despliegues, proyectos, dominios y variables de entorno en Vercel usando Vercel CLI. Proporciona patrones modernos y mejores prácticas para workflows de desarrollo y producción.

When to Use This Skill

Use this skill when the user requests:

Primary Use Cases

• "Deploy to Vercel" or "Deploy my app"
• "Set up Vercel project" or "Link to Vercel"
• "Configure custom domain on Vercel"
• "Manage environment variables on Vercel"
• "View Vercel logs" or "Debug deployment"

Secondary Use Cases

• "Promote preview to production"
• "Remove/delete Vercel deployment"
• "Set up CI/CD with Vercel"
• "Switch Vercel team or scope"
• "Check Vercel project status"

Do NOT use when

• Managing environment variables sync (use vercel-env-sync instead)
• Need automated env var validation (use vercel-env-sync)
• Working with Neon database (use neon-database-management)

Prerequisites

1. Vercel CLI Installation

The CLI should be installed globally. Verify installation:

# Check if Vercel CLI is installed
vercel --version

# Expected output: Vercel CLI 37.x.x or higher

If not installed, install globally:

# npm
npm install -g vercel

Alternative: Use npx (no installation needed)

npx vercel --version
npx vercel --help

2. Authentication

Verify authentication status:

vercel whoami

# Output: your-username (success)
# Error: "Error! You must log in first" (needs login)

Login if needed:

# Interactive login (opens browser)
vercel login

# Or use token (CI/CD)
vercel login --token <YOUR_TOKEN>

3. Project Linking

Check if project is linked:

# Should show .vercel/project.json
ls .vercel/

# View linked project
cat .vercel/project.json

Link if needed:

vercel link

Step-by-Step Instructions

Step 1: Environment Verification

Before any Vercel operation, verify the environment:

# Complete verification script
vercel --version && vercel whoami && test -f .vercel/project.json && echo "Ready" || echo "Needs setup"

Success criteria:

• CLI version displayed (37.x.x+)
• Username shown (authenticated)
• .vercel/project.json exists (linked)

Troubleshooting:

• If "command not found": Install CLI (see Prerequisites)
• If "You must log in": Run vercel login
• If "No project linked": Run vercel link

Step 2: Project Management

Initialize New Project

# In project directory (creates .vercel/project.json)
vercel

# Follow prompts:
# - Link to existing project? (Y/n)
# - Which scope? (personal/team)
# - Link to existing project or create new?

Link Existing Project

# Explicit link command
vercel link

# Force relink
vercel link --yes

List Projects

vercel project ls

Switch Team/Scope

# List available teams
vercel teams ls

# Switch to team
vercel switch <team-name>

# Or use --scope flag
vercel --scope <team-name> <command>

Step 3: Deployments

Deploy to Preview (Default)

# Deploy current branch to preview URL
vercel

# Output: https://your-project-xxx.vercel.app

Deploy to Production

vercel --prod

Deploy with Options

# Force rebuild (skip cache)
vercel --force

# Deploy specific directory
vercel ./dist

# With message
vercel --message "Fix: authentication bug"

List Deployments

# Recent deployments
vercel ls

# With metadata
vercel ls --meta

# Filter by app
vercel ls <app-name>

Inspect Deployment

vercel inspect <deployment-url>

# Example
vercel inspect https://my-app-abc123.vercel.app

Promote Preview to Production

vercel promote <deployment-url>

# Example
vercel promote https://my-app-abc123.vercel.app

Remove Deployment

# Remove specific deployment
vercel remove <deployment-url>

# Force without confirmation
vercel remove <deployment-url> --yes

# Remove multiple
vercel remove <url1> <url2>

Step 4: Environment Variables

Note: For advanced env var management (sync, validation, audit), use vercel-env-sync.

List Variables

# All environments
vercel env ls

# Specific environment
vercel env ls production
vercel env ls preview
vercel env ls development

Add Variable

# Interactive (recommended for sensitive values)
vercel env add <NAME>

# Non-interactive (CI/CD)
echo "value" | vercel env add MY_VAR production

# Multiple environments
echo "value" | vercel env add MY_VAR production preview development

# Mark as sensitive
echo "secret" | vercel env add API_SECRET production --sensitive

Update Variable (Modern)

# Update existing variable (Vercel CLI 33+)
echo "new-value" | vercel env update MY_VAR production --yes

# Update with sensitive flag
echo "new-secret" | vercel env update API_SECRET production --sensitive --yes

Remove Variable

vercel env rm MY_VAR production

# Force without confirmation
vercel env rm MY_VAR production --yes

Pull Variables (Local Development)

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

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

# Pull with git branch
vercel env pull .env.preview --environment=preview --git-branch=feature-x

⚠️ IMPORTANT: Add .env*.local to .gitignore

Run Commands with Vercel Env

# Run dev server with Vercel environment
vercel env run -- pnpm dev

# Run with specific environment
vercel env run -e production -- pnpm build

# Run tests with preview env
vercel env run -e preview -- pnpm test

Step 5: Domains

List Domains

vercel domains ls

Add Domain

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

# Add with project
vercel domains add example.com --project=my-project

Verify Domain

vercel domains inspect example.com

# Force re-verification
vercel domains verify example.com

Remove Domain

vercel domains rm example.com

Create Alias (Legacy)

# Assign custom domain to deployment
vercel alias set <deployment-url> example.com

# List aliases
vercel alias ls

# Remove alias
vercel alias rm example.com

Step 6: Logs and Debugging

View Logs

# Production logs
vercel logs --prod

# Specific deployment
vercel logs <deployment-url>

# Follow (real-time)
vercel logs --prod --follow

# Filter by function
vercel logs --prod --function=api/hello

# Filter by status code
vercel logs --prod --status=500

Local Development

# Simulate Vercel environment locally
vercel dev

# With custom port
vercel dev --port 3001

# With specific env file
vercel dev --env .env.local

Local Build

# Build as Vercel would
vercel build

# Production build
vercel build --prod

# Deploy prebuilt
vercel deploy --prebuilt

Advanced Usage

CI/CD Integration

GitHub Actions

# .github/workflows/deploy.yml
name: Deploy to Vercel

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install dependencies
        run: pnpm install

      - name: Pull Vercel Environment
        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}

      - name: Build Project
        run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}

      - name: Deploy to Vercel
        run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

Required GitHub Secrets

VERCEL_TOKEN      # From https://vercel.com/account/tokens
VERCEL_ORG_ID     # From .vercel/project.json
VERCEL_PROJECT_ID # From .vercel/project.json

vercel.json Configuration

Basic Structure

{
  "version": 2,
  "name": "my-project",
  "framework": "nextjs",
  "buildCommand": "pnpm build",
  "devCommand": "pnpm dev",
  "installCommand": "pnpm install"
}

Redirects

{
  "redirects": [
    {
      "source": "/old-path",
      "destination": "/new-path",
      "permanent": true
    },
    {
      "source": "/blog/:slug",
      "destination": "/news/:slug",
      "permanent": false
    }
  ]
}

Rewrites

{
  "rewrites": [
    {
      "source": "/api/:path*",
      "destination": "https://api.external.com/:path*"
    }
  ]
}

Headers

{
  "headers": [
    {
      "source": "/api/:path*",
      "headers": [
        {
          "key": "Access-Control-Allow-Origin",
          "value": "*"
        }
      ]
    }
  ]
}

Examples

Example 1: First-Time Project Setup

User request: "Set up my Next.js project on Vercel"

Actions:

# 1. Verify CLI
vercel --version

# 2. Login (if needed)
vercel login

# 3. Link project
vercel link

# 4. Deploy to preview
vercel

# 5. Deploy to production
vercel --prod

Expected result: Project deployed to Vercel with both preview and production URLs.

Example 2: Deploy with Environment Variables

User request: "Deploy and set up env vars"

Actions:

# 1. Deploy
vercel --prod

# 2. Add environment variables
echo "https://myapp.com" | vercel env add NEXT_PUBLIC_APP_URL production
echo "secret-key" | vercel env add API_SECRET production --sensitive

# 3. Redeploy to apply env vars
vercel --prod

Expected result: App deployed with environment variables configured.

Example 3: Promote Preview to Production

User request: "Make my preview deployment live"

Actions:

# 1. List recent deployments
vercel ls

# 2. Promote specific deployment to production
vercel promote https://my-app-abc123.vercel.app

# Or simply redeploy current to production
vercel --prod

Expected result: Preview deployment now serves production traffic.

Example 4: Debug Failed Deployment

User request: "My deployment failed, help me debug"

Actions:

# 1. Get deployment URL from recent deployments
vercel ls

# 2. View logs
vercel logs <deployment-url>

# 3. Inspect deployment details
vercel inspect <deployment-url>

# 4. Try local build with Vercel env
vercel env pull .env.local
vercel build

Expected result: Root cause identified from logs or build output.

Error Handling

Common Errors

Debugging Tips

# Enable verbose output
vercel --debug <command>

# Check authentication
vercel whoami && vercel teams ls

# Verify project config
cat .vercel/project.json

# Test build locally
vercel build

# Check all env vars
vercel env ls

Best Practices

DO

1. Verify CLI installation before operations
2. Use vercel env run for local development with latest env vars
3. Test with vercel build locally before deploying
4. Use preview deployments for testing before production
5. Add .vercel/ to .gitignore (except project.json if team-shared)
6. Use --yes flag in CI/CD to skip prompts
7. Document env vars in .env.example
8. Use vercel env update instead of rm+add pattern

DON'T

1. Don't commit secrets in vercel.json
2. Don't share VERCEL_TOKEN publicly
3. Don't deploy directly to production without testing
4. Don't use deprecated vercel secrets (use vercel env)
5. Don't ignore failed builds - check logs immediately

Quick Reference

Essential Commands

# Verify setup
vercel --version && vercel whoami

# Deploy
vercel              # Preview
vercel --prod       # Production

# Environment
vercel env ls                              # List all vars
vercel env add NAME production             # Add var
vercel env update NAME production --yes    # Update var
vercel env pull                            # Pull to .env.local
vercel env run -- pnpm dev                 # Run with Vercel env

# Logs
vercel logs --prod          # Production logs
vercel logs --prod --follow # Real-time logs

# Domains
vercel domains ls                    # List domains
vercel domains add example.com       # Add domain
vercel alias set <url> example.com   # Create alias

# Project
vercel link                 # Link project
vercel inspect              # Inspect current deployment
vercel ls                   # List deployments
vercel remove <url>         # Remove deployment

NPM Scripts

{
  "scripts": {
    "deploy": "vercel",
    "deploy:prod": "vercel --prod",
    "env:pull": "vercel env pull .env.local",
    "env:ls": "vercel env ls",
    "logs": "vercel logs --prod",
    "vercel:build": "vercel build",
    "vercel:dev": "vercel dev"
  }
}

Related Skills

• vercel-env-sync - Advanced environment variable synchronization
• neon-database-management - Neon database integration with Vercel
• nextjs16-proxy-middleware - Middleware configuration

Resources

• Vercel CLI Documentation
• Environment Variables
• Deploying with Git
• Vercel REST API
• Agent Skills Standard

Last Updated: January 31, 2026
Version: 3.0
Compatibility: Vercel CLI 37.0+, Node.js 18+