Vercel CLI with Tokens
Deploy and manage projects on Vercel using the CLI with token-based authentication, without relying on vercel login.
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) VERCEL_TOKEN is already set in the environment
If this returns a value, you're ready. Skip to Step 2.
B) Token is in a .env file under VERCEL_TOKEN
If found, export it:
C) Token is in a .env file under a different name
Look for any variable that looks like a Vercel token (Vercel tokens typically start with vca_):
Inspect the output to identify which variable holds the token, then export it as VERCEL_TOKEN:
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 VERCEL_TOKEN is exported as an environment variable, the Vercel CLI reads it natively — do not pass it as a --token flag. Putting secrets in command-line arguments exposes them in shell history and process listings.
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 vercel link.
If you have a project URL (e.g. https://vercel.com/my-team/my-project), extract the team slug:
If you have both VERCEL_ORG_ID and VERCEL_PROJECT_ID in your environment, export them — the CLI will use these automatically and skip any .vercel/ directory:
Note: VERCEL_ORG_ID and VERCEL_PROJECT_ID must be set together — setting only one causes an error.
CLI Setup
Ensure the Vercel CLI is installed and up to date:
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 VERCEL_TOKEN and VERCEL_PROJECT_ID are set in the environment, deploy directly:
With a team scope (either via VERCEL_ORG_ID or --scope):
Production (only when explicitly requested):
Check status:
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
Link the project
With git remote (preferred):
Reads the git remote and connects to the matching Vercel project. Creates .vercel/repo.json. More reliable than plain vercel link, which matches by directory name.
Without git remote:
Creates .vercel/project.json.
Link to a specific project by name:
If the project is already linked, check orgId in .vercel/project.json or .vercel/repo.json 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:
- Vercel builds automatically. Non-production branches get preview deployments.
- Retrieve the deployment URL:
Find the latest entry in the
deploymentsarray.
B) CLI Deploy — no git remote
Check status:
Deploying from a Remote Repository (code not cloned locally)
- Clone the repository:
- Link to Vercel:
- Deploy via git push (if you have push access) or CLI deploy.
About .vercel/ Directory
A linked project has either:
.vercel/project.json— fromvercel link. ContainsprojectIdandorgId..vercel/repo.json— fromvercel link --repo. ContainsorgId,remoteName, and aprojectsmap.
Not needed when VERCEL_ORG_ID + VERCEL_PROJECT_ID are both set in the environment.
Do NOT run vercel project inspect or vercel link in an unlinked directory to detect state — they will interactively prompt or silently link as a side-effect. vercel ls is safe (in an unlinked directory it defaults to showing all deployments for the scope). vercel whoami is safe anywhere.
Managing Environment Variables
Inspecting Deployments
Managing Domains
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 (vercel-plan); substitute the actual name if it was renamed at stripe projects add time.
- Upgrade to Pro:
stripe projects add vercel/pro(orstripe 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.
Full details: https://vercel.com/docs/plans/pro-plan
Working Agreement
- Never pass
VERCEL_TOKENas a--tokenflag. 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
.envfiles 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
.vercel/files directly. The CLI manages this directory. Reading them (e.g. to verifyorgId) is fine. - Do not curl/fetch deployed URLs to verify. Just return the link to the user.
- Use
--format jsonwhen structured output will help with follow-up steps. - Use
-yon commands that prompt for confirmation to avoid interactive blocking.
Troubleshooting
Token not found
Check the environment and any .env files present:
Authentication error
If the CLI fails with Authentication required:
- The token may be expired or invalid.
- Verify:
vercel whoami(usesVERCEL_TOKENfrom environment). - Ask the user for a fresh token.
Wrong team
Verify the scope is correct:
Build failure
Check the build logs:
Common causes:
- Missing dependencies — ensure
package.jsonis complete and committed. - Missing environment variables — add with
vercel env add. - Framework misconfiguration — check
vercel.json. Vercel auto-detects frameworks (Next.js, Remix, Vite, etc.) frompackage.json; override withvercel.jsonif detection is wrong.


