Preface¶

Vercel CLI typically requires running vercel login in your local terminal first, which opens a browser to complete authentication before you can deploy, modify environment variables, or view build logs. This workflow works fine for daily development, but it breaks in CI environments, headless servers, or when running commands via Agents like Cursor, Claude Code, or Codex: interactive login will hang indefinitely with no one to click the browser link or enter credentials.

Vercel’s official documentation already provides a non-interactive authentication method: create an access token at Account Tokens, then use the VERCEL_TOKEN environment variable (or the --token CLI flag) to run the CLI. The vercel-cli-with-tokens skill formalizes this token workflow into steps executable by Agents: first locate the token, then identify the project and team, default to preview deployments, and also manage environment variables and domain names. It is complementary to the deploy-to-vercel skill in the same repository: the former focuses on token authentication and automation scenarios, while the latter covers interactive login and unauthenticated fallback in sandboxes.

This article is based on the original SKILL.md of this skill, cross-checked against the official Vercel CLI and Access Tokens documentation. The version in the skill metadata is 1.0.0, and the author field is vercel.

What It Is¶

vercel-cli-with-tokens is part of the vercel-labs/agent-skills repository, an official Vercel-maintained collection of Agent Skills following the standard SKILL.md format, which can be loaded by tools that support this specification such as Cursor, Codex CLI, and Claude Code.

The skill’s stated purpose is to use token-based authentication to deploy and manage projects via the Vercel CLI without relying on vercel login. The official trigger scenarios listed in its description include "deploy to vercel", "set up vercel", and "add environment variables to vercel". That is, when you ask an Agent to deploy, initialize a Vercel project, or add environment variables to a project, it should use the token-based path instead of prompting for a browser login.

The repository directory is at:
https://github.com/vercel-labs/agent-skills/tree/main/skills/vercel-cli-with-tokens

There is also a corresponding entry on skills.sh: https://www.skills.sh/vercel-labs/agent-skills/vercel-cli-with-tokens

Core Capabilities¶

Based on the SKILL.md and Vercel CLI documentation, this skill covers the following main functions:

1. Discover tokens in a fixed order: first check the VERCEL_TOKEN environment variable, then look for the same variable in .env, then search for any variables in .env with vercel in their name, and only ask the user for a token if none are found. The entry point for creating tokens is https://vercel.com/account/tokens.

2. Locate projects and teams: Read VERCEL_PROJECT_ID and VERCEL_ORG_ID, or extract the team slug from the project URL. When both IDs are present in the environment, the CLI will use them directly without needing to run vercel link. The official documentation also specifies that you should set both variables in CI or non-interactive environments to skip the linking step. Note: VERCEL_ORG_ID and VERCEL_PROJECT_ID must be used together; setting only one will throw an error.

3. Default to preview deployments: Unless the user explicitly requests a production deployment, only create preview deployments. If a project ID exists, run vercel deploy directly; if not, first run vercel link (prioritize --repo if a git remote exists), then choose between git push or CLI deployment.

4. Manage environment variables, view deployments, and configure domains: Includes commands like vercel env add/ls/pull/rm, vercel inspect, vercel logs, and vercel domains.

5. A set of constraints for Agents: The most important rule is never pass the token as a --token command line parameter, only export it as an environment variable for the CLI to read. The Vercel official documentation also recommends using VERCEL_TOKEN in CI because command line arguments appear in shell history and process lists. The official CLI still supports the --token flag, which takes precedence if both are provided; this skill is stricter than the CLI and explicitly prohibits using this parameter.

Installation and Enablement¶

The official way to install skill repositories is via the Vercel Labs skills CLI. To install only this single skill:

npx skills add vercel-labs/agent-skills --skill vercel-cli-with-tokens

You can also install the entire official collection:

npx skills add vercel-labs/agent-skills

npx skills add will detect your locally installed Agents and write the skill to the appropriate directory. By default, it installs at the project level; add the -g flag to install globally to your user directory for all projects. The standard directories for common tools are listed below (taken from the Supported Agents table in the vercel-labs/skills repository):

