CLI & Config

To allow for interacting with the platform using the terminal or an automated system, Vercel offers a command-line interface called Vercel CLI.

If you'd like to interface with the platform programmatically, take a look at the REST API.

Vercel CLI Reference

Vercel CLI provides a set of commands that allow you to deploy and manage your projects. This page contains a complete list of all Vercel CLI commands available, alongside their optional parameters for additional behavior.

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

npm i -g vercel

All commands and options are listed in the following categories:

Commands

Overview

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.

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

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

• --debug
• --force
• --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 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.

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.

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.

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.

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.

vercel env pull

Using the vercel env command to download Development Environment Variables from the cloud and write to a local .env file.

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] [environment]

Using the vercel env command to add an Environment Variable 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.

Global Options

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

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

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

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:

• --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.

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.

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:

• --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:

• --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:

• --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.

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:

• --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.

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:

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

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:

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

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

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:

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

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:

• --debug
• --global-config
• --help
• --local-config
• --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:

• --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.

Certs

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

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:

• --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.

Billing

The vercel billing command is used to manage payment methods, providing functionality to list, add, and remove them.

Basic Usage

vercel billing ls

Using the vercel billing command to list all the payment methods of the active account.

Extended Usage

vercel billing add

Using the vercel billing add command to interactively add a new credit card.

vercel billing rm [card-id]

Using the vercel billing rm command to remove a credit card by ID.

vercel billing set-default [card-id]

Using the vercel billing set-default command to select which credit card should be default.

Global Options

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

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

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

Alias

Whenever 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 to apply any Custom Domains configured in the Project Settings.

To be more specific, 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 aforementioned sources.

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

Therefore, 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:

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

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

Options

This section contains information about the two types of options available to pass when using Vercel CLI commands, unique and global.

To understand which options can be used with a particular command, take a look at the specific command for more information.

Unique Options

Unique options relate only to a single Vercel CLI command and as such, are documented in full in the command section they relate to.

When using unique options, some of the shorthands may conflict with those of global options, this only occurs when the particular global option is not available for that command.

Global Options

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

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.

Project Configuration

Using a vercel.json configuration file, placed at the root of a project, you can provide a list of options that changes the default behavior of the Vercel platform.

functions

Type: Object of key String and value Object.

Key definition:

