npx skills add ...
npx skills add vercel-labs/agent-skills --skill vercel-cli-with-tokens
npx skills add vercel-labs/agent-skills --skill vercel-cli-with-tokens
Deploy and manage projects on Vercel using token-based authentication. Use when working with Vercel CLI using access tokens rather than interactive login — e.g. "deploy to vercel", "set up vercel", "add environment variables to vercel".
The same skill content is published under more than one repo. The install counts are split across them; any of these commands works.
Deploy and manage projects on Vercel using the CLI with token-based authentication, without relying on vercel login.
Before running any Vercel CLI commands, identify where the token is coming from. Work through these scenarios in order:
VERCEL_TOKEN is already set in the environmentIf this returns a value, you're ready. Skip to Step 2.
.env file under VERCEL_TOKENIf found, export it:
.env file under a different nameLook 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:
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.
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.
Ensure the Vercel CLI is installed and up to date:
Always deploy as preview unless the user explicitly requests production. Choose a method based on what you have available.
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:
Use this when you have a token and team but no pre-existing project ID.
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.
A) Git Push Deploy — has git remote (preferred)
Git pushes trigger automatic Vercel deployments.
deployments array.B) CLI Deploy — no git remote
Check status:
.vercel/ DirectoryA linked project has either:
.vercel/project.json — from vercel link. Contains projectId and orgId..vercel/repo.json — from vercel link --repo. Contains orgId, remoteName, and a projects map.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.
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.
stripe projects add vercel/pro (or stripe projects upgrade vercel-plan pro)stripe projects downgrade vercel-plan hobbyFull details: https://vercel.com/docs/plans/pro-plan
VERCEL_TOKEN as a --token flag. Export it as an environment variable and let the CLI read it natively..env files first..vercel/ files directly. The CLI manages this directory. Reading them (e.g. to verify orgId) is fine.--format json when structured output will help with follow-up steps.-y on commands that prompt for confirmation to avoid interactive blocking.Check the environment and any .env files present:
If the CLI fails with Authentication required:
vercel whoami (uses VERCEL_TOKEN from environment).Verify the scope is correct:
Check the build logs:
Common causes:
package.json is complete and committed.vercel env add.vercel.json. Vercel auto-detects frameworks (Next.js, Remix, Vite, etc.) from package.json; override with vercel.json if detection is wrong.export VERCEL_TOKEN=$(grep '^<VARIABLE_NAME>=' .env | cut -d= -f2-)# 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# Check environment
printenv VERCEL_PROJECT_ID
printenv VERCEL_ORG_ID
# Or check .env
grep -i 'vercel' .env 2>/dev/null# e.g. "my-team" from "https://vercel.com/my-team/my-project"
echo "$PROJECT_URL" | sed 's|https://vercel.com/||' | cut -d/ -f1export VERCEL_ORG_ID="<org-id>"
export VERCEL_PROJECT_ID="<project-id>"npm install -g vercel
vercel --versionvercel deploy -y --no-waitvercel deploy --scope <team-slug> -y --no-waitvercel deploy --scope <team-slug> -y --no-waitvercel deploy --prod --scope <team-slug> -y --no-waitvercel inspect <deployment-url>vercel inspect <deployment-url># 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/nullvercel link --repo --scope <team-slug> -yvercel link --repo --scope <team-slug> -yvercel link --scope <team-slug> -yvercel link --project <project-name> --scope <team-slug> -y