vercel-cli-with-tokens

Vercel CLI with Tokens

Deploy and manage projects on Vercel using the CLI with token-based authentication. Use this skill when you have a Vercel access token and need to operate without interactive login.

Authentication

Never run vercel login. Always use token-based auth via the --token flag or VERCEL_TOKEN environment variable. This ensures the correct account is used even if another Vercel account is logged in locally.

vercel <command> --token "$VERCEL_TOKEN"

Scoping to a Team

Use --scope to target a specific team. Accepts a team slug or team ID (team_...):

vercel <command> --token "$VERCEL_TOKEN" --scope <team-slug-or-id>

Not required if the project is already linked (.vercel/project.json provides the org context) or if VERCEL_ORG_ID is set.

Targeting a Project

Use --project to target a specific project without needing vercel link. Accepts a project name or project ID (prj_...):

vercel deploy --token "$VERCEL_TOKEN" --scope <team> --project <project-name-or-id>

This is the simplest path when you already have a project ID — no .vercel/ directory needed.

Environment Variable Alternative

Instead of flags, you can set these environment variables. The CLI recognizes them natively:

Variable Purpose Equivalent flag

VERCEL_TOKEN Auth token --token

VERCEL_ORG_ID Team/org ID --scope

VERCEL_PROJECT_ID Project ID --project

VERCEL_ORG_ID and VERCEL_PROJECT_ID must be set together — setting only one causes an error. When both are set, the CLI skips .vercel/project.json entirely.

Resolution Precedence

Token: --token flag > VERCEL_TOKEN env var > stored auth in config.

Team/scope: --scope flag > scope in vercel.json > currentTeam in global config > VERCEL_ORG_ID.

Project: --project flag > VERCEL_PROJECT_ID env var > .vercel/project.json > interactive prompt.

CLI Setup

npm install -g vercel
vercel --version

Or use npx for one-off commands:

npx vercel <command> --token "$VERCEL_TOKEN"

Deploying a Project

Always deploy as preview unless the user explicitly requests production.

Quick Deploy (have project ID — no linking needed)

When you already have a project ID (e.g., prj_...), deploy directly:

vercel deploy --token "$VERCEL_TOKEN" --scope <team> --project <project-id> -y --no-wait

Check status:

vercel inspect <deployment-url> --token "$VERCEL_TOKEN"

Production deploy (only when explicitly requested):

vercel deploy --prod --token "$VERCEL_TOKEN" --scope <team> --project <project-id> -y --no-wait

Full Deploy Flow (no project ID)

Use this when you have a token and team but need to create or find a project.

Step 1: Determine Project State

# 1. Does the project have a git remote?
git remote get-url origin 2>/dev/null

# 2. Is it already linked to a Vercel project?
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null

Step 2: Link the Project

If no .vercel/project.json or .vercel/repo.json exists, link first.

With git remote (preferred):

vercel link --repo --token "$VERCEL_TOKEN" --scope <team> -y

Reads the git remote and connects to the matching Vercel project. Creates .vercel/repo.json. More reliable than vercel link without --repo, which matches by directory name.

Without git remote:

vercel link --token "$VERCEL_TOKEN" --scope <team> -y

Creates .vercel/project.json.

Link to a specific existing project by name:

vercel link --project <project-name> --token "$VERCEL_TOKEN" --scope <team> -y

If the project is already linked, check orgId in .vercel/project.json or .vercel/repo.json to verify it matches the intended team. If not, re-link with the correct --scope.

Step 3: Deploy

A) Git Push Deploy — has git remote (preferred)

The best long-term setup. Git pushes trigger automatic Vercel deployments.

• Ask the user before pushing. Never push without explicit approval.

• Commit and push:

git add .
git commit -m "deploy: <description of changes>"
git push

• Vercel builds automatically. Non-production branches get preview deployments; the production branch (usually main) gets a production deployment.

• Retrieve the deployment URL:

sleep 5
vercel ls --format json --token "$VERCEL_TOKEN" --scope <team>

