Vercel Cli With Tokens

vercel-labs/agent-skills/skills/vercel-cli-with-tokens

作者 vercel-labs1a2c79d4e6c4a2283dc2c614b6538cbe1ed5ca62无许可证34K 个星标收录于 2026年11月20日更新于 2026年11月20日仓库今天更新

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

精选仅含说明DevOps 与云端
AI 生成的概览

使用令牌认证通过 Vercel CLI 部署和管理 Vercel 项目,无需交互式登录。

功能
指导代理在环境变量或 .env 文件中查找 Vercel 访问令牌,安全地导出它,并确定项目与团队范围。随后涵盖安装 CLI、部署预览或生产环境、关联项目、管理环境变量、查看部署与日志以及处理域名。还包含故障排查步骤和 Stripe Projects 套餐变更说明。
适用场景
适用于使用访问令牌以非交互方式部署或管理 Vercel 项目的场景,例如部署到 Vercel、为仓库配置 Vercel,或向 Vercel 项目添加环境变量。
运行要求
需要 Node.js 与 npm 以全局安装 Vercel CLI、一个 Vercel 访问令牌(通常以 vca_ 开头),可选提供 VERCEL_ORG_ID 与 VERCEL_PROJECT_ID 以及团队 slug。需要访问 Vercel 的网络;不附带脚本。

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

bash
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

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

If found, export it:

bash
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_):

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

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

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

bash
# Bad — token visible in shell history and process listingsvercel deploy --token "vca_abc123"
# Good — CLI reads VERCEL_TOKEN from the environmentexport 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.

bash
# Check environmentprintenv VERCEL_PROJECT_IDprintenv VERCEL_ORG_ID
# Or check .envgrep -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:

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

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

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

CLI Setup

Ensure the Vercel CLI is installed and up to date:

bash
npm install -g vercelvercel --version

Deploying a Project

Always deploy as preview unless the user explicitly requests production. Choose a method based on what you have available.

Quick Deploy (have project ID — no linking needed)

When VERCEL_TOKEN and VERCEL_PROJECT_ID are set in the environment, deploy directly:

bash
vercel deploy -y --no-wait

With a team scope (either via VERCEL_ORG_ID or --scope):

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

Production (only when explicitly requested):

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

Check status:

bash
vercel inspect <deployment-url>

Full Deploy Flow (no project ID — need to link)

Use this when you have a token and team but no pre-existing project ID.

Check project state first
bash
# 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/null
Link the project

With git remote (preferred):

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

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:

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

Creates .vercel/project.json.

Link to a specific project by name:

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

If the project is already linked, check orgId in .vercel/project.json or .vercel/repo.json to verify it matches the intended team.

Deploy after linking

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

Git pushes trigger automatic Vercel deployments.

  1. Ask the user before pushing. Never push without explicit approval.
  2. Commit and push:
    bash
    git add .git commit -m "deploy: <description of changes>"git push
  3. Vercel builds automatically. Non-production branches get preview deployments.
  4. Retrieve the deployment URL:
    bash
    sleep 5vercel ls --format json --scope <team-slug>
    Find the latest entry in the deployments array.

B) CLI Deploy — no git remote

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

Check status:

bash
vercel inspect <deployment-url>

Deploying from a Remote Repository (code not cloned locally)

  1. Clone the repository:
    bash
    git clone <repo-url>cd <repo-name>
  2. Link to Vercel:
    bash
    vercel link --repo --scope <team-slug> -y
  3. 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.

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.

Managing Environment Variables

bash
# Set for all environmentsecho "value" | vercel env add VAR_NAME --scope <team-slug>
# Set for a specific environment (production, preview, development)echo "value" | vercel env add VAR_NAME production --scope <team-slug>
# List environment variablesvercel env ls --scope <team-slug>
# Pull env vars to local .env.local filevercel env pull --scope <team-slug>
# Remove a variablevercel env rm VAR_NAME --scope <team-slug> -y

Inspecting Deployments

bash
# List recent deploymentsvercel ls --format json --scope <team-slug>
# Inspect a specific deploymentvercel inspect <deployment-url>
# View build logs (requires Vercel CLI v35+)vercel inspect <deployment-url> --logs
# View runtime request logs (follows live by default; add --no-follow for a one-shot snapshot)vercel logs <deployment-url>

Managing Domains

bash
# List domainsvercel domains ls --scope <team-slug>
# Add a domain to the project — linked or env-linked directory (1 arg)vercel domains add <domain> --scope <team-slug>
# Add a domain — unlinked directory (requires <project> positional)vercel domains add <domain> <project> --scope <team-slug>

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.

Troubleshooting

Token not found

Check the environment and any .env files present:

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

Authentication error

If the CLI fails with Authentication required:

  • The token may be expired or invalid.
  • Verify: vercel whoami (uses VERCEL_TOKEN from environment).
  • Ask the user for a fresh token.

Wrong team

Verify the scope is correct:

bash
vercel whoami --scope <team-slug>

Build failure

Check the build logs:

bash
vercel inspect <deployment-url> --logs

Common causes:

  • Missing dependencies — ensure package.json is complete and committed.
  • Missing environment variables — add with vercel env add.
  • Framework misconfiguration — check vercel.json. Vercel auto-detects frameworks (Next.js, Remix, Vite, etc.) from package.json; override with vercel.json if detection is wrong.

CLI not installed

bash
npm install -g vercel

来源与署名

来源:vercel-labs/agent-skills位于skills/vercel-cli-with-tokens提交1a2c79d

许可证: 无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

在 README 中添加徽章

向读者展示该技能已收录于 SourceWeft,徽章链接到本页。

“Listed on SourceWeft”徽章预览
[![Listed on SourceWeft](https://sourceweft.com/badge/skills/gh-vercel-labs-agent-skills-vercel-cli-with-tokens.svg)](https://sourceweft.com/skills/gh-vercel-labs-agent-skills-vercel-cli-with-tokens?utm_source=readme&utm_medium=badge)

举报或申请下架