CLI

Vercel gives you multiple ways to interact with and configure your projects. With the command-line interface (CLI) you can interact with the Vercel platform using a terminal, or through an automated system, enabling you to retrieve logs, manage certificates, replicate your deployment environment locally, manage Domain Name System (DNS) records, and more.

This page contains a complete list of all Vercel CLI commands available, alongside their optional parameters for additional behavior, as well as a complete list of configuration options to configure your project through vercel.json.

If you'd like to interface with the platform programmatically, check out the REST API documentation.

Installing the CLI

To download and install Vercel CLI, run the following command:

npm i -g vercel

All commands and options are listed in the following categories:

The vercel command is used to deploy projects and can be used from either the root of the project directory or by providing a path to it.

Basic usage

vercel

Using the vercel command from the root of a project directory.

Extended usage

vercel [path-to-project]

Using the vercel command and supplying a path to the root directory of the project.

vercel deploy --prebuilt

Using the vercel command to deploy a prebuilt project, typically with vercel build. See vercel build and Build Output API for more details.

Standard output usage

vercel > deployment-url.txt

Using the vercel command to deploy and write stdout to a text file. When deploying, stdout is always the Deployment URL.

Project linking

When running vercel in a directory for the first time, Vercel CLI needs to know which scope and Project you want to deploy your directory to. You can choose to either link an existing project or to create a new one.

Linking an existing project when running Vercel CLI in a new directory.

Once set up, a new .vercel directory will be added to your directory. The .vercel directory contains both the organization and project id of your project. If you want unlink your directory, you can remove the .vercel directory.

You can use the --confirm option to skip these questions.

Framework detection

When you create a new project, Vercel CLI will automatically detect the framework you are using and offer default project settings accordingly.

vercel
? Set up and deploy “~/web/my-new-project”? [Y/n] y
? Which scope do you want to deploy to? My Awesome Team
? Link to existing project? [y/N] n
? What’s your project’s name? my-new-project
? In which directory is your code located? my-new-project/
Auto-detected project settings (Next.js):
- Build Command: `next build` or `build` from `package.json`
- Output Directory: Next.js default
- Development Command: next dev --port $PORT
? Want to override the settings? [y/N]

Creating a new project with the vercel command.

When creating a new project, you will be provided with default Build Command, Output Directory, and Development Command options.

You can continue with the default project settings or overwrite them. You can also edit your project settings later in your project dashboard.

Global options

Global options are commonly available to use with multiple Vercel CLI commands.

Current Working Directory

The --cwd option can be used to provide a working directory (that can be different from the current directory) when running Vercel CLI commands.

This option can be a relative or absolute path.

Usage Example

vercel --cwd ~/path-to/project

Using the vercel command with the --cwd option.

Debug

The --debug option, shorthand -d, can be used to provide a more verbose output when running Vercel CLI commands.

Usage example

vercel --debug

Using the vercel command with the --debug option.

Force

The --force option, shorthand -f, is used to skip the build cache.

The option can also be used with vercel init to forcibly replace an existing local directory.

Usage example

vercel --force

Using the vercel command with the --force option.

vercel init gatsby my-project-directory --force

Using the vercel init command with the --force option.

Global config

The --global-config option, shorthand -Q, can be used set the path to the global /.vercel directory.

Usage example

vercel --global-config /path-to/.vercel

Using the vercel command with the --global-config option.

Help

The --help option, shorthand -h, can be used to display more information about Vercel CLI commands.

Usage example

vercel --help

Using the vercel command with the --help option.

vercel secrets --help

Using the vercel secrets command with the --help option.

Local config

The --local-config option, shorthand -A, can be used set the path to a local vercel.json file.

Usage example

vercel --local-config /path-to/vercel.json

Using the vercel command with the --local-config option.

Scope

The --scope option, shorthand -S, can be used to execute Vercel CLI commands from a different team or user account than is currently active.

Usage example

vercel --scope my-team-slug

Using the vercel command with the --scope option.

Token

The --token option, shorthand -t, can be used to execute Vercel CLI commands with an authorization token.

Usage example

vercel --token iZJb2oftmY4ab12HBzyBXMkp

Using the vercel command with the --token option.

Unique options

These are options that only apply to the vercel command, therefore, more information is provided.

