Vercel CLI with Tokens
Deploy and manage projects on Vercel using the CLI with token-based authentication, without relying on
.
Step 1: Locate the Vercel Token
Before running any Vercel CLI commands, identify where the token is coming from. Work through these scenarios in order:
A) is already set in the environment
If this returns a value, you're ready. Skip to Step 2.
B) Token is in a file under
bash
grep '^VERCEL_TOKEN=' .env 2>/dev/null
If found, export it:
bash
export VERCEL_TOKEN=$(grep '^VERCEL_TOKEN=' .env | cut -d= -f2-)
C) Token is in a file under a different name
Look for any variable that looks like a Vercel token (Vercel tokens typically start with
):
bash
grep -i 'vercel' .env 2>/dev/null
Inspect the output to identify which variable holds the token, then export it as
:
bash
export VERCEL_TOKEN=$(grep '^<VARIABLE_NAME>=' .env | cut -d= -f2-)
D) No token found — ask the user
If none of the above yield a token, ask the user to provide one. They can create a Vercel access token at vercel.com/account/tokens.
Important: Once
is exported as an environment variable, the Vercel CLI reads it natively —
do not pass it as a flag. Putting secrets in command-line arguments exposes them in shell history and process listings.
bash
# Bad — token visible in shell history and process listings
vercel deploy --token "vca_abc123"
# Good — CLI reads VERCEL_TOKEN from the environment
export VERCEL_TOKEN="vca_abc123"
vercel deploy
Step 2: Locate the Project and Team
Similarly, check for the project ID and team scope. These let the CLI target the right project without needing
.
bash
# Check environment
printenv VERCEL_PROJECT_ID
printenv VERCEL_ORG_ID
# Or check .env
grep -i 'vercel' .env 2>/dev/null
If you have a project URL (e.g.
https://vercel.com/my-team/my-project
), extract the team slug:
bash
# e.g. "my-team" from "https://vercel.com/my-team/my-project"
echo "$PROJECT_URL" | sed 's|https://vercel.com/||' | cut -d/ -f1
If you have both and in your environment, export them — the CLI will use these automatically and skip any
directory:
bash
export VERCEL_ORG_ID="<org-id>"
export VERCEL_PROJECT_ID="<project-id>"
Note:
and
must be set together — setting only one causes an error.
CLI Setup
Ensure the Vercel CLI is installed and up to date:
bash
npm install -g vercel
vercel --version
Deploying a Project
Always deploy as preview unless the user explicitly requests production. Choose a method based on what you have available.
Quick Deploy (have project ID — no linking needed)
When
and
are set in the environment, deploy directly:
bash
vercel deploy -y --no-wait
With a team scope (either via
or
):
bash
vercel deploy --scope <team-slug> -y --no-wait
Production (only when explicitly requested):
bash
vercel deploy --prod --scope <team-slug> -y --no-wait
Check status:
bash
vercel inspect <deployment-url>
Full Deploy Flow (no project ID — need to link)
Use this when you have a token and team but no pre-existing project ID.
Check project state first
bash
# Does the project have a git remote?
git remote get-url origin 2>/dev/null
# Is it already linked to a Vercel project?
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null
Link the project
With git remote (preferred):
bash
vercel link --repo --scope <team-slug> -y
Reads the git remote and connects to the matching Vercel project. Creates
. More reliable than plain
, which matches by directory name.
Without git remote:
bash
vercel link --scope <team-slug> -y
Link to a specific project by name:
bash
vercel link --project <project-name> --scope <team-slug> -y
If the project is already linked, check
in
or
to verify it matches the intended team.
Deploy after linking
A) Git Push Deploy — has git remote (preferred)
Git pushes trigger automatic Vercel deployments.
- Ask the user before pushing. Never push without explicit approval.
- Commit and push:
bash
git add .
git commit -m "deploy: <description of changes>"
git push
- Vercel builds automatically. Non-production branches get preview deployments.
- Retrieve the deployment URL:
bash
sleep 5
vercel ls --format json --scope <team-slug>
B) CLI Deploy — no git remote
bash
vercel deploy --scope <team-slug> -y --no-wait
Check status:
bash
vercel inspect <deployment-url>
Deploying from a Remote Repository (code not cloned locally)
- Clone the repository:
bash
git clone <repo-url>
cd <repo-name>
- Link to Vercel:
bash
vercel link --repo --scope <team-slug> -y
- Deploy via git push (if you have push access) or CLI deploy.
About Directory
A linked project has either:
- — from . Contains and .
- — from . Contains , , and a map.
Not needed when
+
are both set in the environment.
Do NOT run
or
in an unlinked directory to detect state — they will interactively prompt or silently link as a side-effect.
is safe (in an unlinked directory it defaults to showing all deployments for the scope).
is safe anywhere.
Managing Environment Variables
bash
# Set for all environments
echo "value" | vercel env add VAR_NAME --scope <team-slug>
# Set for a specific environment (production, preview, development)
echo "value" | vercel env add VAR_NAME production --scope <team-slug>
# List environment variables
vercel env ls --scope <team-slug>
# Pull env vars to local .env.local file
vercel env pull --scope <team-slug>
# Remove a variable
vercel env rm VAR_NAME --scope <team-slug> -y
Inspecting Deployments
bash
# List recent deployments
vercel ls --format json --scope <team-slug>
# Inspect a specific deployment
vercel inspect <deployment-url>
# View build logs (requires Vercel CLI v35+)
vercel inspect <deployment-url> --logs
# View runtime request logs (follows live by default; add --no-follow for a one-shot snapshot)
vercel logs <deployment-url>
Managing Domains
bash
# List domains
vercel domains ls --scope <team-slug>
# Add a domain to the project — linked or env-linked directory (1 arg)
vercel domains add <domain> --scope <team-slug>
# Add a domain — unlinked directory (requires <project> positional)
vercel domains add <domain> <project> --scope <team-slug>
Stripe Projects Plan Changes
If this project is managed by Stripe Projects. Ask the user before running any paid or destructive plan change — upgrades bill a real card, downgrades remove seats.
First run
stripe projects status --json
to confirm the Vercel resource's local name. The examples below assume the default (
); substitute the actual name if it was renamed at
time.
- Upgrade to Pro:
stripe projects add vercel/pro
stripe projects upgrade vercel-plan pro
- Downgrade to Hobby:
stripe projects downgrade vercel-plan hobby
What Pro gives you
- $20/month platform fee, includes $20/month of usage credit.
- Turbo build machines (30 vCPUs, 60 GB memory) by default for new projects — significantly faster builds than Hobby.
- 1 deploying seat + unlimited free Viewer seats (read-only collaborators, preview comments).
- Higher included allocations (1 TB Fast Data Transfer, 10M Edge Requests per month).
- Paid add-ons available: SAML SSO, HIPAA BAA, Flags Explorer, Observability Plus, Speed Insights, Web Analytics Plus.
Working Agreement
- Never pass as a flag. Export it as an environment variable and let the CLI read it natively.
- Check the environment for tokens before asking the user. Look in the current env and files first.
- Default to preview deployments. Only deploy to production when explicitly asked.
- Ask before pushing to git. Never push commits without the user's approval.
- Do not modify files directly. The CLI manages this directory. Reading them (e.g. to verify ) is fine.
- Do not curl/fetch deployed URLs to verify. Just return the link to the user.
- Use when structured output will help with follow-up steps.
- Use on commands that prompt for confirmation to avoid interactive blocking.
Troubleshooting
Token not found
Check the environment and any
files present:
bash
printenv | grep -i vercel
grep -i vercel .env 2>/dev/null
Authentication error
- The token may be expired or invalid.
- Verify: (uses from environment).
- Ask the user for a fresh token.
Wrong team
Verify the scope is correct:
bash
vercel whoami --scope <team-slug>
Build failure
Check the build logs:
bash
vercel inspect <deployment-url> --logs
Common causes:
- Missing dependencies — ensure is complete and committed.
- Missing environment variables — add with .
- Framework misconfiguration — check . Vercel auto-detects frameworks (Next.js, Remix, Vite, etc.) from ; override with if detection is wrong.
CLI not installed