--- id: daily-vercel-cli-with-tokens name: "vercel-cli-with-tokens" url: https://skills.yangsir.net/skill/daily-vercel-cli-with-tokens author: vercel-labs domain: cloud-infra tags: ["vercel", "deployment", "token-auth", "cli-management"] install_count: 37500 rating: 4.60 (137 reviews) github: https://github.com/vercel-labs/agent-skills --- # vercel-cli-with-tokens > 使用CLI通过Token认证方式在Vercel上部署和管理项目，支持完整的项目生命周期管理 **Stats**: 37,500 installs · 4.6/5 (137 reviews) ## Before / After 对比 ### Vercel项目部署 **Before**: 通过Vercel网页控制台手动配置部署，或使用交互式CLI登录操作，自动化流水线中难以集成，CI/CD环境下认证方式受限 **After**: 基于Token认证的CLI操作无需交互式登录，完美集成CI/CD流水线，项目部署、环境管理和配置更新全部命令行完成 | Metric | Before | After | Change | |---|---|---|---| | 部署操作耗时 | 10min | 2min | -80% | ## Readme # 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 --token "$VERCEL_TOKEN" ``` ### Scoping to a Team Use `--scope` to target a specific team. Accepts a **team slug** or **team ID** (`team_...`): ``` vercel --token "$VERCEL_TOKEN" --scope ``` 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 --project ``` 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 --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 --project -y --no-wait ``` Check status: ``` vercel inspect --token "$VERCEL_TOKEN" ``` Production deploy (only when explicitly requested): ``` vercel deploy --prod --token "$VERCEL_TOKEN" --scope --project -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 -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 -y ``` Creates `.vercel/project.json`. **Link to a specific existing project by name:** ``` vercel link --project --token "$VERCEL_TOKEN" --scope -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: " 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 ``` The latest entry in the `deployments` array has the preview URL. **B) CLI Deploy — no git remote** ``` vercel deploy --token "$VERCEL_TOKEN" --scope -y --no-wait ``` `--no-wait` returns immediately with the deployment URL. Check status: ``` vercel inspect --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 cd ``` - Link to Vercel: ``` vercel link --repo --token "$VERCEL_TOKEN" --scope -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 # Set for a specific environment (production, preview, development) echo "value" | vercel env add VAR_NAME production --token "$VERCEL_TOKEN" --scope # List environment variables vercel env ls --token "$VERCEL_TOKEN" --scope # Pull env vars to local .env file vercel env pull --token "$VERCEL_TOKEN" --scope # Remove a variable vercel env rm VAR_NAME --token "$VERCEL_TOKEN" --scope -y ``` ## Inspecting Deployments ``` # List recent deployments vercel ls --format json --token "$VERCEL_TOKEN" --scope # Inspect a specific deployment vercel inspect --token "$VERCEL_TOKEN" # View build logs vercel logs --token "$VERCEL_TOKEN" ``` ## Managing Domains ``` # List domains vercel domains ls --token "$VERCEL_TOKEN" --scope # Add a domain to the project vercel domains add --token "$VERCEL_TOKEN" --scope ``` ## 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 ``` ### Build Failure Check the build logs: ``` vercel logs --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 Installs198Repository[vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills)GitHub Stars23.3KFirst Seen1 day agoSecurity Audits[Gen Agent Trust HubPass](/vercel-labs/agent-skills/vercel-cli-with-tokens/security/agent-trust-hub)[SocketPass](/vercel-labs/agent-skills/vercel-cli-with-tokens/security/socket)[SnykWarn](/vercel-labs/agent-skills/vercel-cli-with-tokens/security/snyk)Installed oncodex178gemini-cli176opencode176cursor175github-copilot174amp173 --- *Source: https://skills.yangsir.net/skill/daily-vercel-cli-with-tokens* *Markdown mirror: https://skills.yangsir.net/api/skill/daily-vercel-cli-with-tokens/markdown*