Build env

The --build-env option, shorthand -b, can be used to provide environment variables to the build step.

Usage example

vercel --build-env KEY1=value1 --build-env KEY2=value2

Using the vercel command with the --build-env option.

Confirm

The --confirm option can be used to skip questions you are asked when setting up a new project. The questions will be answered with the provided defaults, inferred from vercel.json and the folder name.

Usage example

vercel --confirm

Using the vercel command with the --confirm option.

Env

The --env option, shorthand -e, can be used to provide Environment Variables at Runtime.

Usage example

vercel --env KEY1=value1 --env KEY2=value2

Using the vercel command with the --env option.

Name

The --name option, shorthand -n, can be used to provide a project name for a deployment.

Usage example

vercel --name foo

Using the vercel command with the --name option.

No clipboard

The --no-clipboard option, shorthand -C, can be used to prevent Vercel CLI from copying the deployment URL to the clipboard.

Usage example

vercel --no-clipboard

Using the vercel command with the --no-clipboard option.

Prod

The --prod option can be used to create a deployment for a production domain specified in the project dashboard.

Usage example

vercel --prod

Using the vercel command with the --prod option.

Public

The --public option can be used to ensures the source code is publicly available at the /_src path.

Usage example

vercel --public

Using the vercel command with the --public option.

Regions

The --regions option can be used to specify which regions the deployments Serverless Functions should run in.

Usage example

vercel --regions sfo1

Using the vercel command with the --regions option.

Version

The --version option can be used to verify the version of Vercel CLI currently being used.

Usage example

vercel --version

Using the vercel command with the --version option.

Commands

alias

When a new Deployment is created (regardless of whether it's created through our Git Integration, Vercel CLI, or the REST API), the platform will automatically try to apply any Custom Domains configured in the Project Settings.

Any Custom Domain that doesn't have a custom Preview Branch configured (there can only be one Production Branch and it's configured separately in the Project Settings) will be applied to Production Deployments created through any of the available sources.

Custom Domains that do have a custom Preview Branch configured, however, only get applied when using the Git Integration.

If you're not using the Git Integration, vercel alias is a great solution if you still need to apply Custom Domains based on Git branches, or other heuristics.

In general, the command allows for assigning Custom Domains to any Deployment.

Usage

vercel alias set [deployment-url] [custom-domain]

Using the vercel alias command to assign a Custom Domain to a Deployment.

vercel alias rm [custom-domain]

Using the vercel alias command to remove a Custom Domain from a Deployment.

vercel alias ls

Using the vercel alias command to list Custom Domains that were assigned to Deployments.

Global Options

The following global options can be passed when using the vercel secrets command:

• --cwd
• --debug
• --global-config
• --help
• --local-config
• --scope
• --token

For more information on global options and their usage, refer to the options section.

bisect

The vercel bisect command can be used to perform a "binary search" upon a set of Deployments in a Project for the purpose of determining when an issue was introduced.

Basic Usage

vercel bisect

Using the vercel bisect command will initiate an interactive prompt where you specify a good deployment, followed by a bad deployment and step through the deployments in between to find the first bad deployment.

Global Options

The following global options can be passed when using the vercel bisect command:

• --cwd
• --debug
• --global-config
• --help
• --token

For more information on global options and their usage, refer to the options section.

Unique Options

These are options that only apply to the vercel bisect command, therefore, more information is provided.

Good

The --good option, shorthand -g, can be used to specify the initial "good" deployment from the command line. When this option is present, the prompt will be skipped at the beginning of the bisect session. A production alias URL may be specified for convenience.

Usage Example

vercel bisect --good https://example.com

Using the vercel bisect command with the --good option.

Bad

The --bad option, shorthand -b, can be used to specify the "bad" deployment from the command line. When this option is present, the prompt will be skipped at the beginning of the bisect session. A production alias URL may be specified for convenience.

Usage Example

vercel bisect --bad https://example-s93n1nfa.vercel.app

Using the vercel bisect command with the --bad option.

Path

The --path option, shorthand -p, can be used to specify a subpath of the deployment where the issue occurs. The subpath will be appended to each URL during the bisect session.

Usage Example

vercel bisect --path /blog/first-post

Using the vercel bisect command with the --path option.

Open

