env

# Vercel Environment Variables Manage environment variables for the current Vercel project with safety rails to prevent secret leakage. > **🔒 Never-Echo-Secrets Rule**: Environment variable **values** must never appear in command output, summaries, or conversation text. Only show variable **names**, **environments**, and **metadata** (created date, type). This rule applies to all subcommands. ## Preflight 1. **CLI available?** — Confirm `vercel` is on PATH. - If missing: `npm i -g vercel` (or `pnpm add -g vercel` / `bun add -g vercel`). 2. **Project linked?** — Check for `.vercel/project.json` in the current directory or nearest parent. - If not found: run `vercel link` interactively, then re-run `/env`. 3. **Detect environment files** — Check for `.env`, `.env.local`, `.env.production.local`, `.env.development.local` in the project root. Note which exist for the diff subcommand. ## Plan Based on "$ARGUMENTS", determine the action: | Argument | Action | Destructive? | |----------|--------|-------------| | `list` / `ls` / _(none)_ | List env var names per environment | No | | `pull` | Download env vars to local `.env.local` | No (overwrites local file) | | `add <NAME>` | Add a new env var | Yes (if production) | | `rm <NAME>` / `remove <NAME>` | Remove an env var | **Yes** | | `diff` | Compare local vs Vercel key names | No | For any operation that mutates **production** environment variables (`add` or `rm` targeting production): > ⚠️ **Production environment mutation requested.** > This will change environment variables on your live production deployment. > **Ask the user for explicit confirmation before proceeding.** Do not mutate production env vars without a clear "yes." ## Commands ### "list" or "ls" or no arguments <!-- Sourced from env-vars skill: vercel env CLI > List Environment Variables --> ```bash # List all environment variables vercel env ls # Filter by environment vercel env ls production ``` Present results as a table of variable **names only** grouped by environment. **Never print values.** | Name | Production | Preview | Development | |------|-----------|---------|-------------| | DATABASE_URL | ✓ | ✓ | ✓ | | API_KEY | ✓ | ✓ | — | ### "pull" <!-- Sourced from env-vars skill: vercel env CLI > Pull Environment Variables --> ```bash # 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 ``` After pulling, remind the user: > Ensure `.env*.local` is in your `.gitignore` to avoid committing secrets. ### "add \<NAME\>" 1. Ask the user which environments to target: production, preview, development (can select multiple). 2. If **production** is selected, require explicit confirmation (see Plan section). 3. Run the add command: <!-- Sourced from env-vars skill: vercel env CLI > 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. ```bash # 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. The CLI will prompt for the value interactively — **do not pass the value as a CLI argument or echo it**. ### "rm \<NAME\>" or "remove \<NAME\>" 1. If the variable exists in **production**, require explicit confirmation. 2. Run the remove command: <!-- Sourced from env-vars skill: vercel env CLI > Remove Environment Variables --> ```bash # Remove from specific environment vercel env rm MY_SECRET production # Remove from all environments vercel env rm MY_SECRET ``` Confirm the target environment(s) with the user before executing. ### "diff" Compare local environment file key names against Vercel-configured key names. **Only compare names — never read or display values.** 1. Read local env file keys (from `.env.local` or `.env` — whichever exists): ```bash grep -v '^#' .env.local | grep '=' | cut -d'=' -f1 | sort ``` 2. Fetch Vercel env var names: ```bash vercel env ls ``` Parse the output to extract variable names for the target environment (default: development). 3. Present the diff: ``` ## Env Diff — Local vs Vercel (development) ### In local but NOT on Vercel: - EXTRA_LOCAL_VAR - DEBUG_MODE ### On Vercel but NOT in local: - ANALYTICS_KEY - SENTRY_DSN ### In both: - DATABASE_URL - API_KEY - NEXT_PUBLIC_APP_URL ``` If all keys match, report: "Local and Vercel environment keys are in sync." ## Environment-Specific Configuration Reference <!-- Sourced from env-vars skill: 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: ```bash # Add a variable only for the "staging" branch vercel env add DATABASE_URL preview --git-branch=staging < ./staging-database-url.txt ``` ## Common Gotchas <!-- Sourced from env-vars skill: 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: ```bash # 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: ```bash # 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 ``` ## Verification After any mutation (`add` or `rm`), verify the change took effect: ```bash vercel env ls ``` Re-list environment variables and confirm: - For `add`: the new variable name appears in the expected environment(s). - For `rm`: the variable name no longer appears in the target environment(s). If verification fails (variable still present after remove, or missing after add), report the discrepancy and suggest retrying. ## Summary Present a structured result block: ``` ## Env Result - **Action**: list | pull | add | remove | diff - **Status**: success | failed - **Variable**: <NAME> (for add/remove) - **Environments**: production, preview, development (as applicable) - **Details**: <key outcome> ``` For `diff`, include counts: ``` - **Local only**: N keys - **Vercel only**: N keys - **Shared**: N keys ``` ## Next Steps Based on the action performed: - **After list** → "Run `/env pull` to sync to local, or `/env diff` to compare local vs Vercel." - **After pull** → "Restart your dev server to pick up the new variables. Run `/env diff` to verify sync." - **After add** → "Run `/deploy` to make the new variable available in your next deployment. For production, the variable is available immediately on the next request." - **After remove** → "The variable is removed. If your app depends on it, update your code or add a replacement. Consider redeploying with `/deploy`." - **After diff** → "Add missing variables with `/env add <NAME>`, or pull from Vercel with `/env pull` to sync."