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".
One skill from vercel-labs-agent-skills. Installed with the plugin, it fires itself as you prompt.
Installs just this skill. Get the whole plugin for auto-invocation.
SKILL.md
vercel-cli-with-tokens.SKILL.md
---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_`):
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`):
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.
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.