The --open option, shorthand -o, will attempt to automatically open each deployment URL in your browser window for convenience.

Usage Example

vercel bisect --open

Using the vercel bisect command with the --open option.

Run

The --run option, shorthand -r, provides the ability for the bisect session to be automated using a shell script or command that will be invoked for each deployment URL. The shell script can run an automated test (for example, using the curl command to check the exit code) which the bisect command will use to determine whether each URL is good (exit code 0), bad (exit code non-0), or should be skipped (exit code 125).

Usage Example

vercel bisect --run ./test.sh

Using the vercel bisect command with the --run option.

certs

The vercel certs command is used to manage certificates for domains, providing functionality to list, issue, and remove them. Vercel manages certificates for domains automatically.

Basic Usage

vercel certs ls

Using the vercel certs command to list all certificates under an account.

Extended Usage

vercel certs issue [domain1, domain2, domain3]

Using the vercel certs command to issue certificates for multiple domains.

vercel certs rm [certificate-id]

Using the vercel certs command to remove a certificate by ID.

Global Options

The following global options can be passed when using the vercel certs command:

• --cwd
• --debug
• --force
• --global-config
• --help
• --local-config
• --scope
• --token

For more information on global options and their usage, refer to the options section.

Unique Options

These are options that only apply to the vercel certs command, therefore, more information is provided.

Challenge Only

The --challenge-only option can be used to only show the challenges needed to issue a certificate.

Usage Example

vercel certs issue foo.com --challenge-only

Using the vercel certs command with the --challenge-only option.

dev

The vercel dev command is used to replicate the Vercel deployment environment locally, allowing you to test your Serverless Functions, without requiring you to deploy each time a change is made.

When to Use This Command

If you're using a framework and your framework's Development Command already provides all the features you need, we recommend against using vercel dev.

In the case of Next.js, for example, the framework's Development Command (next dev) provides native support for Serverless Functions (placed in the pages/api directory), Redirects, Rewrites, Headers and more – so there's no need to use vercel dev. However, you can use vercel env pull, to download the Development Environment Variables defined in your Project Settings.

Frameworks like Gatsby, on the other hand, do not offer a Development Command that supports Serverless Functions, for example. In those cases, vercel dev acts as a helper that provides the necessary features and runs Gatsby's Development Command at the same time. In that case, you wouldn't use vercel env pull because the Development Environment Variables defined in your Project Settings are downloaded into memory.

Basic Usage

vercel dev

Using the vercel dev command from the root of a project directory.

Global Options

The following global options can be passed when using the vercel dev command:

• --debug
• --help

For more information on global options and their usage, refer to the options section.

Unique Options

These are options that only apply to the vercel dev command, therefore, more information is provided.

Listen

The --listen option, shorthand -l, can be used to specify which port vercel dev runs on.

Usage Example

vercel dev --listen 5005

Using the vercel dev command with the --listen option.

dns

The vercel dns command is used to manage DNS record for domains, providing functionality to list, add, remove, and import records.

Basic Usage

vercel dns ls

Using the vercel dns command to list all DNS records under an account.

Extended Usage

vercel dns add [domain] [subdomain] [A || AAAA || ALIAS || CNAME || TXT] [value]

Using the vercel dns command to add an A record for a subdomain.

vercel dns add [domain] '@' MX [record-value] [priority]

Using the vercel dns command to add an MX record for a domain.

vercel dns add [domain] [name] SRV [priority] [weight] [port] [target]

Using the vercel dns command to add an SRV record for a domain.

vercel dns add [domain] [name] CAA '[flags] [tag] "[value]"'

Using the vercel dns command to add a CAA record for a domain.

vercel dns rm [record-id]

Using the vercel dns command to remove a record for a domain.

vercel dns import [domain] [path-to-zonefile]

Using the vercel dns command to import a zonefile for a domain.

Global Options

The following global options can be passed when using the vercel dns command:

• --cwd
• --debug
• --global-config
• --help
• --local-config
• --scope
• --token

For more information on global options and their usage, refer to the options section.

domains

The vercel domains command is used to manage domains under an account, providing functionality to list, inspect, add, remove, purchase, move, transfer-in, and verify domains.

Basic Usage

vercel domains ls

Using the vercel domains command to list all domains under an account.

