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 remove), 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.
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.local file or a different file of your choice.
vercel env pull [file]To override environment variable values temporarily, use:
MY_ENV_VAR="temporary value" next devWhen 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_TOKENis never preserved from your local file. It is always refreshed from Vercel. The Vercel-managed analytics variablesVERCEL_ANALYTICS_ID,VERCEL_SPEED_INSIGHTS_ID, andVERCEL_WEB_ANALYTICS_IDare 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.
vercel env listUsing the vercel env command to list all Environment
Variables in a Vercel Project.
vercel env addUsing the vercel env command to add an Environment
Variable to a Vercel Project.
vercel env removeUsing the vercel env command to remove an Environment
Variable from a Vercel Project.
The --environment and --git-branch options of vercel env add, list, remove, and update need Vercel CLI 64.7.0 or later.
vercel env list --environment [environment]Using the vercel env command to list Environment
Variables for a specific Environment in a Vercel Project.
vercel env list --environment preview --git-branch [gitbranch]Using the vercel env command to list the Preview
Environment Variables of a specific Git branch.
vercel env add [name]Using the vercel env command to add an Environment
Variable to a Vercel Project. The CLI prompts you to select the Environments.
vercel env add [name] --environment [environment]Using the vercel env command to add an Environment
Variable for a specific Environment to a Vercel Project.
vercel env add [name] --environment production,previewUsing the vercel env command to add an Environment
Variable to several Environments at once. Separate the Environments with
commas.
vercel env add [name] --environment preview --git-branch [gitbranch]Using the vercel env command to add an Environment
Variable to a specific Git branch. Only Preview Environment Variables can
target a Git branch.
vercel env add [name] --environment [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.
echo [value] | vercel env add [name] --environment [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.
vercel env add [name] --environment preview --git-branch [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.
vercel env remove [name] --environment [environment]Using the vercel env command to remove an Environment
Variable from a Vercel Project.
The vercel env update sub-command updates the value of an existing environment variable.
vercel env update [name]Using vercel env update to update an Environment
Variable across all Environments.
vercel env update [name] --environment [environment]Using vercel env update to update the Environment
Variable that covers a specific Environment. The new value applies to every
Environment that the variable covers.
vercel env update [name] --environment preview --git-branch [gitbranch]Using vercel env update to update the Preview
Environment Variable of a specific Git branch.
cat ~/.npmrc | vercel env update NPM_RC --environment preview --yesUpdate an Environment Variable value from stdin. The --yes option skips
the update confirmation, which piped input cannot answer.
vercel env pull [file]Using the vercel env command to download Development
Environment Variables from the cloud and write to a specific file.
vercel env pull --environment=previewUsing the vercel env command to download Preview
Environment Variables from the cloud and write to the
.env.local file.
vercel env pull --environment=preview --git-branch=feature-branchUsing the vercel env command to download
"feature-branch" Environment Variables from the cloud and write to the
.env.local file.
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.
vercel env run -- <command>Using vercel env run to run a command with
development Environment Variables from your Vercel Project.
vercel env run -- next devRun the Next.js development server with development Environment Variables.
vercel env run -e preview -- npm testvercel env run -e production -- next buildvercel env run -e preview --git-branch feature-x -- next devRun the development server with preview Environment Variables for a specific Git branch.
The following options are available for vercel env run:
-e, --environment: Specify the environment to pull variables from. Defaults todevelopment. Acceptsdevelopment,preview,production, or the name of a custom environment.--git-branch: Specify a Git branch to pull branch-specific Environment Variables.
These are options that only apply to the vercel env command.
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 flag maps to Secret. With vercel env add, the --no-sensitive flag maps to Config. --visibility is a deprecated alias for --type.
By default, vercel env update keeps the variable's current type. Pass --type secret to change a Config variable to a Secret. To change a Secret to Config, remove the variable and add it again with --type config.
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. |
vercel env add API_URL --environment production --value "https://api.example.com" --no-sensitive --yesAdd a Config variable. --no-sensitive infers type: config.
vercel env add API_KEY --environment production --value "sk_live_..." --sensitive --yesAdd a Secret variable. --sensitive infers type: secret.
vercel env add DEV_API_KEY --environment development --value "sk_test_..." --sensitive --yesAdd a Secret in Development.
vercel env add API_URL --environment production --type config --yesSet 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.
The --force option overwrites an existing environment variable of the same target without prompting for confirmation.
vercel env add API_TOKEN --environment production --forceUsing vercel env add with the
--force option to overwrite an existing Environment
Variable.
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.
vercel env pull --yesUsing the vercel env pull command with the
--yes option to overwrite an existing environment
file.
vercel env remove [name] --yesUsing the vercel env remove command with the
--yes option to skip the remove confirmation.
vercel env update API_TOKEN --environment production --yesUsing the vercel env update command with the
--yes option to skip the update confirmation.
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.
Was this helpful?