The latest entry in the deployments array has the preview URL.

B) CLI Deploy — no git remote

vercel deploy --token "$VERCEL_TOKEN" --scope <team> -y --no-wait

--no-wait returns immediately with the deployment URL. Check status:

vercel inspect <deployment-url> --token "$VERCEL_TOKEN"

Deploying from a Remote Repository

If the user wants to deploy code from a remote that isn't cloned locally:

• Clone the repository:

git clone <repo-url>
cd <repo-name>

• Link to Vercel:

vercel link --repo --token "$VERCEL_TOKEN" --scope <team> -y

• Deploy via git push (if you have push access) or CLI deploy.

About .vercel/ Directory

A 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.

Either file means the project is linked. Not needed when using --project flag or VERCEL_ORG_ID + VERCEL_PROJECT_ID env vars.

Do NOT run vercel project inspect, vercel ls, or vercel link in an unlinked directory to detect state — without .vercel/, they will interactively prompt or silently link as a side-effect. Only vercel whoami --token "$VERCEL_TOKEN" is safe to run anywhere.

Managing Environment Variables

Run from a linked project directory, or use --project to target a specific project.

# Set for all environments
echo "value" | vercel env add VAR_NAME --token "$VERCEL_TOKEN" --scope <team>

# Set for a specific environment (production, preview, development)
echo "value" | vercel env add VAR_NAME production --token "$VERCEL_TOKEN" --scope <team>

# List environment variables
vercel env ls --token "$VERCEL_TOKEN" --scope <team>

# Pull env vars to local .env file
vercel env pull --token "$VERCEL_TOKEN" --scope <team>

# Remove a variable
vercel env rm VAR_NAME --token "$VERCEL_TOKEN" --scope <team> -y

Inspecting Deployments

# List recent deployments
vercel ls --format json --token "$VERCEL_TOKEN" --scope <team>

# Inspect a specific deployment
vercel inspect <deployment-url> --token "$VERCEL_TOKEN"

# View build logs
vercel logs <deployment-url> --token "$VERCEL_TOKEN"

Managing Domains

# List domains
vercel domains ls --token "$VERCEL_TOKEN" --scope <team>

# Add a domain to the project
vercel domains add <domain> --token "$VERCEL_TOKEN" --scope <team>

Working Agreement

• Always use --token on every Vercel CLI command. Never rely on local login state.

• Use --scope and/or --project to target the correct team and project.

• Do not run vercel login. Authentication is handled entirely by the access token.

• 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 read or modify .vercel/ files directly. The CLI manages this directory.

• Do not curl/fetch deployed URLs to verify. Just return the link to the user.

• Use --format json when structured output will help with follow-up steps (e.g., vercel ls).

• Use -y on commands that prompt for confirmation to avoid interactive blocking.

Troubleshooting

Authentication Error

If commands fail with Authentication required or similar:

• The token may be expired or revoked. Ask the user for a fresh token or check the token source.

• Verify the token is valid: vercel whoami --token "$VERCEL_TOKEN"

Wrong Team

If deployments appear under the wrong team, verify --scope is correct:

vercel whoami --token "$VERCEL_TOKEN" --scope <team>

Build Failure

Check the build logs:

vercel logs <deployment-url> --token "$VERCEL_TOKEN"

Common causes:

• Missing dependencies — ensure package.json is complete and committed.

• Missing environment variables — add them with vercel env add.

• Framework misconfiguration — check vercel.json or framework-specific settings.

• Vercel auto-detects frameworks (Next.js, Remix, Vite, etc.) from package.json. Override with a vercel.json if detection is wrong.

CLI Not Installed

npm install -g vercel

Weekly Installs198Repositoryvercel-labs/agent-skillsGitHub Stars23.3KFirst Seen1 day agoSecurity AuditsGen Agent Trust HubPassSocketPassSnykWarnInstalled oncodex178gemini-cli176opencode176cursor175github-copilot174amp173