env-vars

This skill guides your AI coding agent, such as Claude Code, Codex or Cursor, through managing an app’s settings on Vercel, including passwords, API keys and site URLs. It covers adding, updating and removing settings, and choosing separate values for the live site, preview versions and local development. It also helps your agent prepare local configuration files and troubleshoot temporary login tokens used by Vercel services.

WHEN TO USE

USE FOR

You need to add, update or remove an app setting, and choose whether Vercel stores it as a hidden Secret or a readable Config value.
You have just cloned a project or changed computers and want guidance on linking the project, downloading local settings and checking which entries from .env.example are missing.
A preview branch needs its own setting, such as a separate database URL for staging.
Your app authenticates successfully on Vercel but fails locally. The skill guides your agent through checking for a missing or expired OIDC token—the temporary login token—and an AI_GATEWAY_API_KEY that takes priority over it.
A database migration or other standalone script needs access to the project’s local settings.

This is the repository’s env-vars instruction file. Read the corrections in Defaults before using it; whole-plugin installations may provide an older version, as explained in Install.

In this document (9)

Vercel Environment Variables

You are an expert in Vercel environment variable management — .env file conventions, the vercel env CLI, OIDC token lifecycle, and environment-specific configuration.

.env File Hierarchy

Vercel and Next.js load environment variables in a specific order. Later files override earlier ones:

File	Purpose	Git-tracked?
`.env`	Default values for all environments	Yes
`.env.local`	Local overrides and secrets	No (gitignored)
`.env.development`	Development-specific defaults	Yes
`.env.development.local`	Local dev overrides	No
`.env.production`	Production-specific defaults	Yes
`.env.production.local`	Local prod overrides	No
`.env.test`	Test-specific defaults	Yes
`.env.test.local`	Local test overrides	No

Load Order (Next.js)

.env (lowest priority)
.env.[environment] (development, production, or test)
.env.local (skipped in test environment)
.env.[environment].local (highest priority, skipped in test)

Critical Rules

Never commit secrets to .env, .env.development, or .env.production — use .local variants or Vercel environment variables
.env.local is always gitignored by Next.js — this is where vercel env pull writes secrets
Variables prefixed with NEXT_PUBLIC_ are exposed to the browser bundle — never put secrets in NEXT_PUBLIC_ vars
All other variables are server-only (API routes, Server Components, middleware)

vercel env CLI

Pull Environment Variables

# Pull all env vars for the current environment into .env.local
vercel env pull .env.local

# Pull for a specific environment
vercel env pull .env.local --environment=production
vercel env pull .env.local --environment=preview
vercel env pull .env.local --environment=development

# Overwrite existing file without prompting
vercel env pull .env.local --yes

# Pull to a custom file
vercel env pull .env.production.local --environment=production

Add Environment Variables

Every variable has a type:

Type	After saving	Use for
Secret	Hidden in the dashboard and `vercel env ls`; can be replaced, never read back. Production and Preview Secrets are not returned by `vercel env pull`.	Passwords, API keys, tokens, database URLs
Config	Readable by members with access	Non-sensitive values you need to read later

Deployments receive both types at build time and runtime. Secret and Config replaced the Sensitive toggle; existing Sensitive variables are Secrets.

# Interactive — prompts for value, environments, and type
vercel env add MY_SECRET

# Non-interactive: read the value from a file so it never lands in shell
# history or process arguments (echo "value" | ... and --value do both)
vercel env add MY_SECRET production < ./secret.txt

# Add to production and preview in one command
vercel env add MY_SECRET production,preview < ./secret.txt

# Set the type explicitly
vercel env add MY_SECRET production --type secret < ./secret.txt
vercel env add SITE_REGION production --type config < ./region.txt

# Add development in its own command; development-only adds default to Config
vercel env add MY_SECRET development < ./dev-secret.txt

# Update an existing value
vercel env update MY_SECRET production < ./secret.txt

Defaults: a non-interactive add to production, preview, or a custom environment is stored as Secret.
Public prefixes are always Config: variables such as NEXT_PUBLIC_* or VITE_* are exposed to browsers, so the CLI refuses --type secret for them. Keep a private value under a name without the prefix.
Flags: --type config|secret needs Vercel CLI 59.6 or later. Older CLIs use --visibility, now a deprecated alias of --type. --sensitive (Secret) and --no-sensitive (Config) still work in every version.
Team policy: Separate Production Secret Values requires a Production Secret to differ from the Preview, Development, and custom environment values of the same key. Under it, create separate Production and non-Production values instead of adding one value to all targets. It replaces the deprecated Enforce Sensitive Environment Variables policy.

