version: "1.0.0" name: vercel-cli description: 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. metadata: priority: 4 docs:

• "https://vercel.com/docs/cli"

sitemap: "https://vercel.com/sitemap/docs.xml" pathPatterns:

• 'vercel.json'
• 'vercel.ts'
• '.vercel/**'
• '.vercelignore'
• 'now.json'

bashPatterns:

• '^\s*vercel(?:\s|$)'
• '^\s*vc(?:\s|$)'
• '\bnpx\s+vercel\b'
• '\bpnpm\s+dlx\s+vercel\b'
• '\bbunx\s+vercel\b'
• '\byarn\s+dlx\s+vercel\b'
• '\bnpx\s+@vercel/config\b'

promptSignals: phrases:

• "check deployment"
• "check deploy"
• "deployment status"
• "deploy status"
• "vercel logs"
• "vercel metrics"
• "deployment logs"
• "deploy logs"
• "vercel inspect"
• "is it deployed"
• "deploy failing"
• "deploy failed"
• "deployment error"
• "check vercel"
• "vercel status"

allOf:

• [check, deployment]
• [check, deploy]
• [vercel, status]
• [vercel, logs]
• [vercel, metrics]
• [deploy, error]
• [deploy, failed]
• [deploy, stuck]

anyOf:

• "deployment"
• "deploy"
• "vercel"
• "production"

noneOf:

• "terraform"
• "aws deploy"
• "heroku"

minScore: 6 retrieval: aliases:

• vercel command line
• vc cli
• deploy command
• vercel terminal

intents:

• deploy from cli
• link project
• manage domains
• view logs from terminal

entities:

• vercel CLI
• vercel deploy
• vercel env
• vercel link
• vercel logs
• vercel metrics

chainTo: - pattern: '"functions"\s:\s\{|"maxDuration"\s:|"memory"\s:' targetSkill: vercel-functions message: 'Functions configuration detected in vercel.json — loading Vercel Functions guidance for runtime options, streaming, and Fluid Compute.' skipIfFileContains: '"crons"\s:' - pattern: '"redirects"\s:\s\[|"rewrites"\s:\s\[|"headers"\s:\s*\[' targetSkill: routing-middleware message: 'Routing rules in vercel.json — loading Routing Middleware guidance for platform-level request interception patterns.'

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.