Vercel CLI Deep Dive

Why Use the Vercel CLI?

While the Vercel dashboard is great, the CLI gives you:

• Local development with production environment variables
• Manual deployments without Git commits
• Programmatic access for scripts and CI/CD
• Quick iteration without leaving the terminal

Installation

Authentication

Login

bash
Copy
# Opens browser for authentication
vercel login

# Login with specific email
vercel login [email protected]

# Login with GitHub
vercel login --github

# Login with GitLab
vercel login --gitlab

Logout

bash
Copy
vercel logout

Check Current User

bash
Copy
vercel whoami
# Output: your-username

Project Setup

Link an Existing Project

bash
Copy
cd /path/to/your/project

# Link to existing Vercel project
vercel link

# Output:
# ? Set up "~/my-app"? [Y/n] y
# ? Which scope should contain your project? Your Name
# ? Link to existing project? [y/N] y
# ? What's the name of your existing project? my-app
# ✅ Linked to my-app

Create New Project

bash
Copy
cd /path/to/your/project

# Deploy and create new project
vercel

# Follow prompts to configure

Project Configuration File

After linking, Vercel creates .vercel/project.json:

json
Copy
{
  "projectId": "prj_xxxxxxxxxxxxxxxxxxxx",
  "orgId": "team_xxxxxxxxxxxxxxxxxxxx"
}

Deployment Commands

Preview Deployment

bash
Copy
# Deploy to preview (default)
vercel

# Same as
vercel deploy

Preview deployments:

• Get a unique URL
• Don't affect production
• Great for testing changes

Production Deployment

bash
Copy
# Deploy to production
vercel --prod

# Same as
vercel deploy --prod

Deploy with Options

bash
Copy
# Deploy without prompts (CI/CD)
vercel --yes

# Deploy specific directory
vercel ./dist

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

# Deploy and wait for build to complete
vercel --wait

# Set build environment variables
vercel --build-env API_KEY=secret

# Set runtime environment variables
vercel --env DATABASE_URL=postgresql://...

Environment Variables

List Variables

bash
Copy
# List all environment variables
vercel env ls

# Output:
# Environment Variables for my-app
# ┌──────────────┬─────────────┬─────────────────────┐
# │ Name         │ Value       │ Environments        │
# ├──────────────┼─────────────┼─────────────────────┤
# │ DATABASE_URL │ ●●●●●●●●●●● │ Production, Preview │
# │ API_KEY      │ ●●●●●●●●●●● │ Production          │
# └──────────────┴─────────────┴─────────────────────┘

Add Variables

bash
Copy
# Interactive add
vercel env add MY_VARIABLE

# Select environments when prompted:
# ? Which Environments? (select multiple)
# ◉ Production
# ◉ Preview
# ◯ Development
# ? What's the value of MY_VARIABLE? my-secret-value

# Add with specific environment
vercel env add DATABASE_URL production

Remove Variables

bash
Copy
# Remove from all environments
vercel env rm MY_VARIABLE

# Remove from specific environment
vercel env rm MY_VARIABLE production

Pull Variables to Local

bash
Copy
# Pull production env vars to .env.local
vercel env pull

# Pull to specific file
vercel env pull .env.development.local

# Pull from specific environment
vercel env pull --environment=preview

This is incredibly useful for local development with production-like settings.

Local Development

Start Development Server

bash
Copy
# Start local dev with Vercel features
vercel dev

# Start on specific port
vercel dev --listen 3001

# Use specific framework
vercel dev --framework nextjs

vercel dev gives you:

• Serverless function emulation
• Edge function support
• Environment variables from Vercel
• Rewrites and redirects from vercel.json

When to Use vercel dev vs npm run dev

Domain Management

List Domains

bash
Copy
vercel domains ls

# Output:
# Domains for my-app
# ┌─────────────────────┬────────────┬─────────────┐
# │ Domain              │ Status     │ Added       │
# ├─────────────────────┼────────────┼─────────────┤
# │ myapp.vercel.app    │ Valid      │ 2 days ago  │
# │ example.com         │ Valid      │ 1 day ago   │
# └─────────────────────┴────────────┴─────────────┘

Add Domain

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

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

Remove Domain

bash
Copy
vercel domains rm example.com

Check Domain Status

bash
Copy
vercel domains inspect example.com

# Shows DNS configuration status and SSL certificate

Logs and Monitoring

View Deployment Logs

bash
Copy
# View logs for latest deployment
vercel logs

# Follow logs in real-time
vercel logs --follow

# View logs for specific deployment
vercel logs https://my-app-abc123.vercel.app

# Filter by output type
vercel logs --output=all    # All output
vercel logs --output=error  # Errors only

View Function Logs

bash
Copy
# View serverless function logs
vercel logs --since=1h

# View specific function
vercel logs /api/users

Aliases and Promotions

Create Alias

bash
Copy
# Alias a deployment to a custom URL
vercel alias https://my-app-abc123.vercel.app my-alias.vercel.app

# Alias to production domain
vercel alias https://my-app-abc123.vercel.app example.com

Promote Deployment

bash
Copy
# Promote a preview deployment to production
vercel promote https://my-app-abc123.vercel.app

Secrets (Legacy)

bash
Copy
# Old method (deprecated)
vercel secrets add my-secret value

# New method (recommended)
vercel env add MY_SECRET

Useful Commands Reference

Project Commands

bash
Copy
vercel                    # Deploy to preview
vercel --prod             # Deploy to production
vercel link               # Link to Vercel project
vercel unlink             # Unlink current directory
vercel inspect <url>      # Show deployment info
vercel remove <name>      # Remove project/deployment

Environment Commands

bash
Copy
vercel env ls             # List environment variables
vercel env add <name>     # Add variable
vercel env rm <name>      # Remove variable
vercel env pull           # Pull to local .env

Domain Commands

bash
Copy
vercel domains ls         # List domains
vercel domains add <dom>  # Add domain
vercel domains rm <dom>   # Remove domain
vercel domains inspect    # Check domain status

Other Commands

bash
Copy
vercel logs               # View logs
vercel logs --follow      # Stream logs
vercel dev                # Local development
vercel whoami             # Current user
vercel switch             # Switch team/scope
vercel teams ls           # List teams

CI/CD Integration

Using in GitHub Actions

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

on:
  push:
    branches: [main]

env:
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

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

      - name: Install Vercel CLI
        run: npm install -g vercel

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

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

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

Getting Required Secrets

1. VERCEL_TOKEN: Account Settings → Tokens → Create
2. VERCEL_ORG_ID: vercel link then check .vercel/project.json
3. VERCEL_PROJECT_ID: Same as above

Troubleshooting

"Project not found"

bash
Copy
# Re-link the project
vercel link

"Permission denied"

bash
Copy
# Check you're in the right team
vercel switch

# Re-authenticate
vercel logout
vercel login

"Build failed"

bash
Copy
# Test build locally first
npm run build

# Check build logs
vercel logs --output=error