You can specify target Agents with the -a flag, for example, to install for both Claude Code and Cursor:

npx skills add vercel-labs/agent-skills --skill vercel-cli-with-tokens -a claude-code -a cursor

After installation, the Agent will load this skill when it detects tasks like deploying or configuring Vercel. You will also need the Vercel CLI installed locally:

npm install -g vercel
vercel --version

Where to Get the Token¶

Before running any vercel commands, the skill requires confirming the token source in the following order:

1. The VERCEL_TOKEN environment variable is already set:

    printenv VERCEL_TOKEN

If a value is returned, you can proceed to the next step.

2. If VERCEL_TOKEN is defined in your .env file, export it to your current shell session:

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

3. If you are using a different variable name in .env, the skill recommends searching for variables containing the vercel keyword and exporting their value as VERCEL_TOKEN. The original documentation notes that “Vercel tokens usually start with vca_”, but this should be cross-referenced with the official token format: Vercel announced in its February 2026 changelog that personal access tokens use the vcp prefix, while vca refers to App Access Tokens for Sign in with Vercel. The Access tokens dashboard also clarifies that personal access tokens start with vcp_ and are only displayed once after creation. Tokens for CLI/CI use should be created at https://vercel.com/account/tokens, and you should not treat vca_ app tokens as general CLI credentials.

4. If none of the above methods work, ask the user for a token. Tokens can be scoped to an account, team, or individual project; project-level tokens can only modify that specific project.

Once you have the token, only export it as an environment variable, never include it directly in command line arguments:

# INCORRECT: Token will appear in shell history and process lists
vercel deploy --token "vcp_your_token"

# CORRECT: CLI reads the token from the environment variable
export VERCEL_TOKEN="vcp_your_token"
vercel deploy

Deploy After Locating the Project¶

Once the token is ready, confirm the project and team IDs:

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

If you have a project URL such as https://vercel.com/my-team/my-project, the team slug is the first path segment my-team, which you will use with the --scope <team-slug> flag in subsequent commands.

If both IDs are available, export them to your shell environment, and the CLI will ignore the .vercel/ directory:

export VERCEL_ORG_ID="<org-id>"
export VERCEL_PROJECT_ID="<project-id>"

Deploy directly with an existing project ID (no linking required):

vercel deploy -y --no-wait

With team scope:

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

Only add the --prod flag if the user explicitly requests a production deployment:

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

The --no-wait flag returns the deployment URL immediately without waiting for the build to finish. You can check the deployment status with:

vercel inspect <deployment-url>

No project ID exists, you need to run vercel link first. First check your repository status, and do not use vercel project inspect or run vercel link in an unlinked directory to “detect” the project – these commands may trigger interactive prompts, or quietly complete the linking when run with -y. The safe detection commands the skill recommends are vercel ls (which lists deployments for the current scope in an unlinked directory) and vercel whoami from any location.

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

If you have a git remote, prioritize repository-level linking, which matches Vercel projects by the remote URL and is more reliable than the standard vercel link which matches by directory name. This command will generate a .vercel/repo.json file:

vercel link --repo --scope <team-slug> -y

If you do not have a git remote:

vercel link --scope <team-slug> -y

This will generate a .vercel/project.json file. You can also specify the project by name:

vercel link --project <project-name> --scope <team-slug> -y

After linking, if you have a git remote, the preferred workflow is to push to git to trigger Vercel’s automatic builds. You must ask the user for approval before pushing, as the skill prohibits running git push without prior consent. If there is no remote, continue with vercel deploy --scope <team-slug> -y --no-wait.

The .vercel/ directory is maintained by the Vercel CLI, you can read the orgId inside it to verify the team, but do not modify these files directly. You do not need this directory if you have already set both VERCEL_ORG_ID and VERCEL_PROJECT_ID in the environment.

Environment Variables, Logs, and Domains¶

The skill includes environment variable management under the same token workflow, all commands should include the --scope flag to avoid modifying the wrong team:

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

