vercel-cli-with-tokens

by vercel

Deploy and manage projects on Vercel using token-based authentication. Use when working with Vercel CLI using access tokens rather than interactive login —… npx skills add https://github.com/vercel-labs/claude-skills --skill vercel-cli-with-tokens Download ZIPGitHub28.6k

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

Look for any variable that looks like a Vercel token (Vercel tokens typically start with vca_):

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

Inspect the output to identify which variable holds the token, then export it as VERCEL_TOKEN:

export VERCEL_TOKEN=$(grep '^ =' .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 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.

# 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 vercel link.

# 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:

# 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 VERCEL_ORG_ID and VERCEL_PROJECT_ID in your environment, export them — the CLI will use these automatically and skip any .vercel/ directory:

export VERCEL_ORG_ID=" "
export VERCEL_PROJECT_ID=" "

Note: VERCEL_ORG_ID and VERCEL_PROJECT_ID must be set together — setting only one causes an error.

Managing Environment Variables

# Set for all environments
echo "value" | vercel env add VAR_NAME --scope 

# Set for a specific environment (production, preview, development)
echo "value" | vercel env add VAR_NAME production --scope 

# List environment variables
vercel env ls --scope 

# Pull env vars to local .env.local file
vercel env pull --scope 

# Remove a variable
vercel env rm VAR_NAME --scope -y

Managing Domains

# List domains
vercel domains ls --scope 

# Add a domain to the project — linked or env-linked directory (1 arg)
vercel domains add --scope 

# Add a domain — unlinked directory (requires positional)
vercel domains add --scope 

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 (or 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.

Full details: https://vercel.com/docs/plans/pro-plan

Working Agreement

• Never pass VERCEL_TOKEN as a --token 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 .env 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 .vercel/ files directly. The CLI manages this directory. Reading them (e.g. to verify orgId) is fine.

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

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