Vercel CLI Skill
The Vercel CLI (vercel or vc) deploys, manages, and develops projects on the Vercel platform from the command line. Use vercel <command> -h for full flag details on any command.
Critical: Project Linking
Commands must be run from the directory containing the .vercel folder (or a subdirectory of it). How .vercel gets set up depends on your project structure:
.vercel/project.json: Created by vercel link. Links a single project. Fine for single-project repos, and can work in monorepos if there's only one project..vercel/repo.json: Created by vercel link --repo. Links a repo that may contain multiple projects. Always a good idea when any project has a non-root directory (e.g., apps/web).
Running from a project subdirectory (e.g., apps/web/) skips the "which project?" prompt since it's unambiguous.
When something goes wrong, check how things are linked first — look at what's in .vercel/ and whether it's project.json or repo.json. Also verify you're on the right team with vercel whoami — linking while on the wrong team is a common mistake.
Quick Start
npm i -g vercel
vercel login
vercel link # single project
# OR
vercel link --repo # monorepo
vercel pull
vercel dev # local development
vercel deploy # preview deployment
vercel --prod # production deployment
Decision Tree
Use this to route to the correct reference file:
- Deploy →
references/deployment.md
- Local development →
references/local-development.md
- Environment variables →
references/environment-variables.md
- CI/CD automation →
references/ci-automation.md
- Domains or DNS →
references/domains-and-dns.md
- Projects or teams →
references/projects-and-teams.md
- Logs, metrics, debugging, or accessing preview deploys →
references/monitoring-and-debugging.md
- Blob storage →
references/storage.md
- Integrations (databases, storage, etc.) →
references/integrations.md
- Access a preview deployment → use
vercel curl (see references/monitoring-and-debugging.md)
- CLI doesn't have a command for it → use
vercel api as a fallback (see references/advanced.md)
- Node.js backends (Express, Hono, etc.) →
references/node-backends.md
- Monorepos (Turborepo, Nx, workspaces) →
references/monorepos.md
- Bun runtime →
references/bun.md
- Feature flags →
references/flags.md
- Advanced (API, webhooks) →
references/advanced.md
- Global flags →
references/global-options.md
- First-time setup →
references/getting-started.md
Anti-Patterns
- Wrong link type in monorepos with multiple projects:
vercel link creates project.json, which only tracks one project. Use vercel link --repo instead. When things break, check .vercel/ first.
- Letting commands auto-link in monorepos: Many commands implicitly run
vercel link if .vercel/ doesn't exist. This creates project.json, which may be wrong. Run vercel link (or --repo) explicitly first.
- Linking while on the wrong team: Use
vercel whoami to check, vercel teams switch to change.
- Forgetting
--yes in CI: Required to skip interactive prompts.
- Using
vercel deploy after vercel build without --prebuilt: The build output is ignored.
- Hardcoding tokens in flags: Use
VERCEL_TOKEN env var instead of --token.
- Disabling deployment protection: Use
vercel curl instead to access preview deploys.
1---
2name: vercel-cli
3description: Vercel CLI expert guidance. Use when deploying, managing environment variables, linking projects, viewing logs, querying metrics, managing domains, or interacting with the Vercel platform from the command line.
4metadata:
5 priority: 4
6 docs:
7 - "https://vercel.com/docs/cli"
8 sitemap: "https://vercel.com/sitemap.xml"
9 pathPatterns:
10 - 'vercel.json'
11 - 'vercel.ts'
12 - '.vercel/**'
13 - '.vercelignore'
14 - 'now.json'
15 bashPatterns:
16 - '^\s*vercel(?:\s|$)'
17 - '^\s*vc(?:\s|$)'
18 - '\bnpx\s+vercel\b'
19 - '\bpnpm\s+dlx\s+vercel\b'
20 - '\bbunx\s+vercel\b'
21 - '\byarn\s+dlx\s+vercel\b'
22 - '\bnpx\s+@vercel/config\b'
23 promptSignals:
24 phrases:
25 - "check deployment"
26 - "check deploy"
27 - "deployment status"
28 - "deploy status"
29 - "vercel logs"
30 - "vercel metrics"
31 - "deployment logs"
32 - "deploy logs"
33 - "vercel inspect"
34 - "is it deployed"
35 - "deploy failing"
36 - "deploy failed"
37 - "deployment error"
38 - "check vercel"
39 - "vercel status"
40 allOf:
41 - [check, deployment]
42 - [check, deploy]
43 - [vercel, status]
44 - [vercel, logs]
45 - [vercel, metrics]
46 - [deploy, error]
47 - [deploy, failed]
48 - [deploy, stuck]
49 anyOf:
50 - "deployment"
51 - "deploy"
52 - "vercel"
53 - "production"
54 noneOf:
55 - "terraform"
56 - "aws deploy"
57 - "heroku"
58 minScore: 6
59retrieval:
60 aliases:
61 - vercel command line
62 - vc cli
63 - deploy command
64 - vercel terminal
65 intents:
66 - deploy from cli
67 - link project
68 - manage domains
69 - view logs from terminal
70 entities:
71 - vercel CLI
72 - vercel deploy
73 - vercel env
74 - vercel link
75 - vercel logs
76 - vercel metrics
77chainTo:
78 -
79 pattern: '"functions"\s*:\s*\{|"maxDuration"\s*:|"memory"\s*:'
80 targetSkill: vercel-functions
81 message: 'Functions configuration detected in vercel.json — loading Vercel Functions guidance for runtime options, streaming, and Fluid Compute.'
82 skipIfFileContains: '"crons"\s*:'
83 -
84 pattern: '"redirects"\s*:\s*\[|"rewrites"\s*:\s*\[|"headers"\s*:\s*\['
85 targetSkill: routing-middleware
86 message: 'Routing rules in vercel.json — loading Routing Middleware guidance for platform-level request interception patterns.'
87---
88
89# Vercel CLI Skill
90
91The Vercel CLI (`vercel` or `vc`) deploys, manages, and develops projects on the Vercel platform from the command line. Use `vercel <command> -h` for full flag details on any command.
92
93## Critical: Project Linking
94
95Commands must be run from the directory containing the `.vercel` folder (or a subdirectory of it). How `.vercel` gets set up depends on your project structure:
96
97- **`.vercel/project.json`**: Created by `vercel link`. Links a single project. Fine for single-project repos, and can work in monorepos if there's only one project.
98- **`.vercel/repo.json`**: Created by `vercel link --repo`. Links a repo that may contain multiple projects. Always a good idea when any project has a non-root directory (e.g., `apps/web`).
99
100Running from a project subdirectory (e.g., `apps/web/`) skips the "which project?" prompt since it's unambiguous.
101
102**When something goes wrong, check how things are linked first** — look at what's in `.vercel/` and whether it's `project.json` or `repo.json`. Also verify you're on the right team with `vercel whoami` — linking while on the wrong team is a common mistake.
103
104## Quick Start
105
106```bash
107npm i -g vercel
108vercel login
109vercel link # single project
110# OR
111vercel link --repo # monorepo
112vercel pull
113vercel dev # local development
114vercel deploy # preview deployment
115vercel --prod # production deployment
116```
117
118## Decision Tree
119
120Use this to route to the correct reference file:
121
122- **Deploy** → `references/deployment.md`
123- **Local development** → `references/local-development.md`
124- **Environment variables** → `references/environment-variables.md`
125- **CI/CD automation** → `references/ci-automation.md`
126- **Domains or DNS** → `references/domains-and-dns.md`
127- **Projects or teams** → `references/projects-and-teams.md`
128- **Logs, metrics, debugging, or accessing preview deploys** → `references/monitoring-and-debugging.md`
129- **Blob storage** → `references/storage.md`
130- **Integrations (databases, storage, etc.)** → `references/integrations.md`
131- **Access a preview deployment** → use `vercel curl` (see `references/monitoring-and-debugging.md`)
132- **CLI doesn't have a command for it** → use `vercel api` as a fallback (see `references/advanced.md`)
133- **Node.js backends (Express, Hono, etc.)** → `references/node-backends.md`
134- **Monorepos (Turborepo, Nx, workspaces)** → `references/monorepos.md`
135- **Bun runtime** → `references/bun.md`
136- **Feature flags** → `references/flags.md`
137- **Advanced (API, webhooks)** → `references/advanced.md`
138- **Global flags** → `references/global-options.md`
139- **First-time setup** → `references/getting-started.md`
140
141## Anti-Patterns
142
143- **Wrong link type in monorepos with multiple projects**: `vercel link` creates `project.json`, which only tracks one project. Use `vercel link --repo` instead. When things break, check `.vercel/` first.
144- **Letting commands auto-link in monorepos**: Many commands implicitly run `vercel link` if `.vercel/` doesn't exist. This creates `project.json`, which may be wrong. Run `vercel link` (or `--repo`) explicitly first.
145- **Linking while on the wrong team**: Use `vercel whoami` to check, `vercel teams switch` to change.
146- **Forgetting `--yes` in CI**: Required to skip interactive prompts.
147- **Using `vercel deploy` after `vercel build` without `--prebuilt`**: The build output is ignored.
148- **Hardcoding tokens in flags**: Use `VERCEL_TOKEN` env var instead of `--token`.
149- **Disabling deployment protection**: Use `vercel curl` instead to access preview deploys.
vercel