Extended Usage

vercel domains inspect [domain]

Using the vercel domains command to retrieve information about a specific domain.

vercel domains add [domain] [project]

Using the vercel domains command to add a domain to an account or project.

vercel domains rm [domain]

Using the vercel domains command to remove a domain from an account.

vercel domains buy [domain]

Using the vercel domains command to buy a domain for an account.

vercel domains move [domain] [account-name]

Using the vercel domains command to move a domain to another account.

vercel domains transfer-in [domain]

Using the vercel domains command to transfer in a domain to an account.

Global Options

The following global options can be passed when using the vercel domains command:

• --cwd
• --debug
• --global-config
• --help
• --local-config
• --scope
• --token

For more information on global options and their usage, refer to the options section.

env

The vercel env command is used to manage Environment Variables under a Project, providing functionality to list, add, remove, and pull.

Basic Usage

vercel env ls

Using the vercel env command to list all Environment Variables in a Project.

vercel env add

Using the vercel env command to add an Environment Variable to a Project.

vercel env rm

Using the vercel env command to remove an Environment Variable from a Project.

Extended Usage

vercel env ls [environment]

Using the vercel env command to list Environment Variables for a specific Environment in a Project.

vercel env ls [environment] [gitbranch]

Using the vercel env command to list Environment Variables for a specific Environment and Git branch.

vercel env add [name]

Using the vercel env command to add an Environment Variable to all Environments to a Project.

vercel env add [name] [environment]

Using the vercel env command to add an Environment Variable for a specific Environment to a Project.

vercel env add [name] [environment] < [file]

Using the vercel env command to add an Environment Variable to a Project using a local file's content as the value.

vercel env add [name] [environment] [gitbranch] < [file]

Using the vercel env command to add an Environment Variable with Git branch to a Project using a local file's content as the value.

vercel env rm [name] [environment]

Using the vercel env command to remove an Environment Variable from a Project.

vercel env pull [file]

Using the vercel env command to download Development Environment Variables from the cloud and write to a specific file. This can be useful for local development with frameworks that have local development servers for server-side functions, such as next dev or gatsby dev.

Global Options

The following global options can be passed when using the vercel env command:

• --cwd
• --debug
• --global-config
• --help
• --local-config
• --token

For more information on global options and their usage, refer to the options section.

help

The vercel help command generates a list of all available Vercel CLI commands and options in the terminal. When combined with a second argument - a valid Vercel CLI command - it outputs more detailed information about that command.

Basic Usage

vercel help

Using the vercel help command to generate a list of Vercel CLI commands and options.

Extended Usage

vercel help [command]

Using the vercel help command to generate detailed information about a specific Vercel CLI command.

init

The vercel init command is used to initialize projects locally from the examples found in the Vercel repository.

Basic Usage

vercel init

Using the vercel init command to initialize a project locally.

Extended Usage

vercel init [project-name]

Using the vercel init command to initialize a specific project locally.

vercel init [project-name] [new-project-name]

Using the vercel init command to initialize a specific project locally and rename the directory.

Global Options

The following global options can be passed when using the vercel init command:

• --debug
• --help
• --force

For more information on global options and their usage, refer to the options section.

inspect

The vercel inspect command is used to retrieve information about a deployment referenced either by its unique deployment URL or production domain.

Basic Usage

vercel inspect [unique-deployment-url]

Using the vercel inspect command to retrieve information about a specific deployment.

Extended Usage

vercel inspect [production-deployment-url]

Using the vercel inspect command to retrieve information about a production deployment.

Global Options

The following global options can be passed when using the vercel inspect command:

• --cwd
• --debug
• --global-config
• --help
• --local-config
• --scope
• --token

For more information on global options and their usage, refer to the options section.

link

The vercel link command is used to link your local directory to a Project.

Basic Usage

vercel link

Using the vercel link command to link the current directory to a Project.

Extended Usage

vercel link [path-to-directory]

Using the vercel link command and supplying a path to the local directory of the Project.

Global Options

The following global options can be passed when using the vercel link command:

• --cwd
• --debug
• --global-config
• --help
• --local-config
• --scope
• --token

For more information on global options and their usage, refer to the options section.

Unique Options

These are options that only apply to the vercel link command.

Confirm

