vercel-cli-with-tokens

Name: vercel-cli-with-tokens
Author: vercel-labs

byvercel-labs· 154 skills

Installs

75k

Stars

29k

Forks

2.6k

How to install vercel-cli-with-tokens?

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

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

Installs into the current project.

›Prefer a prompt? Paste this to your agent

Use this skill

Run `npx skills use "https://github.com/vercel-labs/agent-skills" --skill "vercel-labs/agent-skills/vercel-cli-with-tokens"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the whole pack

Use the skills in "https://github.com/vercel-labs/agent-skills" that are relevant to the current task. Run `npx skills add "https://github.com/vercel-labs/agent-skills"` and select the relevant skills, then follow their instructions.

Files · 1

View on GitHub

SKILL.md

1	# Vercel CLI with Tokens
2
3	Deploy and manage projects on Vercel using the CLI with token-based authentication, without relying on `vercel login`.
4
5	## Step 1: Locate the Vercel Token
6
7	Before running any Vercel CLI commands, identify where the token is coming from. Work through these scenarios in order:
8
9	### A) `VERCEL_TOKEN` is already set in the environment
10
11	```bash
12	printenv VERCEL_TOKEN
13	```
14
15	If this returns a value, you're ready. Skip to Step 2.
16
17	### B) Token is in a `.env` file under `VERCEL_TOKEN`
18
19	```bash
20	grep '^VERCEL_TOKEN=' .env 2>/dev/null
21	```
22
23	If found, export it:
24
25	```bash
26	export VERCEL_TOKEN=$(grep '^VERCEL_TOKEN=' .env \| cut -d= -f2-)
27	```
28
29	### C) Token is in a `.env` file under a different name
30
31	Look for any variable that looks like a Vercel token (Vercel tokens typically start with `vca_`):
32
33	```bash
34	grep -i 'vercel' .env 2>/dev/null
35	```
36
37	Inspect the output to identify which variable holds the token, then export it as `VERCEL_TOKEN`:
38
39	```bash
40	export VERCEL_TOKEN=$(grep '^<VARIABLE_NAME>=' .env \| cut -d= -f2-)
41	```
42
43	### D) No token found — ask the user
44
45	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.
46
47	---
48
49	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.
50
51	```bash
52	# Bad — token visible in shell history and process listings
53	vercel deploy --token "vca_abc123"
54
55	# Good — CLI reads VERCEL_TOKEN from the environment
56	export VERCEL_TOKEN="vca_abc123"
57	vercel deploy
58	```
59
60	## Step 2: Locate the Project and Team
61
62	Similarly, check for the project ID and team scope. These let the CLI target the right project without needing `vercel link`.
63
64	```bash
65	# Check environment
66	printenv VERCEL_PROJECT_ID
67	printenv VERCEL_ORG_ID
68
69	# Or check .env
70	grep -i 'vercel' .env 2>/dev/null
71	```
72
73	If you have a project URL (e.g. `https://vercel.com/my-team/my-project`), extract the team slug:
74
75	```bash
76	# e.g. "my-team" from "https://vercel.com/my-team/my-project"
77	echo "$PROJECT_URL" \| sed 's\|https://vercel.com/\|\|' \| cut -d/ -f1
78	```
79
80	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:
81
82	```bash
83	export VERCEL_ORG_ID="<org-id>"
84	export VERCEL_PROJECT_ID="<project-id>"
85	```
86
87	Note: `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` must be set together — setting only one causes an error.
88
89	## CLI Setup
90
91	Ensure the Vercel CLI is installed and up to date:
92
93	```bash
94	npm install -g vercel
95	vercel --version
96	```
97
98	## Deploying a Project
99
100	Always deploy as preview unless the user explicitly requests production. Choose a method based on what you have available.
101
102	### Quick Deploy (have project ID — no linking needed)
103
104	When `VERCEL_TOKEN` and `VERCEL_PROJECT_ID` are set in the environment, deploy directly:
105
106	```bash
107	vercel deploy -y --no-wait
108	```
109
110	With a team scope (either via `VERCEL_ORG_ID` or `--scope`):
111
112	```bash
113	vercel deploy --scope <team-slug> -y --no-wait
114	```
115
116	Production (only when explicitly requested):
117
118	```bash
119	vercel deploy --prod --scope <team-slug> -y --no-wait
120	```
121
122	Check status:
123
124	```bash
125	vercel inspect <deployment-url>
126	```
127
128	### Full Deploy Flow (no project ID — need to link)
129
130	Use this when you have a token and team but no pre-existing project ID.
131
132	#### Check project state first
133
134	```bash
135	# Does the project have a git remote?
136	git remote get-url origin 2>/dev/null
137
138	# Is it already linked to a Vercel project?
139	cat .vercel/project.json 2>/dev/null \|\| cat .vercel/repo.json 2>/dev/null
140	```
141
142	#### Link the project
143
144	With git remote (preferred):
145
146	```bash
147	vercel link --repo --scope <team-slug> -y
148	```
149
150	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.
151
152	Without git remote:
153
154	```bash
155	vercel link --scope <team-slug> -y
156	```
157
158	Creates `.vercel/project.json`.
159
160	Link to a specific project by name:
161
162	```bash
163	vercel link --project <project-name> --scope <team-slug> -y
164	```
165
166	If the project is already linked, check `orgId` in `.vercel/project.json` or `.vercel/repo.json` to verify it matches the intended team.
167
168	#### Deploy after linking
169
170	A) Git Push Deploy — has git remote (preferred)
171
172	Git pushes trigger automatic Vercel deployments.
173
174	1. Ask the user before pushing. Never push without explicit approval.
175	2. Commit and push:
176	```bash
177	git add .
178	git commit -m "deploy: <description of changes>"
179	git push
180	```
181	3. Vercel builds automatically. Non-production branches get preview deployments.
182	4. Retrieve the deployment URL:
183	```bash
184	sleep 5
185	vercel ls --format json --scope <team-slug>
186	```
187	Find the latest entry in the `deployments` array.
188
189	B) CLI Deploy — no git remote
190
191	```bash
192	vercel deploy --scope <team-slug> -y --no-wait
193	```
194
195	Check status:
196
197	```bash
198	vercel inspect <deployment-url>
199	```
200
201	### Deploying from a Remote Repository (code not cloned locally)
202
203	1. Clone the repository:
204	```bash
205	git clone <repo-url>
206	cd <repo-name>
207	```
208	2. Link to Vercel:
209	```bash
210	vercel link --repo --scope <team-slug> -y
211	```
212	3. Deploy via git push (if you have push access) or CLI deploy.
213
214	### About `.vercel/` Directory
215
216	A linked project has either:
217	- `.vercel/project.json` — from `vercel link`. Contains `projectId` and `orgId`.
218	- `.vercel/repo.json` — from `vercel link --repo`. Contains `orgId`, `remoteName`, and a `projects` map.
219
220	Not needed when `VERCEL_ORG_ID` + `VERCEL_PROJECT_ID` are both set in the environment.
221
222	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.
223
224	## Managing Environment Variables
225
226	```bash
227	# Set for all environments
228	echo "value" \| vercel env add VAR_NAME --scope <team-slug>
229
230	# Set for a specific environment (production, preview, development)
231	echo "value" \| vercel env add VAR_NAME production --scope <team-slug>
232
233	# List environment variables
234	vercel env ls --scope <team-slug>
235
236	# Pull env vars to local .env.local file
237	vercel env pull --scope <team-slug>
238
239	# Remove a variable
240	vercel env rm VAR_NAME --scope <team-slug> -y
241	```
242
243	## Inspecting Deployments
244
245	```bash
246	# List recent deployments
247	vercel ls --format json --scope <team-slug>
248
249	# Inspect a specific deployment
250	vercel inspect <deployment-url>
251
252	# View build logs (requires Vercel CLI v35+)
253	vercel inspect <deployment-url> --logs
254
255	# View runtime request logs (follows live by default; add --no-follow for a one-shot snapshot)
256	vercel logs <deployment-url>
257	```
258
259	## Managing Domains
260
261	```bash
262	# List domains
263	vercel domains ls --scope <team-slug>
264
265	# Add a domain to the project — linked or env-linked directory (1 arg)
266	vercel domains add <domain> --scope <team-slug>
267
268	# Add a domain — unlinked directory (requires <project> positional)
269	vercel domains add <domain> <project> --scope <team-slug>
270	```
271
272	## Stripe Projects Plan Changes
273
274	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.
275
276	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.
277
278	- Upgrade to Pro: `stripe projects add vercel/pro` (or `stripe projects upgrade vercel-plan pro`)
279	- Downgrade to Hobby: `stripe projects downgrade vercel-plan hobby`
280
281	### What Pro gives you
282
283	- $20/month platform fee, includes $20/month of usage credit.
284	- Turbo build machines (30 vCPUs, 60 GB memory) by default for new projects — significantly faster builds than Hobby.
285	- 1 deploying seat + unlimited free Viewer seats (read-only collaborators, preview comments).
286	- Higher included allocations (1 TB Fast Data Transfer, 10M Edge Requests per month).
287	- Paid add-ons available: SAML SSO, HIPAA BAA, Flags Explorer, Observability Plus, Speed Insights, Web Analytics Plus.
288
289	Full details: https://vercel.com/docs/plans/pro-plan
290
291	## Working Agreement
292
293	- Never pass `VERCEL_TOKEN` as a `--token` flag. Export it as an environment variable and let the CLI read it natively.
294	- Check the environment for tokens before asking the user. Look in the current env and `.env` files first.
295	- Default to preview deployments. Only deploy to production when explicitly asked.
296	- Ask before pushing to git. Never push commits without the user's approval.
297	- Do not modify `.vercel/` files directly. The CLI manages this directory. Reading them (e.g. to verify `orgId`) is fine.
298	- Do not curl/fetch deployed URLs to verify. Just return the link to the user.
299	- Use `--format json` when structured output will help with follow-up steps.
300	- Use `-y` on commands that prompt for confirmation to avoid interactive blocking.
301
302	## Troubleshooting
303
304	### Token not found
305
306	Check the environment and any `.env` files present:
307
308	```bash
309	printenv \| grep -i vercel
310	grep -i vercel .env 2>/dev/null
311	```
312
313	### Authentication error
314
315	If the CLI fails with `Authentication required`:
316	- The token may be expired or invalid.
317	- Verify: `vercel whoami` (uses `VERCEL_TOKEN` from environment).
318	- Ask the user for a fresh token.
319
320	### Wrong team
321
322	Verify the scope is correct:
323
324	```bash
325	vercel whoami --scope <team-slug>
326	```
327
328	### Build failure
329
330	Check the build logs:
331
332	```bash
333	vercel inspect <deployment-url> --logs
334	```
335
336	Common causes:
337	- Missing dependencies — ensure `package.json` is complete and committed.
338	- Missing environment variables — add with `vercel env add`.
339	- 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.
340
341	### CLI not installed
342
343	```bash
344	npm install -g vercel
345	```

6 picks

Type

Run `npx skills use "https://github.com/vercel-labs/agent-skills" --skill "vercel-labs/agent-skills/vercel-cli-with-tokens"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the skills in "https://github.com/vercel-labs/agent-skills" that are relevant to the current task. Run `npx skills add "https://github.com/vercel-labs/agent-skills"` and select the relevant skills, then follow their instructions.

vercel-cli-with-tokens

How to install vercel-cli-with-tokens?

Related

vercel-cli-with-tokens

How to install vercel-cli-with-tokens?

Related