A glob pattern that matches the paths of the Serverless Functions you would like to customize (like api/*.js or api/test.js).

Value definition:

• runtime (optional): The npm package name of a Runtime, including its version.
• memory (optional): An integer defining the memory in MB for your Serverless Function (between 128 and 3008, in intervals of 64).
• maxDuration (optional): An integer defining how long your Serverless Function should be allowed to run on every request in seconds (between 1 and the maximum limit of your plan, as mentioned below).
• includeFiles (optional): A glob pattern to match files that should be included in your Serverless Function. If you’re using a Community Runtime, the behavior might vary. Please consult its documentation for more details. (does not apply if Next.js is used)
• excludeFiles (optional): A glob pattern to match files that should be excluded from your Serverless Function. If you’re using a Community Runtime, the behavior might vary. Please consult its documentation for more details. (does not apply if Next.js is used)

Description:

By default, no configuration is needed to deploy Serverless Functions to Vercel.

For all officially supported runtimes, the only requirement is to create an api directory at the root of your project directory, placing your Serverless Functions inside.

The functions property cannot be used in combination with builds. Since the latter is a legacy configuration property, we recommend dropping it in favor of the new one.

When deployed, each Serverless Function receives the following properties:

• Memory: 1024 MB (1 GB)
• Maximum Execution Duration: 5s (Hobby), 15s (Pro), or 30s (Enterprise)

To configure them, you can add the functions property like so:

{
  "functions": {
    "api/test.js": {
      "memory": 3008,
      "maxDuration": 30
    }
  }
}

Both sub properties are optional and need to match the following constraints mentioned at the top of this section.

In order to use a runtime that is not officially supported, you can add a runtime property to the definition:

{
  "functions": {
    "api/test.php": {
      "runtime": "vercel-php@0.1.0"
    }
  }
}

In the example above, the api/test.php Serverless Function does not use one of the officially supported runtimes. In turn, a runtime property was added in order to invoke the vercel-php community runtime.

For more information on Runtimes, see the documentation:

regions

Type: Array of region identifier String.

Valid values: a list of valid region identifiers.

By setting and modifying this value, you can decide the deployment regions of the Serverless Functions that get created as a result of the build steps. The region iad1 is used by default.

This value does not impact static files or edge caches, since deployments always have a CDN layer in front.

The special value all can be used to target all available regions.

{
  "regions": ["iad1", "sfo"]
}

public

Type: Boolean.

Default Value: false.

When set to true, both the source view and logs view will be publicly accessible.

{
  "public": true
}

cleanUrls

Type: Boolean.

Default Value: false.

When set to true, all HTML files and Serverless Functions will have their extension removed. When visiting a path that ends with the extension, a 308 response will redirect the client to the extensionless path.

For example, a static file named about.html will be served when visiting the /about path. Visiting /about.html will redirect to /about.

Similarly, a Serverless Function named api/user.go will be served when visiting /api/user. Visiting /api/user.go will redirect to /api/user.

{
  "cleanUrls": true
}

trailingSlash

Type: Boolean.

Default Value: undefined.

false

When trailingSlash: false, visiting a path that ends with a forward slash will respond with a 308 status code and redirect to the path without the trailing slash.

For example, the /about/ path will redirect to /about.

{
  "trailingSlash": false
}

true

When trailingSlash: true, visiting a path that does not end with a forward slash will respond with a 308 status code and redirect to the path with a trailing slash.

For example, the /about path will redirect to /about/.

However, paths with a file extension will not redirect to a trailing slash.

For example, the /about/styles.css path will not redirect, but the /about/styles path will redirect to /about/styles/.

{
  "trailingSlash": true
}

undefined

When trailingSlash: undefined, visiting a path with or without a trailing slash will not redirect.

For example, both /about and /about/ will serve the same content without redirecting.

This is not recommended because it could lead to search engines indexing two different pages with duplicate content.

Redirects

Redirects allow you to send users to URLs that are different from the ones they originally requested. For example, if you rename existing public routes in your application, adding redirects ensures there are no broken links for your users.

Redirects do not require a Serverless Function and can be directly processed at the Edge across all regions.

Type: Array of redirect Object.

Valid values: a list of redirect definitions.

Limits:

• A maximum of 1,024 redirects in the array.
• A maximum of string length of 4,096 for the source and destination values.

See related Next.js redirects documentation.

Redirect object definition:

• source: A pattern that matches each incoming pathname (excluding querystring).
• destination: A location destination defined as an absolute pathname or external URL.
• permanent: A boolean to toggle between permanent and temporary redirect (default true). When true, the status code is 308. When false the status code is 307.
• has: An optional array of has objects with the type, key and value properties.
  • type: String — must be either header, cookie, host, or query.
  • key: String — the key from the selected type to match against.
  • value: String or not defined — the value to check for, if undefined any value will match. A regex like string can be used to capture a specific part of the value, e.g. if the value first-(?<paramName>.*) is used for first-second then second will be usable in the destination with :paramName.

{
  "redirects": [
    { "source": "/me", "destination": "/profile.html" },
    { "source": "/user", "destination": "/api/user", "permanent": false },
    { "source": "/view-source", "destination": "https://github.com/vercel/vercel" },
    {
      "source": "/:path((?!uk/).*)",
      "has": [
        {
          "type": "header",
          "key": "x-vercel-ip-country",
          "value": "GB"
        }
      ],
      "destination": "/uk/:path*",
      "permanent": false
    }
  ]
}

Example vercel.json that redirects /me to a static file, /user to a Serverless Function, /view-source to an external URL, and UK vistors to the UK localized path.

In some rare cases, you might need to assign a custom status code for older HTTP Clients to properly redirect. In these cases, you can use the statusCode property instead of the permanent property, but not both.

Rewrites

Rewrites allow you to send users to different URLs without modifying the visible URL. This is also known as a URL proxy.

You can also use them to return different responses depending on the headers of the incoming request (such as User-Agent, which contains the type of device and browser that the request originated from).

Rewrites do not require a Serverless Function and can be directly processed at the Edge across all regions.

Type: Array of rewrite Object.

Valid values: a list of rewrite definitions.

Limits:

• A maximum of 1,024 rewrites in the array.
• A maximum of string length of 4,096 for the source and destination values.

Rewrite object definition:

• source: A pattern that matches each incoming pathname (excluding querystring).
• destination: An absolute pathname to an existing resource or an external URL.
• has: An optional array of has objects with the type, key and value properties.
  • type: String — must be either header, cookie, host, or query.
  • key: String — the key from the selected type to match against.
  • value: String or not defined — the value to check for, if undefined any value will match. A regex like string can be used to capture a specific part of the value, e.g. if the value first-(?<paramName>.*) is used for first-second then second will be usable in the destination with :paramName.

{
  "rewrites": [
    { "source": "/about", "destination": "/about-our-company.html" },
    { "source": "/resize/:width/:height", "destination": "/api/sharp" },
    { "source": "/proxy/:match*", "destination": "https://example.com/:match*" },
    {
      "source": "/:path((?!uk/).*)",
      "has": [
        {
          "type": "header",
          "key": "x-vercel-ip-country",
          "value": "GB"
        }
      ],
      "destination": "/uk/:path*"
    }
  ]
}

Example vercel.json that rewrites /about to a static file, /resize/100/50 to /api/sharp?width=100&height=50, /proxy/support to https://example.com/support, and UK vistors to the UK localized path.

Headers

Used to attach headers to HTTP responses from your Deployments.

Headers do not require a Serverless Function and can be directly processed at the Edge across all regions.

Type: Array of header Object.

Valid values: a list of header definitions.

Limits:

• A maximum of 1,024 headers in the array.
• A maximum of string length of 4,096 for the source, key, and value values.

Header object definition:

• source: A pattern that matches each incoming pathname (excluding querystring).
• headers: An array of key/value pairs representing each response header.
• has: An optional array of has objects with the type, key and value properties.
  • type: String — must be either header, cookie, host, or query.
  • key: String — the key from the selected type to match against.
  • value: String or not defined — the value to check for, if undefined any value will match. A regex like string can be used to capture a specific part of the value, e.g. if the value first-(?<paramName>.*) is used for first-second then second will be usable in the destination with :paramName.

This example configures custom response headers for static files, Serverless Functions, and a wildcard that matches all routes.

{
  "headers": [
    {
      "source": "/service-worker.js",
      "headers" : [
        {
          "key" : "Cache-Control",
          "value" : "public, max-age=0, must-revalidate"
        }
      ]
    },
    {
      "source": "/(.*)",
      "headers" : [
        {
          "key" : "X-Content-Type-Options",
          "value" : "nosniff"
        },
        {
          "key" : "X-Frame-Options",
          "value" : "DENY"
        },
        {
          "key" : "X-XSS-Protection",
          "value" : "1; mode=block"
        }
      ]
    },
    {
      "source": "/:path*",
      "has": [
        {
          "type": "query",
          "key": "authorized"
        }
      ],
      "headers": [
        {
          "key": "x-authorized",
          "value": "true"
        }
      ]
    }
  ]
}

name

Type: String.

Valid values: string name for the deployment.

Limits:

• A maximum length of 52 characters
• Only lower case alphanumeric characters or hyphens are allowed
• Cannot begin or end with a hyphen, or contain multiple consecutive hyphens

The prefix for all new deployment instances. The CLI usually generates this field automatically based on the name of the directory. But if you'd like to define it explicitly, this is the way to go.

The defined name is also used to organize the deployment into a project.

{
  "name": "example-app"
}

version

Type: Number.

Valid values: 1, 2.

Specifies the Vercel Platform version the deployment should use.

{
  "version": 2
}

alias

Type: Array or String.

Valid values: domain names (optionally including subdomains) added to the account, or a string for a suffixed URL using .vercel.app or a Custom Deployment Suffix (available on the Enterprise plan).

Limit: A maximum of 64 aliases in the array.

The alias or aliases are applied automatically using Vercel for GitHub, Vercel for GitLab, or Vercel for Bitbucket when merging or pushing to the Production Branch.

You can deploy to the defined aliases using Vercel CLI by setting the production deployment environment target.

{
  "alias": ["my-domain.com", "my-alias"]
}

scope

Type: String.

Valid values: For teams, either an ID or slug. For users, either a email address, username, or ID.

This property determines the scope (Personal Account or Team) under which the project will be deployed by Vercel CLI.

Furthermore, it also affects any other actions that the user takes within the directory that contains this configuration (e.g. listing Environment Variables using vercel secrets ls).

{
  "scope": "my-team"
}

env

Type: Object of String keys and values.

Valid values: environment keys and values.

Environment variables passed to the invoked Serverless Functions.

This example will pass the MY_KEY static env to all Serverless Functions and SECRET resolved from the my-secret-name Secret dynamically.

{
  "env": {
    "MY_KEY": "this is the value",
    "SECRET": "@my-secret-name"
  }
}

build.env

Type: Object of String keys and values inside the build Object.

Valid values: environment keys and values.

Environment variables passed to the Build processes.

The following example will pass the MY_KEY Environment Variable to all Builds and SECRET resolved from the my-secret-name Secret dynamically.

{
  "build": {
    "env": {
      "MY_KEY": "this is the value",
      "SECRET": "@my-secret-name"
    }
  }
}

builds

Type: Array of build Object.

Valid values: a list of build descriptions whose src references valid source files.

Build object definition:

• src (String): A glob expression or pathname. If more than one file is resolved, one build will be created per matched file. It can include * and **.
• use (String): An npm module to be installed by the build process. It can include a semver compatible version (e.g.: @org/proj@1).
• config (Object): Optionally, an object including arbitrary metadata to be passed to the Builder.

The following will include all HTML files as-is (to be served statically), and build all Python files and JS files into Serverless Functions:

{
  "builds": [
    { "src": "*.html", "use": "@vercel/static" },
    { "src": "*.py", "use": "@vercel/python" },
    { "src": "*.js", "use": "@vercel/node" }
  ]
}

routes

Type: Array of route Object.

Valid values: a list of route definitions.

Route object definition:

• src: A PCRE-compatible regular expression that matches each incoming pathname (excluding querystring).
• methods: A set of HTTP method types. If no method is provided, requests with any HTTP method will be a candidate for the route.
• dest: A destination pathname or full URL, including querystring, with the ability to embed capture groups as $1, $2…
• headers: A set of headers to apply for responses.
• status: A status code to respond with. Can be used in tandem with Location: header to implement redirects.
• continue: A boolean to change matching behavior. If true, routing will continue even when the src is matched.

Routes are processed in the order they are defined in the array, so wildcard/catch-all patterns should usually be last.

This example configures custom routes that map to static files and Serverless Functions:

{
  "routes": [
    { "src": "/redirect", "status": 308, "headers": { "Location": "https://example.com/" } },
    { "src": "/custom-page", "headers": {"cache-control": "s-maxage=1000"}, "dest": "/index.html" },
    { "src": "/api", "dest": "/my-api.js" },
    { "src": "/users", "methods": ["POST"], "dest": "/users-api.js" },
    { "src": "/users/(?<id>[^/]*)", "dest": "/users-api.js?id=$id" },
    { "src": "/legacy", "status": 404},
    { "src": "/.*", "dest": "https://my-old-site.com"}
  ]
}

Upgrading

In most cases, you can upgrade legacy routes usage to the newer rewrites, redirects, headers, cleanUrls or trailingSlash properties.

Here are some examples that show how to upgrade legacy routes to the equivalent new property.

Route Parameters

With routes, you use a PCRE Regex named group to match the ID and then pass that parameter in the query string.

{
  "routes": [{ "src": "/product/(?<id>[^/]+)", "dest": "/api/product?id=$id" }]
}

Match URL like /product/532004 and proxy to /api/product?id=532004.

With rewrites, named parameters are automatically passed in the query string.

{
  "rewrites": [{ "source": "/product/:id", "destination": "/api/product" }]
}

Equivalent to the legacy routes usage above, but instead using rewrites.

Redirects

With routes, you specify the status code to use a 307 Temporary Redirect. Also, this redirect needs to be defined before other routes.

{
  "routes": [
    {
      "src": "/posts/(.*)",
      "headers": { "Location": "/blog/$1" },
      "status": 307
    }
  ]
}

Redirecting from all paths in the posts directory but keeping the path in the new location.

With redirects, you disable the permanent property to use a 307 Temporary Redirect. Also, redirects are always processed before rewrites.

{
  "redirects": [
    {
      "source": "/posts/:id",
      "destination": "/blog/:id",
      "permanent": false
    }
  ]
}

Equivalent to the legacy routes usage above, but instead using redirects.

SPA Fallback

With routes, you use "handle": "filesystem" to give precedence to the filesytem and exit early if the requested path matched a file.

{
  "routes": [
    { "handle": "filesystem" },
    { "src": "/(.*)", "dest": "/index.html" }
  ]
}

Fallback to index.html after checking the filesystem for exact matches.

With rewrites, the filesystem check is the default behavior. If you want to change the name of files at the filesystem level, file renames can be performed during the Build Step, but not with rewrites.

{
  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}

Equivalent to the legacy routes usage above, but instead using rewrites.

Headers

With routes, you use "continue": true to prevent stopping at the first match.

{
  "routes": [
    {
      "src": "/favicon.ico",
      "headers": { "Cache-Control": "public, max-age=3600" },
      "continue": true
    },
    {
      "src": "/assets/(.*)",
      "headers": { "Cache-Control": "public, max-age=31556952, immutable" },
      "continue": true
    }
  ]
}

Add Cache-Control headers to favicon and other static assets.

With headers, this is no longer necessary since that is the default behavior.

{
  "headers": [
    {
      "source": "/favicon.ico",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=3600"
        }
      ]
    },
    {
      "source": "/assets/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=31556952, immutable"
        }
      ]
    }
  ]
}

Equivalent to the legacy routes usage above, but instead using headers.

Pattern Matching

With routes, you need to escape a dot with two backslashes, otherwise it would match any character PCRE Regex.

{
  "routes": [{ "src": "/atom\\.xml", "dest": "/api/rss" }]
}

Match the literal /atom.xml and proxy to /api/rss to dynamically generate RSS.

With rewrites, the . is not a special character so it does not need to be escaped.

{
  "rewrites": [{ "source": "/atom.xml", "destination": "/api/rss" }]
}

Equivalent to the legacy routes usage above, but instead using rewrites.

Negative Lookahead

With routes, you use PCRE Regex negative lookahead.

{
  "routes": [{ "src": "/(?!maintenance)", "dest": "/maintenance" }]
}

Proxy all requests to the /maintenance except for /maintenance directly to avoid infinite loop.

With rewrites, the Regex needs to be wrapped.

{
  "rewrites": [
    { "source": "/((?!maintenance).*)", "destination": "/maintenance" }
  ]
}

Equivalent to the legacy routes usage above, but instead using rewrites.

Case Sensitivity

With routes, the src property is case-insensitive leading to duplicate content, where multiple request paths with difference cases serve the same page.

With rewrites / redirects / headers, the source property is case-sensitive so you don't accidentally create duplicate content.

Git Configuration

The following configuration options can be used through a vercel.json file like the options above.

github.enabled

Type: Boolean.

When set to false, Vercel for GitHub will not deploy the given project regardless of the GitHub app being installed.

{
  "github": {
    "enabled": false
  }
}

github.autoAlias

Type: Boolean.

When set to false, Vercel for GitHub will not apply the alias upon merge.

{
  "alias": ["example.com"],
  "github": {
    "autoAlias": false
  }
}

github.silent

Type: Boolean.

When set to true, Vercel for GitHub will stop commenting on pull requests and commits.

{
  "github": {
    "silent": true
  }
}

github.autoJobCancelation

Type: Boolean.

When set to false, Vercel for GitHub will always build pushes in sequence without cancelling a build for the most recent commit.

{
  "github": {
    "autoJobCancelation": false
  }
}

Global Configuration

Using the following files and configuration options, you can configure Vercel CLI under your system user.

There are two global configuration files: config.json and auth.json. These files are stored in the com.vercel.cli directory inside XDG_DATA_HOME, which defaults to:

• Linux: ~/.local/share/com.vercel.cli
• macOS: ~/Library/Application Support/com.vercel.cli
• Windows: %APPDATA%\Roaming\xdg.data\com.vercel.cli

config.json

This file is used for global configuration of Vercel deployments. Vercel CLI uses this file as a way to co-ordinate how deployments should be treated, consistently.

The first option is a single _ that gives a description to the file, if a user should find themselves looking through it without context.

The following options are all of the options that can be used by users to configure their Vercel deployments globally on their system for that user profile:

currentTeam

Type: String.

Valid values: A team ID.

This option tells Vercel CLI which context is currently active. If this property exists and contains a team ID, that team is used as the scope for deployments, otherwise if this property does not exist, the user's personal account is used.

{
  "currentTeam": "team_ofwUZockJlL53hINUGCc1ONW"
}

api

Type: String.

Valid values: An API Origin URL.

This option selects which API Origin Vercel CLI should use when performing an action requiring the API.

{
  "api": "https://api-sfo1.vercel.com"
}

collectMetrics

Type: Boolean.

Valid values: true (default), false.

This option defines whether Vercel CLI should collect anonymous metrics about which commands are invoked the most, how long they take to run, and which errors customers are running into.

{
  "collectMetrics": true
}

auth.json

This file should not be edited manually. It exists to contain the authentication information for the Vercel clients.

In the case that you are uploading your global configuration setup to a potentially insecure destination, we highly recommend ensuring that this file will not be uploaded, as it allows an attacker to gain access to your provider accounts.