vercel-cli

---
name: vercel-cli
description: Vercel CLI expert guidance. Use when deploying, managing environment variables, linking projects, viewing logs, querying metrics, debugging a deployed app on Vercel (errors, 5xx responses, timeouts, slow routes, or a single failing request), managing domains, managing feature flags with vercel flags, or interacting with the Vercel platform from the command line. Use the vercel-tracing skill instead for `vercel traces` span search, trace inspection, and sampling rules, or for OpenTelemetry setup.
metadata:
  priority: 4
  docs:
    - "https://vercel.com/docs/cli"
  sitemap: "https://vercel.com/sitemap.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
    - vercel traces
chainTo:
  -
    pattern: '\b(?:vercel|vc)\s+traces\b'
    targetSkill: vercel-tracing
    message: 'vercel traces command detected — loading Vercel Tracing guidance for span search, request inspection, and sampling rules.'
  -
    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> --help` for full flag details on any command.

The installed CLI help is the source of truth for obscure or newly added flags. If a command example here is not enough, check `vercel <command> --help` before acting instead of guessing.

Parse only stdout for URLs and JSON. Warnings, progress, and `--help` print to stderr; merge streams only when searching help text. Some help commands exit 2 after printing usage, so treat printed usage as a successful help read.

In agent/non-interactive mode, many commands report errors and required confirmations as a single JSON object on stdout with `status`, `reason`, `hint`, and `next` (runnable follow-up commands). Prefer a suggested `next` command over composing a retry only after confirming that it preserves the user's intended target and authorization; do not automatically run linking, authentication, or mutation follow-ups. Read commands such as `list`, `logs`, `inspect`, and `api` keep their normal output shape.

## Critical: Project Linking

Project context depends on the command's working directory. Before a consequential read or mutation, run `vercel project inspect --non-interactive` from the intended directory and confirm the reported owner and project. This command resolves only existing context in non-interactive mode; stop on `link_required` or a target mismatch instead of linking automatically.

Many project-aware commands also accept `--project <name-or-id>` with `--scope <team>` for an explicit, one-command target. Confirm that target and scope preserve the user's intent before using them.

- **`<cwd>/.vercel/project.json`**: Created by `vercel link`. This exact working-directory link wins over a repository link. The CLI does not generally inherit a root `project.json` when run from an arbitrary subdirectory.
- **`<repo-root>/.vercel/repo.json`**: Created by `vercel link --repo`. The CLI selects the deepest project directory that contains the working directory.
- **Unmatched repository path**: If no repo mapping contains the working directory, interactive repo resolution prompts among the configured projects. Non-interactive repo resolution currently selects the only configured project or remains unresolved when multiple choices exist. Commands that set up projects may then enter a linking flow, so non-interactive mode is not generally fail-closed.

Being inside an app directory is not proof that the intended project was selected. Check the resolved project explicitly, especially when a repo mapping does not cover that directory.

`vercel whoami --format json` identifies the authenticated user and effective team; plain non-TTY `vercel whoami` prints only the username. Neither verifies the linked project. Read-only project commands can still require login or team SAML re-authentication and open a browser/device flow. Ask the user to complete that flow deliberately before continuing.

## Quick Start

```bash
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, redeploy, forced builds, no-cache builds, or deployment source/provenance** → `references/deployment.md`
- **Rolling releases, deploy hooks, cron jobs, cache, git connection, Edge Config, redirects, custom environments** → `references/project-infra.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`
- **Vercel Toolbar comments (`vercel comments`)** → `references/comments.md`
- **Build failures, deployment errors, logs, metrics, Speed Insights, Core Web Vitals, activity, performance, preview access, or production debugging** → `references/monitoring-and-debugging.md`
- **Alerts, usage, contracts, billing purchases, tokens, telemetry, or CLI upgrades** → `references/platform-ops.md`
- **Blob storage** → `references/storage.md`
- **Container Registry (`vercel vcr`: repositories, images, tags, docker/podman/buildah login, push/pull)** → `references/container-registry.md`
- **Integrations (databases, storage, etc.)** → `references/integrations.md`
- **Connectors (`vercel connect`)** → `references/connectors.md`
- **Routing rules** → `references/routing.md`
- **Firewall (WAF rules, IP blocks, rate limiting)** → `references/firewall.md`
- **Access a preview deployment** → use `vercel curl` (see `references/monitoring-and-debugging.md`)
- **CLI command is unavailable or output is missing required fields** → use `vercel api` after first-class CLI paths are unavailable or insufficient (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 (`vercel flags`: create, inspect, set, split, rollout, rules, segments, sdk-keys)** → `references/flags.md`
- **Microfrontends** → `references/microfrontends.md`
- **Sandbox** → `references/sandbox.md`
- **Agent, MCP, skills discovery, or AI Gateway** → `references/agent-and-ai.md`
- **Captured request traces (`vercel traces`, including `--open` / `--view`)** → `references/advanced.md`
- **Advanced (`vercel api` fallback, 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.
- **Assuming an app subdirectory determines the project**: Verify with `vercel project inspect --non-interactive`; an unmatched repo path can currently fall back to the sole configured project in non-interactive mode.
- **Using `vercel whoami` as linked-project verification**: `vercel whoami --format json` reports authentication and team context, not the selected project.
- **Forgetting non-interactive flags in plain CI runs**: detected agents get `--non-interactive` by default, but plain CI does not — pass it explicitly there, and add `--yes` only for commands that require confirmation.
- **Using `vercel deploy` after `vercel build` without `--prebuilt`**: The build output is ignored.
- **Using `vercel redeploy` for no-cache rebuilds**: `vercel redeploy` does not expose a no-cache flag; use `vercel deploy --force` without `--with-cache` when you need a fresh deployment that does not retain build cache.
- **Hardcoding tokens in flags**: Use `VERCEL_TOKEN` env var instead of `--token`.
- **Disabling deployment protection**: Use `vercel curl` instead to access preview deploys.
- **Using `vercel api` too early**: Prefer first-class CLI commands when they expose the needed data or mutation.

• .vercel.approvers 1 KB
• SKILL.md 10 KB
• overlay.yaml 3 KB
• command/vercel.md 2 KB
• references/advanced.md 4 KB
• references/agent-and-ai.md 1 KB
• references/bun.md 1 KB
• references/ci-automation.md 2 KB
• references/comments.md 2 KB
• references/connectors.md 3 KB
• references/container-registry.md 4 KB
• references/deployment.md 3 KB
• references/domains-and-dns.md 3 KB
• references/environment-variables.md 2 KB
• references/firewall.md 18 KB
• references/flags.md 3 KB
• references/getting-started.md 2 KB
• references/global-options.md 1 KB
• references/integrations.md 11 KB
• references/local-development.md 2 KB
• references/microfrontends.md 5 KB
• references/monitoring-and-debugging.md 7 KB
• references/monorepos.md 4 KB
• references/node-backends.md 3 KB
• references/platform-ops.md 2 KB
• references/project-infra.md 3 KB
• references/projects-and-teams.md 2 KB
• references/routing.md 5 KB
• references/sandbox.md 2 KB
• references/storage.md 6 KB
• upstream/SKILL.md 8 KB
• upstream/command/vercel.md 2 KB
• upstream/references/advanced.md 4 KB
• upstream/references/agent-and-ai.md 1 KB
• upstream/references/bun.md 1 KB
• upstream/references/ci-automation.md 2 KB
• upstream/references/comments.md 2 KB
• upstream/references/connectors.md 3 KB
• upstream/references/container-registry.md 4 KB
• upstream/references/deployment.md 3 KB
• upstream/references/domains-and-dns.md 3 KB
• upstream/references/environment-variables.md 2 KB
• upstream/references/firewall.md 18 KB
• upstream/references/flags.md 3 KB
• upstream/references/getting-started.md 2 KB
• upstream/references/global-options.md 1 KB
• upstream/references/integrations.md 11 KB
• upstream/references/local-development.md 2 KB
• upstream/references/microfrontends.md 5 KB
• upstream/references/monitoring-and-debugging.md 7 KB
• upstream/references/monorepos.md 4 KB
• upstream/references/node-backends.md 3 KB
• upstream/references/platform-ops.md 2 KB
• upstream/references/project-infra.md 3 KB
• upstream/references/projects-and-teams.md 2 KB
• upstream/references/routing.md 5 KB
• upstream/references/sandbox.md 2 KB
• upstream/references/storage.md 6 KB