# Add to a specific environment: production / preview / development
echo "value" | vercel env add VAR_NAME production --scope <team-slug>

vercel env ls --scope <team-slug>
vercel env pull --scope <team-slug>
vercel env rm VAR_NAME --scope <team-slug> -y

For deployment troubleshooting:

vercel ls --format json --scope <team-slug>
vercel inspect <deployment-url>

# Build logs, requires Vercel CLI v35 or newer
vercel inspect <deployment-url> --logs

# Runtime request logs; follows logs by default, add --no-follow for a one-time snapshot
vercel logs <deployment-url>

For domain management:

vercel domains ls --scope <team-slug>

# If the project is already linked or specified via environment variables, only the domain is required
vercel domains add <domain> --scope <team-slug>

# For unlinked directories, you must also specify the project name
vercel domains add <domain> <project> --scope <team-slug>

When structured output is needed for subsequent steps, the skill requires adding the --format json flag. Commands that would normally prompt for confirmation should include -y to prevent the Agent from hanging on interactive prompts. After deployment completes, return the deployment URL to the user, do not use curl to request the live address for “validation”.

Use Cases and Notes¶

This skill is suitable for scenarios including: CI/CD pipelines, headless servers, and when Agents need to call the Vercel CLI locally or in a sandbox. It works best when tokens, project IDs, and team IDs are already stored in environment variables or .env as secrets.

You can compare it with the deploy-to-vercel skill in the same collection: the main workflow of deploy-to-vercel is vercel whoami, vercel login, choosing between git push or vercel deploy based on whether the project is already linked, and provides unauthenticated claimable deployment scripts in claude.ai/Codex sandboxes. vercel-cli-with-tokens skips the login page, specifically handling token and environment variable discovery, as well as the details of “deploy directly with an existing ID, run vercel link if no ID exists”. Both skills default to preview deployments, require user approval before pushing to git, and prohibit curling deployment URLs for validation.

There are several common pitfalls to watch out for:

1. Authentication failures. When the CLI reports Authentication required, first run vercel whoami to confirm that the VERCEL_TOKEN in the current environment is still valid; if the token is expired or revoked, you will need to create a new one in the dashboard. If you are targeting the wrong team, use vercel whoami --scope <team-slug> to verify.

2. Build failures. Use vercel inspect <deployment-url> --logs to view the build logs. Common causes listed in the skill include: incomplete or uncommitted package.json dependencies, missing environment variables, or incorrect framework detection. Vercel automatically detects frameworks like Next.js, Remix, and Vite from package.json, if detection fails, override it in vercel.json.

3. Do not accidentally link projects with detection commands. Do not run vercel project inspect or arbitrary vercel link commands in an unlinked directory.

4. Treat tokens as secrets. Tokens are only displayed once after creation; the official recommendation is to store them in a secret manager or environment variable, and never commit them to a repository. Vercel already performs secret scanning for credentials leaked to public GitHub repositories, gists, or npm packages, and may automatically revoke compromised tokens.

5. If the project is managed via Stripe Projects, the skill requires asking the user for approval before making paid or destructive plan changes. Upgrading will incur actual charges, while downgrading will remove seats. This is a separate action from deployment, but it is documented in the same SKILL.md.

Summary¶

vercel-cli-with-tokens solves a very specific problem: enabling Agents to call the Vercel CLI with VERCEL_TOKEN in environments where running vercel login is impossible or inappropriate, to complete preview deployments, environment variable management, and domain configuration. The key constraints are also clear: tokens should only be passed via environment variables, default to preview deployments, use org/project ID pairs, and ask for user approval before pushing to git remotes.

Official links:
- Skill directory: https://github.com/vercel-labs/agent-skills/tree/main/skills/vercel-cli-with-tokens
- Collection repository: https://github.com/vercel-labs/agent-skills
- skills.sh: https://www.skills.sh/vercel-labs/agent-skills
- Vercel CLI and Tokens: https://vercel.com/docs/cli, https://vercel.com/docs/cli/global-options
- Create access tokens: https://vercel.com/docs/accounts/access-tokens