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

printenv VERCEL_TOKEN

If this returns a value, you're ready. Skip to Step 2.

B) Token is in a .env file under VERCEL_TOKEN

grep '^VERCEL_TOKEN=' .env 2>/dev/null

If found, export it:

export VERCEL_TOKEN=$(grep '^VERCEL_TOKEN=' .env | cut -d= -f2-)

C) Token is in a .env file under a different name

grep -i 'vercel' .env 2>/dev/null

Inspect the output to identify which variable holds the token (Vercel tokens typically start with vca_), 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.

# 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

# Check environment
printenv VERCEL_PROJECT_ID
printenv VERCEL_ORG_ID

# Or check .env
grep -i 'vercel' .env 2>/dev/null

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. Both parameters must be set together.

CLI Setup

npm install -g vercel
vercel --version

Deploying a Project

Always deploy as preview unless the user explicitly requests production.

Quick Deploy (project ID available)

vercel deploy -y --no-wait
vercel deploy --scope <team-slug> -y --no-wait

# Production (only when explicitly requested):
vercel deploy --prod --scope <team-slug> -y --no-wait

# Check status:
vercel inspect <deployment-url>

Full Deploy Flow (linking required)

# Check project state first
git remote get-url origin 2>/dev/null
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null

# Link with git remote (preferred)
vercel link --repo --scope <team-slug> -y

# Link without git remote
vercel link --scope <team-slug> -y

# Link to specific project by name
vercel link --project <project-name> --scope <team-slug> -y

Managing Environment Variables

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

# Set for a specific environment
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

# 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
vercel logs <deployment-url>

Managing Domains

# List domains
vercel domains ls --scope <team-slug>

# Add a domain (linked directory)
vercel domains add <domain> --scope <team-slug>

# Add a domain (unlinked directory — requires project name)
vercel domains add <domain> <project> --scope <team-slug>

Troubleshooting

Token not found

printenv | grep -i vercel
grep -i vercel .env 2>/dev/null

Authentication error

Verify: vercel whoami (uses VERCEL_TOKEN from environment). Ask for a fresh token if expired.

Wrong team

vercel whoami --scope <team-slug>

Build failure

vercel inspect <deployment-url> --logs

Common causes: missing dependencies, missing environment variables, framework misconfiguration.

Working Agreement

• Never pass VERCEL_TOKEN as a --token flag. Export it as an environment variable.
• Check the environment for tokens before asking the user.
• Default to preview deployments.
• Ask before pushing to git.
• Do not modify .vercel/ files directly.
• Use --format json for structured output.
• Use -y on commands that prompt for confirmation.

Installation

npx skills add https://github.com/vercel-labs/agent-skills --skill vercel-cli-with-tokens

Mirrored from https://github.com/vercel-labs/agent-skills — original author: vercel-labs, license: MIT. This is an unclaimed mirror. Content and ownership transfer to the author when they claim this account.