vercel env

The vercel env command is used to manage Environment Variables of a Project, providing functionality to list, add, remove, export, and run commands with environment variables.

To leverage environment variables in local tools (like next dev or gatsby dev) that want them in a file (like .env), run vercel env pull <file>. This will export your Project's environment variables to that file. After updating environment variables on Vercel (through the dashboard, vercel env add, or vercel env rm), you will have to run vercel env pull <file> again to get the updated values. When the target file already exists, vercel env pull merges the pulled values into it instead of discarding local-only entries. See the pull merge behavior for details.

To run a command with environment variables without writing them to a file, use vercel env run -- <command>. This fetches the environment variables directly from your linked Vercel project and passes them to the specified command.

Exporting Development Environment Variables

Some frameworks make use of environment variables during local development through CLI commands like next dev or gatsby dev. The vercel env pull sub-command will export development environment variables to a local .env file or a different file of your choice.

terminal

vercel env pull [file]

To override environment variable values temporarily, use:

terminal

MY_ENV_VAR="temporary value" next dev

How `vercel env pull` merges into an existing file

When the target file already exists, vercel env pull merges the pulled values into it rather than overwriting the whole file:

Variables defined only in your local file, and not present in the pulled environment, are kept. The CLI logs Kept <KEYS> (defined locally, not found in the <environment> Environment).
VERCEL_OIDC_TOKEN is never preserved from your local file. It is always refreshed from Vercel. The Vercel-managed analytics variables VERCEL_ANALYTICS_ID, VERCEL_SPEED_INSIGHTS_ID, and VERCEL_WEB_ANALYTICS_ID are also never preserved as local-only entries.
For Secret variables whose values cannot be read from Vercel, the CLI keeps the real value already in your local file. If your local file has no real value for that key, the CLI writes a placeholder for you to replace with a local-only value.

If you are using vercel build or vercel dev, you should use vercel pull instead. Those commands operate on a local copy of environment variables and Project settings that are saved under .vercel/, which vercel pull provides.

Usage

terminal

vercel env ls

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

terminal

vercel env add

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

terminal

vercel env rm

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

Extended Usage

terminal

vercel env ls [environment]

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

terminal

vercel env ls [environment] [gitbranch]

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

terminal

vercel env add [name]

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

terminal

vercel env add [name] [environment]

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

terminal

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

Using the vercel env command to add an Environment Variable to a specific Git branch.

terminal

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

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

terminal

echo [value] | vercel env add [name] [environment]

Using the echo command to generate the value of the Environment Variable and piping that value into the vercel env add command. Warning: this will save the value in bash history, so this is not recommended for secrets.

terminal

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

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

terminal

vercel env rm [name] [environment]

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

Updating Environment Variables

The vercel env update sub-command updates the value of an existing environment variable.

terminal

vercel env update [name]

Using vercel env update to update an Environment Variable across all Environments.

terminal

vercel env update [name] [environment]

Using vercel env update to update an Environment Variable for a specific Environment.

terminal

vercel env update [name] [environment] [gitbranch]

Using vercel env update to update an Environment Variable for a specific Environment and Git branch.

terminal

cat ~/.npmrc | vercel env update NPM_RC preview

Update an Environment Variable value from stdin.

terminal

vercel env pull [file]

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

terminal

vercel env pull --environment=preview

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

terminal

vercel env pull --environment=preview --git-branch=feature-branch

Using the vercel env command to download "feature-branch" Environment Variables from the cloud and write to the .env.local file.

Running Commands with Environment Variables

The vercel env run sub-command runs any command with environment variables from your linked Vercel project, without writing them to a file. This is useful when you want to avoid storing secrets on disk or need a quick way to test with production-like configuration.

terminal

vercel env run -- <command>

Using vercel env run to run a command with development Environment Variables from your Vercel Project.

terminal

vercel env run -- next dev

Run the Next.js development server with development Environment Variables.

terminal

vercel env run -e preview -- npm test

Run tests with preview Environment Variables.

terminal

vercel env run -e production -- next build

Run a production build with production Environment Variables.

terminal

vercel env run -e preview --git-branch feature-x -- next dev

Run the development server with preview Environment Variables for a specific Git branch.

The -- separator is required to distinguish between flags for vercel env run and the command you want to run. Flags after -- are passed to your command.

Options

The following options are available for vercel env run:

-e, --environment: Specify the environment to pull variables from. Defaults to development. Accepts development, preview, or production.
--git-branch: Specify a Git branch to pull branch-specific Environment Variables.

Unique Options

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

Type

vercel env add and vercel env update store each variable as Config or Secret. Use --type config or --type secret to set the type explicitly. The --sensitive and --no-sensitive flags map to Secret and Config. --visibility is a deprecated alias for --type.

Success output includes a Type line (Config or Secret).

Target	Default type	Notes
Production	`secret`	Use `--no-sensitive` or `--type config` for Config.
Preview	`secret`	Use `--no-sensitive` or `--type config` for Config.
Development	`config`	Use `--sensitive` or `--type secret` for Secret. Secrets are allowed in Development.
Custom environments	`secret`	Use `--no-sensitive` or `--type config` for Config.

terminal

vercel env add API_URL production --value "https://api.example.com" --no-sensitive --yes

Add a Config variable. --no-sensitive infers type: config.

terminal

vercel env add API_KEY production --value "sk_live_..." --sensitive --yes

Add a Secret variable. --sensitive infers type: secret.

terminal