The --confirm option can be used to accept the default answers.

Usage Example

vercel link --confirm

Using the vercel link command with the --confirm option.

list

The vercel list command, which can be shortened to vercel ls, is used to provide a list of your deployments along with information about them.

Basic Usage

vercel list

Using the vercel list command to retrieve information about multiple deployments.

Extended Usage

vercel list [project-name]

Using the vercel list command to retrieve information about deployments for a specific project.

vercel list [project-name] [--meta foo=bar]

Using the vercel list command to retrieve information about deployments filtered by metadata.

Global Options

The following global options can be passed when using the vercel list command:

• --cwd
• --debug
• --global-config
• --help
• --local-config
• --scope
• --token

For more information on global options and their usage, refer to the options section.

Unique Options

These are options that only apply to the vercel list command, therefore, more information is provided.

Meta

The --meta option, shorthand -m, can be used to filter results based on project metadata.

Usage Example

vercel list --meta key1=value1 key2=value2

Using the vercel list command with the --meta option.

login

The vercel login command allows you to login to your Vercel account through Vercel CLI.

Basic Usage

vercel login

Using the vercel login command to login to a Vercel account.

Vercel CLI supports the following login methods:

• GitHub OAuth
• GitLab OAuth
• Bitbucket OAuth
• Email confirmation
• SAML Single Sign-On via your Team's identity provider

When no arguments are provided, an interactive prompt will be displayed asking the user which login method should be used.

To skip the interactive prompt, you may also provide your email address, or Team slug (for SAML Single Sign-On), as an argument to vc login.

Usage Examples

vercel login me@example.com

Using the vercel login command with an email address.

vercel login acme

Using the vercel login command with a Team slug for SAML Single Sign-On.

Unique Options

These are options that only apply to the vercel login command.

GitHub

The --github option can be used to initiate GitHub OAuth login:

Usage Example

vercel login --github

Using the vercel login command with the --github option.

GitLab

The --gitlab option can be used to initiate GitLab OAuth login:

Usage Example

vercel login --gitlab

Using the vercel login command with the --gitlab option.

Bitbucket

The --bitbucket option can be used to initiate Bitbucket OAuth login:

Usage Example

vercel login --bitbucket

Using the vercel login command with the --bitbucket option.

Out-of-band Mode

The --oob option can be used to enable to "out-of-band" mode during login, which requires the user to copy the "verification token" from the web browser after an OAuth login, and paste it back into the CLI to complete the login.

In most situations this flag is not necessary, since "out-of-band" mode is automatically enabled when logging in on a remote machine, such as an SSH session or in a Docker container.

Usage Example

vercel login --github --oob

Using the vercel login command with the --oob option.

logout

The vercel logout command allows you to logout of your Vercel account through Vercel CLI.

Basic Usage

vercel logout

Using the vercel logout command to logout of a Vercel account.

logs

The vercel logs command is used to retrieve logs data for a specific deployment.

Basic Usage

vercel logs [deployment-url]

Using the vercel logs command to retrieve logs for a specific deployment.

Global Options

The following global options can be passed when using the vercel logs command:

• --cwd
• --debug
• --global-config
• --help
• --local-config
• --scope
• --token

For more information on global options and their usage, refer to the options section.

Unique Options

These are options that only apply to the vercel logs command, therefore, more information is provided.

All

The --all option, shorthand -a, can be used to receive access logs in addition to the regular logs output.

Usage Example

vercel logs --all

Using the vercel logs command with the --all option.

Follow

The --follow option, shorthand -f, can be used to watch for additional logs output.

Usage Example

vercel logs --follow

Using the vercel logs command with the --follow option.

Number

The --number option, shorthand -n, can be used to specify the number of log lines to output.

Usage Example

vercel logs --number 10

Using the vercel logs command with the --number option.

Output

The --output option, shorthand -o, can be used to specify the format of the logs output, this can be either short (default) or raw.

Usage Example

vercel logs --output raw

Using the vercel logs command with the --output option.

Since

The --since option can be used to return logs only after a specific date, using the ISO 8601 format.

Usage Example

vercel logs --since 2019-09-04T07:05:43+00:00

Using the vercel logs command with the --since option.

Query

The --query option, shorthand -q, can be used to return logs against a search query.

