Vercel CLI

Vercel CLI cheatsheet — deploy web projects from terminal. vercel deploy, vercel --prod, vercel env add, vercel logs, vercel domains. CI/CD and preview deployments covered.

5 min read

What it is

The Vercel CLI is a command-line interface for deploying and managing web projects on Vercel. You reach for it when you want to deploy a new project, update an existing one, or manage your Vercel deployments from your local machine.

Installation

npm/yarn:

npm install -g vercel
# or
yarn global add vercel

Homebrew (macOS):

brew install vercel

Windows: Download the appropriate installer from the Vercel CLI releases page on GitHub.

Core Concepts

Projects: A directory containing your web application code and configuration files.
Deployments: A specific version of your project deployed to Vercel. Each deployment has a unique URL.
Aliases: Custom domains or subdomains that point to a specific deployment.
Environments: Variables (like API keys or database URLs) that can be set for different deployment environments (e.g., production, preview).

Commands / Usage

Project Setup & Deployment

vercel init: Initializes a new Vercel project in the current directory.
```
vercel init my-nextjs-app
```
(Prompts to choose a framework and template)
vercel: Deploys the current directory to Vercel. If it’s the first deployment, it will prompt for project linking.
```
vercel
```
(Deploys to a preview environment by default)
vercel --prod: Deploys the current directory to the production environment.
```
vercel --prod
```
vercel --scope <scope-name>: Deploys to a specific Vercel scope (team or personal account).
```
vercel --scope acme-corp
```
vercel --name <deployment-name>: Assigns a custom name to the deployment.
```
vercel --name initial-release
```
vercel --target production: Explicitly sets the deployment target to production.
```
vercel --target production
```
vercel --target preview: Explicitly sets the deployment target to a preview environment.
```
vercel --target preview
```
vercel --yes: Skips interactive prompts and uses default settings for deployment.
```
vercel --yes --prod
```

Linking & Unlinking Projects

vercel link: Links the current directory to an existing Vercel project.
```
vercel link
```
(Prompts to select a project or create a new one)
vercel link <project-name> --scope <scope-name>: Links the current directory to a specific project within a scope.
```
vercel link my-app --scope acme-corp
```
vercel unlink: Unlinks the current directory from its Vercel project.
```
vercel unlink
```

Managing Deployments

vercel ls: Lists your deployments.
```
vercel ls
```
(Shows production, preview, and development deployments)
vercel ls --scope <scope-name>: Lists deployments for a specific scope.
```
vercel ls --scope acme-corp
```
vercel rm: Removes a deployment.
```
vercel rm my-app-abc123xyz
```
(Prompts to confirm removal of a specific deployment ID)
vercel rm --prod: Removes the production deployment.
```
vercel rm --prod
```
vercel rm --project <project-name>: Removes all deployments for a given project.
```
vercel rm --project my-app
```
vercel logs: Views logs for the latest deployment.
```
vercel logs
```
vercel logs <deployment-id>: Views logs for a specific deployment.
```
vercel logs my-app-abc123xyz
```
vercel --open: Opens the latest deployment in your browser.
```
vercel --open
```
vercel --open --prod: Opens the production deployment in your browser.
```
vercel --open --prod
```

Environment Variables

vercel env add <project-name> <key> <value>: Adds an environment variable for a project.
```
vercel env add my-app API_KEY_12345 abcdefg
```
vercel env add <project-name> <key> --from-file <file-path>: Adds an environment variable from a file.
```
vercel env add my-app SECRET_KEY --from-file ./secrets/key.txt
```
vercel env pull: Pulls environment variables from Vercel to a .env.local file.
```
vercel env pull .env.local
```
vercel env pull --environment production: Pulls production environment variables.
```
vercel env pull --environment production .env.production
```
vercel env rm <project-name> <key>: Removes an environment variable for a project.
```
vercel env rm my-app API_KEY
```

Aliases & Domains

vercel alias add <deployment-id> <alias>: Adds an alias (domain/subdomain) to a deployment.
```
vercel alias add my-app-abc123xyz staging.my-app.com
```
vercel alias ls: Lists all aliases for your account/scope.
```
vercel alias ls
```
vercel alias rm <alias>: Removes an alias.
```
vercel alias rm staging.my-app.com
```

Git Integration

vercel --git-branch <branch-name>: Specifies the Git branch to deploy.
```
vercel --git-branch feature/new-design --prod
```
vercel --git-commit-sha <commit-sha>: Specifies the Git commit SHA to deploy.
```
vercel --git-commit-sha a1b2c3d4e5f67890 --prod
```

Other Useful Commands

vercel status: Shows the status of your linked project’s deployments.
```
vercel status
```
vercel --help: Displays help information for the Vercel CLI.
```
vercel --help
```
vercel --version: Displays the Vercel CLI version.
```
vercel --version
```

Common Patterns

Deploying a Git branch to production:
```
vercel --git-branch main --prod
```

Deploying a specific commit to a preview environment:

vercel --git-commit-sha fedcba9876543210 --target preview

Pulling production environment variables and then deploying:
```
vercel env pull .env.production
vercel --prod
```
Deploying and immediately opening the production URL:
```
vercel --prod --open
```
Removing all deployments for a project (use with caution!):
```
vercel rm --project my-old-project
```

Gotchas

Linking is project-specific: Running vercel link in a subdirectory of a linked project will still link to the same Vercel project. If you need to deploy different parts of a monorepo as separate Vercel projects, you’ll need to manage them from their respective root directories.
--prod flag is crucial for production: Deployments without --prod go to Vercel’s preview environments. Always double-check you’re using --prod when intending a production release.
Environment variable scope: Environment variables added via vercel env add are specific to the project and the selected scope. Ensure you’re adding them to the correct project and scope.
Build output directory: Vercel automatically detects common frameworks (Next.js, Nuxt, etc.). If you have a custom build process or a less common framework, you might need to configure the build output directory in your vercel.json or project settings.
vercel vs vercel --prod: The default vercel command deploys to a preview URL. This is great for testing, but you must use vercel --prod to deploy to your main production domain.