Managing environment variables across environments

Use this guide to manage environment variables across multiple environments. You'll audit what's configured, add variables to the right targets, handle sensitive values, and verify everything locally.

Use this block when you already know what you're doing and want the full command sequence. Use the steps below for context and checks.

# 1. List available environments (including custom ones)
vercel target list
 
# 2. Audit existing variables per environment
vercel env ls production
vercel env ls preview
vercel env ls development
 
# 3. Add variables to specific environments
vercel env add DATABASE_URL production
vercel env add DATABASE_URL preview
 
# 4. Add a sensitive variable (hidden in dashboard, extra security)
vercel env add API_SECRET production --sensitive
 
# 5. Add a branch-specific preview variable
vercel env add DATABASE_URL preview feature-branch
 
# 6. Pull environment variables locally to verify
vercel pull --environment=production
vercel pull --environment=preview --git-branch=feature-branch
 
# 7. Run a command with specific environment variables
vercel env run -e preview -- npm test
vercel env run -e production -- npm run build

Check which environments are available for your project. This includes the default environments (production, preview, development) and any custom environments:

vercel target list

Custom environments let you create additional targets like staging or qa with their own environment variables.

Review what's currently configured in each environment to identify gaps or mismatches:

vercel env ls production

vercel env ls preview

vercel env ls development

To check variables for a custom environment:

vercel env ls staging

Compare the output across environments. Missing variables are a common cause of deployment failures where a preview works but production doesn't, or vice versa.

Add a variable to a single environment. The CLI reads the value from stdin, so it prompts you to enter it:

vercel env add DATABASE_URL production

To pipe a value in without the prompt:

echo "postgres://user:pass@host/db" | vercel env add DATABASE_URL production

To add the same variable to multiple environments, run the command for each one:

vercel env add DATABASE_URL preview
vercel env add DATABASE_URL development

For secrets like API keys and tokens, use the --sensitive flag. This adds extra security measures and hides the value in the Vercel Dashboard:

vercel env add API_SECRET production --sensitive

Sensitive variables behave the same at runtime but their values are non-readable once created. They are only available in production and preview environments.

For preview deployments, you can set variables that only apply to a specific Git branch. This is useful for testing against a different database or API endpoint on a feature branch:

vercel env add DATABASE_URL preview feature-branch

This variable only applies to preview deployments triggered from the feature-branch branch. Other preview deployments use the default preview variable.

To change the value of an existing variable:

vercel env update DATABASE_URL production

You can also pipe the new value:

cat ~/.npmrc | vercel env update NPM_RC preview

Pull environment variables to your local machine to verify they're set correctly:

vercel pull --environment=production

For preview variables with a specific branch:

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

This writes the variables to .vercel/.env.preview.local (or the equivalent for your target environment). Check the file to confirm the values are correct.

Test your app locally using the environment variables from a specific environment without writing them to a file:

vercel env run -e preview -- npm test

vercel env run -e production -- npm run build

For branch-specific variables:

vercel env run -e preview --git-branch feature-branch -- npm run dev

To remove an environment variable from a specific environment:

vercel env rm DATABASE_URL production

This prompts for confirmation. Use --yes to skip the prompt in automated workflows:

vercel env rm DATABASE_URL production --yes

• vercel env
• vercel pull
• vercel target
• Environment variables overview
• Deploying a project from the CLI