vercel env add DEV_API_KEY development --value "sk_test_..." --sensitive --yes

Add a Secret in Development.

terminal

vercel env add API_URL production --type config --yes

Set the type explicitly with --type config or --type secret.

Using --sensitive or --no-sensitive with a conflicting --type returns an error.

In an interactive terminal, the CLI asks Environment Variable type? unless you pass a type flag, --yes, --value, or a value through stdin. Variables with a public framework prefix, such as NEXT_PUBLIC_, are stored as Config.

The legacy Enforce Sensitive Environment Variables team policy is deprecated. The CLI no longer enforces that policy locally. See Environment variables policy for the replacement Separate Production Secret Values policy.

Force

The --force option overwrites an existing environment variable of the same target without prompting for confirmation.

terminal

vercel env add API_TOKEN production --force

Using vercel env add with the --force option to overwrite an existing Environment Variable.

Yes

The --yes option can be used to bypass the confirmation prompt when overwriting an environment file, removing an environment variable, or updating an environment variable.

terminal

vercel env pull --yes

Using the vercel env pull command with the --yes option to overwrite an existing environment file.

terminal

vercel env rm [name] --yes

Using the vercel env rm command with the --yes option to skip the remove confirmation.

terminal

vercel env update API_TOKEN production --yes

Using the vercel env update command with the --yes option to skip the update confirmation.

Global Options

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

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

Last updated August 20, 2026

Cross-link map: vercel env (/docs/cli/env)

From the Vercel docs graph (built 2026-10-14T10:24:21.026Z), spanning vercel.com docs + KB, nextjs.org, ai-sdk.dev, and other Vercel documentation sites. Full graph as JSON: https://vercel.com/docs/graph.json

Semantically closest pages

vercel pull — Learn how to update your local project with remote environment variables using the vercel pull CLI command.
Managing environment variables across environments — Add, sync, and verify environment variables across development, preview, production, and custom environments using the C
Vercel CLI Global Options — Global options are commonly available to use with multiple Vercel CLI commands. Learn about Vercel CLI's global options
vercel deploy — Learn how to deploy your Vercel projects using the vercel deploy CLI command.
vercel list — Learn how to list out all recent deployments for the current Vercel Project using the vercel list CLI command.

This page links to (4)

vercel build — Learn how to build a Vercel Project locally or in your own CI environment using the vercel build CLI command.
Vercel CLI Global Options — Global options are commonly available to use with multiple Vercel CLI commands. Learn about Vercel CLI's global options
Environment variables — Learn more about environment variables on Vercel.
Config and Secret environment variables — Choose Config or Secret environment variables based on whether their values should remain readable after saving.

Pages that link here (27)

By site: vercel-kb (4) · vercel-docs (23)

From vercel-kb

How to add and manage environment variables on Vercel — Add environment variables to Vercel through the dashboard, CLI, or REST API, scope them to each environment, and pull th
Route form submissions with Jev and AI SDK — Route form submissions to the right team with the Jev x AI SDK Form Router template. Jev routes clear cases and a fallba
Migrate to Vercel from Cloudflare — Migrate your website's configuration from Cloudflare Pages or Workers to Vercel
How do I use private dependencies with Vercel? — Information on how to use private dependencies with a Vercel deployment.

From vercel-docs

Vercel Deep Infra Integration — Learn how to add the Deep Infra native integration with Vercel.
Vercel ElevenLabs Integration — Learn how to add the ElevenLabs connectable account integration with Vercel.
Vercel fal Integration — Learn how to add the fal native integration with Vercel.
Vercel Groq Integration — Learn how to add the Groq native integration with Vercel.
Vercel LMNT Integration — Learn how to add LMNT connectable account integration with Vercel.
Vercel Perplexity Integration — Learn how to add Perplexity connectable account integration with Vercel.
Vercel Pinecone Integration — Learn how to add Pinecone connectable account integration with Vercel.
Vercel Replicate Integration — Learn how to add Replicate connectable account integration with Vercel.
Vercel Together AI Integration — Learn how to add Together AI connectable account integration with Vercel.
Vercel xAI Integration — Learn how to add the xAI native integration with Vercel.
Vercel CLI Overview — Learn how to use the Vercel command-line interface \(CLI\) to manage and configure your Vercel Projects from the command
vercel target — Work with custom environments using the --target flag in Vercel CLI.
Environment variables — Learn more about environment variables on Vercel.
Managing environment variables across environments — Add, sync, and verify environment variables across development, preview, production, and custom environments using the C
Config and Secret environment variables — Choose Config or Secret environment variables based on whether their values should remain readable after saving.
Vercel Functions Limits — Learn about the limits and restrictions of using Vercel Functions.
Advanced Node.js Usage — Learn about advanced configurations for Vercel functions on Vercel.
Managing Global Configs with the Dashboard — Learn how to create, view and update your Global Configs and the data inside them in your Vercel Dashboard at the Hobby
Using Global Config — Learn how to use Global Configs in your projects.
Vercel CMS Integrations — Learn how to integrate Vercel with CMS platforms, including Contentful, Sanity, and Sitecore XM Cloud.
OpenID Connect \(OIDC\) Federation — Secure the access to your backend using OIDC Federation to enable auto-generated, short-lived, and non-persistent creden
Deploying a project from the CLI — Set up and deploy a Vercel project using the CLI, from linking to production.
@vercel/blob — Learn how to use the Vercel Blob SDK to access your blob store from your apps.

vercel domains

vercel firewall

Was this helpful?