vercel-cli-with-tokens · 스킬 지원 에이전트
토큰을 사용하는 CLI 환경에서 프로젝트와 배포 설정을 관리합니다.
브라우저 로그인 대신 토큰을 사용하는 CLI 환경에서 Vercel 프로젝트를 관리하는 스킬입니다. 로컬 인증 환경과 대상 프로젝트를 기준으로 설정과 배포 작업을 다룹니다.
이미 준비한 인증 환경과 수행할 작업을 알려주세요. 어느 프로젝트에 어떤 변경을 하는지 구분하며 CLI 작업의 실행 방법과 결과를 정리할 수 있습니다.
“로컬의 토큰 인증 환경으로 이 Vercel 프로젝트 설정을 확인하고 싶어. 대상 프로젝트를 구분하고 필요한 CLI 작업을 정리해줘.”
받을 수 있는 결과설정·배포 작업 결과
Agent Skills를 지원하는 에이전트에 스킬을 추가하세요. 배포 작업은 Vercel 계정과 프로젝트 접근 권한이 필요합니다.
Node.js가 설치된 터미널에서 실행하고 대상 에이전트를 선택하세요. 스킬 폴더와 보조 파일을 함께 설치합니다. 설치 후 새 세션에서 작업을 요청하세요.
npx skills add https://github.com/vercel-labs/agent-skills/tree/063bee94c3f4df8453406c830b0a7df0f2860278/skills/vercel-cli-with-tokens
“vercel-cli-with-tokens 스킬을 사용해줘. 입력 자료: Vercel 프로젝트와 로컬 인증 환경”처럼 요청하세요. 위의 예시를 내 자료에 맞게 바꿔도 좋아요.
예상 결과는 ‘설정·배포 작업 결과’입니다. 필요한 내용이 포함됐는지 확인하세요. 입력 자료의 사실·숫자와 결과를 대조하고, 부족한 부분을 이어서 요청하세요.
제작자 원본 2026-10-04 확인 · 설치 안내 2026-10-04 확인 · 실제 설치·실행 미검증
모델 사용 요금과 연결 앱 요금은 이용 중인 서비스의 정책을 따릅니다.
설치 안내 출처--- name: vercel-cli-with-tokens description: 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". metadata: author: vercel version: "1.0.0" --- # 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`--- name: vercel-cli-with-tokens description: 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". metadata: author: vercel version: "1.0.0" --- # 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 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`. ```bash # 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: ```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 vercel vercel --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 5 vercel 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 environments echo "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 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 ```bash # 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 (follows live by default; add --no-follow for a one-shot snapshot) vercel logs <deployment-url> ``` ## Managing Domains ```bash # List domains vercel 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 vercel grep -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 ```
Original skill: vercel-labs/agent-skills/skills/vercel-cli-with-tokens/SKILL.md Source: https://github.com/vercel-labs/agent-skills/blob/063bee94c3f4df8453406c830b0a7df0f2860278/skills/vercel-cli-with-tokens/SKILL.md License: MIT MIT License Attribution: vercel-labs/agent-skills (MIT license declared in the repository README) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
SKILL.md 본문입니다. 원문에서 참조하는 스크립트·보조 파일은 원본 패키지에 포함되어 있습니다.