Usage Example

vercel logs --query foo

Using the vercel logs command with the --query option.

Until

The --until option can be used to return logs only up until a specific date, using the ISO 8601 format.

Usage Example

vercel logs --until 2019-09-04T07:05:43+00:00

Using the vercel logs command with the --until option.

pull

The vercel pull command is used to store Environment Variables and Project Settings in a local cache for offline development.

Basic Usage

vercel pull

Using the vercel pull fetches the latest "development" Environment Variables and Project Settings from the cloud.

vercel pull --environment=preview

Using the vercel pull fetches the latest "preview" Environment Variables and Project Settings from the cloud.

vercel pull --environment=production

Using the vercel pull fetches the latest "production" Environment Variables and Project Settings from the cloud.

Global Options

The following global options can be passed when using the vercel pull command:

• --cwd
• --debug
• --global-config
• --help
• --token

For more information on global options and their usage, refer to the options section.

remove

The vercel remove command, which can be shortened to vercel rm, is used to remove deployments either by ID or for a specific project.

Basic Usage

vercel remove [deployment-url]

Using the vercel remove command to remove a deployment from the Vercel platform.

Extended Usage

vercel remove [deployment-url-1 deployment-url-2]

Using the vercel remove command to remove multiple deployments from the Vercel platform.

vercel remove [project-name]

Using the vercel remove command to remove all deployments for a project from the Vercel platform.

Global Options

The following global options can be passed when using the vercel remove command:

• --cwd
• --debug
• --global-config
• --help
• --local-config
• --scope
• --token

For more information on global options and their usage, refer to the options section.

Unique Options

These are options that only apply to the vercel remove command, therefore, more information is provided.

Safe

The --safe option, shorthand -s, can be used to skip the removal of deployments with an active preview URL or production domain when a project is provided as the parameter.

Usage Example

vercel remove my-project --safe

Using the vercel remove command with the --safe option.

Yes

The --yes option, shorthand -y, can be used to skip the confirmation step for a deployment or project removal.

Usage Example

vercel remove my-deployment.com --yes

Using the vercel remove command with the --yes option.

secrets

The vercel secrets command is used to manage Secrets used in Environment Variables under an account, providing functionality to list, add, rename, and remove Secrets.

Basic Usage

vercel secrets list

Using the vercel secrets command to list all Secrets under an account.

Extended Usage

vercel secrets add [secret-name] [secret-value]

Using the vercel secrets command to add a Secret to an account.

vercel secrets rename [old-name] [new-name]

Using the vercel secrets command to rename a Secret under an account.

vercel secrets remove [secret-name]

Using the vercel secrets command to remove a Secret from an account.

Global Options

The following global options can be passed when using the vercel secrets command:

• --cwd
• --debug
• --global-config
• --help
• --local-config
• --scope
• --token

For more information on global options and their usage, refer to the options section.

switch

The vercel switch command is used to switch to a different team scope when logged in with Vercel CLI. You can choose to select a team from a list of all those you are part of or specify a team when entering the command.

Basic Usage

vercel switch

Using the vercel switch command to change team scope with Vercel CLI.

Extended Usage

vercel switch [team-name]

Using the vercel switch command to change to a specific team scope with Vercel CLI.

Global Options

The following global options can be passed when using the vercel switch command:

• --debug
• --help

For more information on global options and their usage, refer to the options section.

teams

The vercel teams command is used to manage Teams under an account, providing functionality to list, add, and invite new Team Members.

Basic Usage

vercel teams list

Using the vercel teams command to list all teams under an account.

Extended Usage

vercel teams add

Using the vercel teams command to create a new team.

vercel teams invite [email]

Using the vercel teams command to invite a new Team Member.

Global Options

The following global options can be passed when using the vercel teams command:

• --cwd
• --debug
• --global-config
• --help
• --local-config

For more information on global options and their usage, refer to the options section.

whoami

The vercel whoami command is used to show the username of the user currently logged into Vercel CLI.

Basic Usage

vercel whoami

Using the vercel whoami command to view the username of the user currently logged into Vercel CLI.

Global Options

The following global options can be passed when using the vercel whoami command:

• --cwd
• --debug
• --global-config
• --help
• --local-config
• --token

For more information on global options and their usage, refer to the options section.