List Environment Variables

# List all environment variables
vercel env ls

# Filter by environment
vercel env ls production

Remove Environment Variables

# Remove from specific environment
vercel env rm MY_SECRET production

# Remove from all environments
vercel env rm MY_SECRET

Bootstrap Flow (Fresh Clone / New Machine)

Use this sequence when setting up a project from scratch:

# 1) Link first so pulls target the correct Vercel project
vercel link --yes --project <name-or-id> --scope <team>

# 2) Pull env vars into .env.local
vercel env pull .env.local --yes

# 3) Verify required keys from .env.example exist in .env.local
while IFS='=' read -r key _; do
  [[ -z "$key" || "$key" == \#* ]] && continue
  grep -q "^${key}=" .env.local || echo "Missing in .env.local: $key"
done < .env.example

Temporary Path: Run With Vercel Envs Without Writing a File

If you need Vercel environment variables immediately but do not want to write .env.local yet:

vercel env run -- npm run dev

This is useful for quick validation during bootstrap, but still pull .env.local for a normal local workflow.

Re-pull After Secret or Provisioning Changes

After creating/updating secrets (vercel env add, dashboard changes) or provisioning integrations that add env vars (for example Neon/Upstash), re-run:

vercel env pull .env.local --yes

OIDC Token Lifecycle

Vercel uses OIDC (OpenID Connect) tokens for secure, keyless authentication between your app and Vercel services (AI Gateway, storage, etc.).

How It Works

On Vercel deployments: VERCEL_OIDC_TOKEN is automatically injected as a short-lived JWT and auto-refreshed — zero configuration needed
Local development: vercel env pull .env.local provisions a VERCEL_OIDC_TOKEN valid for ~12 hours
Token expiry: When the local OIDC token expires, re-run vercel env pull .env.local --yes to get a fresh one. Consider re-pulling at the start of each dev session to avoid mid-session auth failures

Common OIDC Patterns

// The @vercel/oidc package reads VERCEL_OIDC_TOKEN automatically
import { getVercelOidcToken } from '@vercel/oidc'

// AI Gateway uses OIDC by default — no manual token handling needed
import { gateway } from 'ai'
const result = await generateText({
  model: gateway('openai/gpt-5.2'),
  prompt: 'Hello',
})

Troubleshooting OIDC

Symptom	Cause	Fix
`VERCEL_OIDC_TOKEN` missing locally	Haven't pulled env vars	`vercel env pull .env.local`
Auth errors after ~12h locally	Token expired	`vercel env pull .env.local --yes`
Works on Vercel, fails locally	Token not in `.env.local`	`vercel env pull .env.local`
`AI_GATEWAY_API_KEY` vs OIDC	Both set, key takes priority	Remove `AI_GATEWAY_API_KEY` to use OIDC

Environment-Specific Configuration

Vercel Dashboard vs .env Files

Use Case	Where to Set
Secrets (API keys, tokens)	Vercel Dashboard (`https://vercel.com/{team}/{project}/settings/environment-variables`) or `vercel env add`, as type Secret
Public config (site URL, feature flags)	`.env` or `.env.[environment]` files
Local-only overrides	`.env.local`
CI/CD secrets	Vercel Dashboard (`https://vercel.com/{team}/{project}/settings/environment-variables`) with environment scoping

Environment Scoping on Vercel

Variables set in the Vercel Dashboard at https://vercel.com/{team}/{project}/settings/environment-variables can be scoped to:

Production — production domain deployments
Preview — branch/PR deployments
Development — vercel dev and vercel env pull

A variable can be assigned to one, two, or all three environments.

Git Branch Overrides

Preview environment variables can be scoped to specific Git branches:

# Add a variable only for the "staging" branch
vercel env add DATABASE_URL preview --git-branch=staging < ./staging-database-url.txt

Gotchas

`vercel env pull` Overwrites Custom Variables

vercel env pull .env.local replaces the entire file — any manually added variables (custom secrets, local overrides, debug flags) are lost. Always back up or re-add custom vars after pulling:

# Save custom vars before pulling
grep -v '^#' .env.local | grep -v '^VERCEL_\|^POSTGRES_\|^NEXT_PUBLIC_' > .env.custom.bak
vercel env pull .env.local --yes
cat .env.custom.bak >> .env.local  # Re-append custom vars

Or maintain custom vars in a separate .env.development.local file (loaded after .env.local by Next.js).

Pulled Files Omit Production and Preview Secrets

vercel env pull --environment=production (or preview) does not write Secret values, so a pulled file cannot reproduce production credentials. Keep separate Development values for local work instead of trying to copy production Secrets onto a machine.

Scripts Don't Auto-Load `.env.local`

Only Next.js auto-loads .env.local. Standalone scripts (drizzle-kit, tsx, custom Node scripts) need explicit loading:

# Use dotenv-cli
npm install -D dotenv-cli
npx dotenv -e .env.local -- npx drizzle-kit push
npx dotenv -e .env.local -- npx tsx scripts/seed.ts

# Or source manually
source <(grep -v '^#' .env.local | sed 's/^/export /') && node scripts/migrate.js

Best Practices

Use vercel env pull as part of your setup workflow — document it in your README
Never hardcode secrets — always use environment variables
Scope narrowly — don't give preview deployments production database access
Rotate OIDC tokens regularly in local dev — re-pull when you see auth errors
Use .env.example — commit a template with empty values so teammates know which vars are needed
Prefix client-side vars with NEXT_PUBLIC_ — and never put secrets in them
Keep custom vars in .env.development.local — protects them from vercel env pull overwrites

Official Documentation

Account or credentials required

4 FOR YOU

Items without a tag are required.

01
Install the Vercel CLI
Install Vercel’s command-line tool where your agent will run the project commands; the skill provides instructions for this tool. The npm package for Vercel CLI 63.1.2 requires Node.js 20 or later, and Vercel documents installation with npm i -g vercel. Check the installed CLI version with vercel --version.
```
vercel --version
```
02
Sign in with project access
Use a Vercel account with access to the project whose settings you want to manage, and sign in to the CLI with vercel login. The CLI requires authentication before accessing project resources.
```
vercel login
```
03
Optional Choose your CLI telemetry setting
If you want to turn off Vercel CLI usage reporting, run vercel telemetry disable under the system user that will run your agent’s commands. Alternatively, set VERCEL_TELEMETRY_DISABLED=1 in that execution environment; it applies only to runs where the variable is set. This choice is optional: leaving telemetry enabled does not prevent you from using the skill.
```
vercel telemetry disable
```
04
Link the local project
From the project folder, use vercel link to select the intended Vercel project. Downloading settings requires this link, or both VERCEL_ORG_ID and VERCEL_PROJECT_ID set in the execution environment.

Setup details: Expect some account or credential setup.

Pulling now preserves local-only settings
The skill says vercel env pull .env.local replaces the entire file and tells your agent to back up and re-append custom settings. Since Vercel CLI 56.0.0, pulling merges downloaded values into the file and keeps variables that exist only locally. On these versions, use the merge behavior rather than the skill’s backup-and-re-append recipe for local-only variables.
This does not preserve every existing value: VERCEL_OIDC_TOKEN is refreshed, and VERCEL_ANALYTICS_ID, VERCEL_SPEED_INSIGHTS_ID and VERCEL_WEB_ANALYTICS_ID are not kept as local-only entries.
Pulling cannot retrieve saved Secrets
The skill highlights missing Production and Preview Secrets, then recommends pulling again after Secret changes. Vercel now allows Secrets in Development too—enabled by default in CLI 59.4.0—but saved Secret values cannot be read back in any environment. For local work, supply a separate local value: pulling keeps a real value already in the file or writes a placeholder, rather than retrieving the newly saved Secret.
Variable types have different defaults
When adding a variable without interactive prompts, Production, Preview and custom environments default to Secret; a Development-only add defaults to Config. Config values remain readable to members with access, while Secrets are write-only after saving. Choose the type explicitly when the default does not match the value you are storing.
Public prefixes expose values to browsers
Next.js exposes NEXT_PUBLIC_ values to browser code, and Vite exposes VITE_ values. Keep passwords, API keys and other private values under names without these public prefixes. The Vercel CLI stores variables with public framework prefixes as Config.
Check Git exclusions before committing
The skill says .env.local is always ignored by Next.js, but exclusion depends on the project’s .gitignore. The default create-next-app template includes environment-file exclusions, and Vercel CLI 54.3.0 added .env* exclusions when pulling to the default .env.local. Check your project’s exclusions before committing files that contain private values.
Use the correct Next.js load order
The skill attributes its file hierarchy to Vercel and Next.js and says the highest-priority local file is skipped in tests. Next.js checks process.env, .env.$(NODE_ENV).local, .env.local, .env.$(NODE_ENV) and .env, in that order, stopping when it finds a value. With NODE_ENV=test, it skips .env.local but still loads .env.test.local.
File loading depends on the tool
The skill says only Next.js automatically loads .env.local, but Vite also loads it. For standalone scripts, configure the loader for the tool you are using rather than assuming the file will be read. Next.js documents @next/env for loading settings outside its runtime, such as in database-tool configuration or tests.
Type flags depend on CLI versions
The skill says --type config|secret needs CLI “59.6 or later” and that --sensitive and --no-sensitive work in every version. The first published npm version with --type is 59.6.2; --no-sensitive was added to env add in 51.8.0, while env update has no --no-sensitive option in CLI 59.6.2–63.1.2. For add and update on these versions, use --type config or --type secret instead of applying the skill’s blanket fallback advice.
Production secrets may require separate values
If a team owner enables Separate Production Secret Values, a Secret’s Production value must differ from its Preview, Development and custom-environment values. Create separate Production and non-Production values when this policy applies.
Changes apply to new deployments
Updating a setting on Vercel does not change previous deployments; the new value applies to new deployments. Vercel supports custom environments as well as Production, Preview and Development, although the skill’s environment-scoping list names only those three.
Vercel CLI reports usage by default
Vercel CLI telemetry is enabled by default and is separate from either installer’s reporting and the plugin’s telemetry. Vercel says it reports commands and arguments used, CLI version, general machine information and account-associated identifiers, while excluding environment variables, file paths, file contents and logs. You can turn it off using the optional preparation step above.
The saved CLI setting belongs to your system user’s global configuration; --global-config can select another configuration directory, and the environment-variable opt-out applies only where that variable is set.

The upstream Vercel Plugin includes commands, agents, hooks and Vercel MCP. Installed components and skill versions vary by client.

This route installs env-vars using the skills CLI’s generic installation syntax; Vercel’s plugin instructions document whole-plugin installation. It does not install the plugin’s commands, agents, hooks, Vercel MCP connection or plugin telemetry hooks.

Install checklist

The single-skill installer, skills CLI 1.7.2, requires Node.js 22.20.0 or later.
Run the single-skill command in an interactive terminal from your project’s folder.
When you run skills CLI 1.7.2 in a regular terminal outside your agent, Claude Code’s preselection depends on the tools the installer detects and your previous choices. With none detected, Claude Code is preselected unless a previous selection applies; with two or more, it is preselected only if you selected it previously. If Claude Code is the only detected tool, the installer skips the agent picker and automatically includes it.
If an agent picker appears, find Claude Code and check whether it is selected. Press Space only if it is unchecked, then press Enter to confirm.
On an interactive installation, the installer may offer the separate find-skills skill, with Yes selected by default; this is a one-time prompt and can be skipped if you have answered it before. Accepting installs find-skills globally for the selected targets, including at ~/.agents/skills/find-skills, even when env-vars is installed only for the project. Choose No if you want to install only env-vars.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add vercel/vercel-plugin --skill "env-vars" --full-depth

Installation and loading

The skills CLI installs env-vars for the project by default and offers a user-wide installation. When Claude Code is an installation target, whether selected in the agent picker or included automatically as the only detected tool, the installer offers a symlink or copy. For a project installation, the default symlink points from .claude/skills/env-vars to .agents/skills/env-vars.
In Claude Code, use /env-vars to request the installed skill directly, or let your agent choose it when its description matches the task. If the installation creates a top-level skills directory that did not exist when your current session started, run /reload-skills; otherwise, Claude Code watches existing skill directories for changes except in bare mode.
Cursor discovers skills when it starts and lets your agent choose relevant guidance. To request env-vars directly, type / in Agent chat and search for env-vars; this attaches the skill to one message.
In Codex, use /skills or type $ to select env-vars. Your agent may also choose it when the task matches the skill’s description.

Good to know

In our Vercel Sandbox test on Amazon Linux 2023 with Node 24.14.1 and skills CLI 1.7.2, running the displayed command without an interactive terminal exited with code 1 and installed nothing.
In simulated-terminal tests on that sandbox, with an empty project, no previous selection and directories corresponding to two or more detected tools, accepting the defaults left Claude Code unselected and it found no skill. After selecting Claude Code, the debug output from Claude Code 2.1.296 showed that it found the project skill. Claude Code was not signed in, and we did not test an actual skill invocation.

What's inside

With --full-depth, the skills CLI clones the repository and copies the skill folder’s SKILL.md and .vercel.approvers, an internal review-owner file, into the selected installation directory.

View on GitHub

This route installs the Vercel Plugin package selected for your AI tool.

Whole-plugin installation can provide a different version of env-vars from the one shown in Documents. When the installer uses Claude Code’s official marketplace, it installs plugin 0.50.0; Codex receives the curated vercel@openai-curated package, whose manifest version is 0.21.4. Both contain an older env-vars file than the repository’s plugin 0.54.1 shown here.

Run this command in a terminal

Install checklist

For this terminal installation route, the plugins installer requires Node.js 18 or later, and Vercel’s plugin instructions also require Bun. The installer lists Claude Code, Cursor, Codex, Grok Build, Kimi Code, GitHub Copilot CLI and VS Code as targets.
The plugins installer detects installed target tools and installs to all detected targets by default; its default scope is per user.
By default, plugins installer 1.3.4 sends an installation report to plugins-telemetry.labs.vercel.dev, including the source exactly as entered, selected plugin names and count, installed target tools, scope, a version field and a CI flag when applicable. It does not check repository visibility before reporting the source, so private repository names, URLs and local paths can be included. Set DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 in the terminal before running the installer to turn this reporting off.
Plugin telemetry is enabled by default in both Claude Code’s official marketplace version 0.50.0 and repository-based installs of upstream plugin 0.54.1, including activity counters, plugin version, a random installation ID, detected coding-tool category and names of its skills when loaded through supported hooks. Set VERCEL_PLUGIN_TELEMETRY=off in the environment that launches your agent, then restart that terminal or app session to disable it. This switch is separate from the installer’s reporting and does not disable Vercel CLI telemetry.
Vercel MCP supports approved clients; its supported-client list does not include GitHub Copilot CLI, Grok Build or Kimi Code. If you need MCP access in one of these clients, confirm that it can complete Vercel authorization before choosing this route for that purpose.

npx plugins add vercel/vercel-plugin

Installation and loading

The upstream plugin bundles Vercel MCP, which can read projects and logs, create deployments and update resources. Before using its account tools, authenticate and grant access to the intended Vercel teams.
Under Claude Code’s plugin naming rule, the vercel manifest makes this skill /vercel:env-vars; /vercel:env is the separate environment-management command. In Cursor, type / in Agent chat and search for the installed skill; in Codex, use /skills or $ to select it. In these clients, your agent may also choose an available skill when its description matches the task.
The upstream plugin does not inject every skill on every prompt or tool call by default.

Good to know

Codex’s curated package declares skills and a connected Vercel app, and contains no plugin telemetry hooks. Its bundled agents and commands are described as included for source parity, so their presence in the package does not establish that Codex exposes them.
Kimi Code does not expose plugin agents. VS Code’s agent-plugin support is a Preview feature.

Open plugin page ↗

Vercel Environment Variables

.env File Hierarchy

Load Order (Next.js)

Critical Rules

vercel env CLI

Pull Environment Variables

Add Environment Variables

List Environment Variables

Remove Environment Variables

Bootstrap Flow (Fresh Clone / New Machine)

Temporary Path: Run With Vercel Envs Without Writing a File

Re-pull After Secret or Provisioning Changes

OIDC Token Lifecycle

How It Works

Common OIDC Patterns

Troubleshooting OIDC

Environment-Specific Configuration

Vercel Dashboard vs .env Files

Environment Scoping on Vercel

Git Branch Overrides

Gotchas

vercel env pull Overwrites Custom Variables

Pulled Files Omit Production and Preview Secrets

Scripts Don't Auto-Load .env.local

Best Practices

Official Documentation

Account or credentials required

Pulling now preserves local-only settings

Pulling cannot retrieve saved Secrets

Variable types have different defaults

Public prefixes expose values to browsers

Check Git exclusions before committing

Use the correct Next.js load order

File loading depends on the tool

Type flags depend on CLI versions

Production secrets may require separate values

Changes apply to new deployments

Vercel CLI reports usage by default

What's inside

Run this command in a terminal

More skills

access-protected-vercel-deployment

ai-gateway

auth

bootstrap

build-agents

cdn-caching

`vercel env pull` Overwrites Custom Variables

Scripts Don't Auto-Load `.env.local`