--- name: openai--vercel--vercel-cli description: >- Vercel CLI expert guidance. Use when deploying, managing environment variables, linking projects, viewing logs, managing domains, or interacting with the Vercel platform from the command line. origin: "openai/plugins — vercel/vercel-cli (MIT)" license: MIT version: "0.1.0" compatibility: "yamtam-engine >= 0.14.0" --- # Vercel CLI You are an expert in the Vercel CLI v50.28.0 (`vercel` or `vc`). The CLI is the primary way to manage Vercel projects from the terminal. ## Installation ```bash npm i -g vercel ``` ## Login The CLI uses an **OAuth 2.0 Device Flow** for authentication. ```bash vercel login ``` > **Deprecation notice**: Email-based login (`vercel login your@email.com`) and the flags `--github`, `--gitlab`, `--bitbucket`, `--oob` were removed February 26, 2026. The `team` method (SAML-based login) remains supported until June 1, 2026, then will also be removed. ## Core Commands ### Deployment ```bash # Preview deployment (from project root) vercel # Production deployment vercel --prod # Build locally, deploy build output only vercel build vercel deploy --prebuilt # Build for production (uses production env vars) vercel build --prod vercel deploy --prebuilt --prod # Force a new deployment (skip cache) vercel --force # Promote a preview deployment to production vercel promote # Rollback to previous production deployment vercel rollback ``` ### Development ```bash # Start local dev server with Vercel features vercel dev # Link current directory to a Vercel project vercel link # Deterministic non-interactive link (recommended for bootstrap/automation) vercel link --yes --project --scope # Pull environment variables and project settings vercel pull # Pull specific environment vercel pull --environment=production # Open linked project in the Vercel Dashboard vercel open ``` ### Deterministic Project Linking (Recommended) Prefer explicit non-interactive linking for bootstrap and automation: ```bash vercel link --yes --project --scope ``` This is more reliable than interactive prompt-driven linking, which can pick the wrong project or team in multi-account setups. If there is any ambiguity, run `vercel open` to confirm the dashboard project, then relink with explicit `--project` and `--scope`. ### Environment Variables ```bash # List all environment variables vercel env ls # Add an environment variable vercel env add MY_VAR # Add for specific environments vercel env add MY_VAR production vercel env add MY_VAR preview development # Add branch-scoped variable vercel env add MY_VAR preview --branch=feature-x # Add sensitive (write-only) variable vercel env add MY_SECRET --sensitive # Remove an environment variable vercel env rm MY_VAR # Pull all env vars to .env.local vercel env pull vercel env pull .env.production.local --environment=production ``` ### Logs & Inspection The `vercel logs` command (rebuilt February 2026) supports **historical log querying** and uses **git context by default** — it automatically scopes logs to your current repository when run from a project directory. ```bash # View runtime/function logs (real-time) vercel logs # Follow logs in real-time (streaming mode) vercel logs --follow # Query historical logs (no longer limited to live-only) vercel logs --since 24h vercel logs --since 7d # Filter by time range vercel logs --since 1h vercel logs --since 30m # Filter by log level vercel logs --level error vercel logs --level warning # Filter by deployment ID, request ID, or arbitrary string vercel logs --deployment-id dpl_xxxxx vercel logs --request-id req_xxxxx vercel logs --query "TypeError" # Output as JSON (for piping to jq or other tools) vercel logs --json # Combine filters: stream errors from the last hour as JSON vercel logs --follow --since 1h --level error --json # Inspect a deployment (build details, metadata, function list) vercel inspect # List recent deployments vercel ls ``` > **Note:** `vercel logs` shows runtime request logs only. For build output, use > `vercel inspect ` or view build logs at `https://vercel.com/{team}/{project}/deployments` → select deployment → **Build Logs**. > > **Drains and advanced observability:** Log drains, trace export, and analytics data forwarding are > configured via the Vercel Dashboard at `https://vercel.com/dashboard/{team}/~/settings/log-drains` or REST API (`/v1/drains`), not the CLI. See `⤳ skill: observability` > for drain setup, payload schemas, and signature verification. ### Domains ```bash # List domains vercel domains ls # Add a domain to a project vercel domains add example.com # Remove a domain vercel domains rm example.com ``` ### DNS ```bash # List DNS records vercel dns ls example.com # Add a DNS record vercel dns add example.com @ A 1.2.3.4 ``` ### Teams ```bash # List teams vercel teams ls # Switch to a team vercel teams switch my-team ``` ### Cache Management ```bash # Purge all cache (CDN + Data cache) for current project vercel cache purge # Purge only CDN cache vercel cache purge --type cdn # Purge only Data cache vercel cache purge --type data # Purge without confirmation prompt vercel cache purge --yes # Invalidate by tag (stale-while-revalidate) vercel cache invalidate --tag blog-posts # Invalidate multiple tags vercel cache invalidate --tag blog-posts,user-profiles,homepage # Hard delete by tag (blocks until revalidated — use with caution) vercel cache dangerously-delete --tag blog-posts # Hard delete with revalidation deadline (deletes only if not accessed within N seconds) vercel cache dangerously-delete --tag blog-posts --revalidation-deadline-seconds 3600 # Invalidate cached image transformations by source path vercel cache invalidate --srcimg /api/avatar/1 # Hard delete cached image transformations vercel cache dangerously-delete --srcimg /api/avatar/1 ``` **Key distinction:** `invalidate` serves STALE and revalidates in the background. `dangerously-delete` serves MISS and blocks while revalidating. Prefer `invalidate` unless you need immediate freshness. **Note:** `--tag` and `--srcimg` cannot be used together. ### MCP Server Integration ```bash # Initialize global MCP client configuration for your Vercel account vercel mcp # Set up project-specific MCP access for the linked project vercel mcp --project ``` The `vercel mcp` command links your local MCP client configuration to a Vercel Project. It generates connection details so AI agents and tools can call your MCP endpoints deployed on Vercel securely. ### Programmatic Configuration (`@vercel/config`) ```bash # Compile vercel.ts to JSON (stdout) npx @vercel/config compile # Validate configuration and show summary npx @vercel/config validate # Generate vercel.json locally for development npx @vercel/config generate ``` Use `vercel.ts` (or `.js`, `.mjs`, `.cjs`, `.mts`) instead of `vercel.json` for type-safe, dynamic project configuration. Only one config file per project — `vercel.json` or `vercel.ts`, not both. > **Note:** Legacy `now.json` support will be removed on March 31, 2026. Rename to `vercel.json` (no content changes needed). ### Marketplace Integrations Auto-provisioning is the default for `vercel integration add` — the CLI automatically creates resources and sets environment variables without extra prompts. ```bash # List installed integrations vercel integration list # Add an integration (auto-provisions env vars by default) vercel integration add neon # Open an integration's dashboard vercel integration open neon # Remove an integration vercel integration remove neon ``` #### Agent-Optimized: `discover` and `guide` AI agents can autonomously discover, install, and retrieve setup instructions for Marketplace integrations (added March 2026): ```bash # Search the integration catalog (returns JSON for automation) vercel integration discover --format=json # Search with a keyword filter vercel integration discover database --format=json # Get agent-friendly setup guide with code snippets vercel integration guide neon # Full workflow: discover → add → guide vercel integration discover storage --format=json vercel integration add neon vercel integration guide neon ``` - `discover` — Searches the Vercel Marketplace catalog. Use `--format=json` for non-interactive output suitable for scripting and agent pipelines. - `guide ` — Returns getting-started documentation in agent-friendly markdown: environment variables, SDK setup, and code snippets. - Human-in-the-loop safety: the CLI prompts for developer confirmation when accepting Terms of Service. > Full subcommands: `discover`, `guide`, `add`, `list` (alias `ls`), `balance`, `open`, `remove`. ### Project-Level Routing (No Redeploy) Create and update routing rules — headers, rewrites, redirects — without building a new deployment. Rules take effect instantly. Available via dashboard (CDN tab), API, CLI, and Vercel SDK. Project-level routes run after bulk redirects and before deployment config routes. ### Feature Flags ```bash # Create a feature flag vercel flags add redesigned-checkout --kind boolean --description "New checkout flow" # List SDK keys vercel flags sdk-keys ls # Enable/disable, archive, and manage flags from CLI vercel flags --help ``` See `⤳ skill: vercel-flags` for full flag configuration and adapter patterns. ### Direct API Access The `vercel api` command (added January 2026) gives direct access to the full Vercel REST API from the terminal. Designed for AI agents — call Vercel APIs with no additional configuration. ```bash # Call any Vercel REST API endpoint vercel api GET /v9/projects vercel api GET /v13/deployments vercel api POST /v9/projects/:id/env --body '{"key":"MY_VAR","value":"val","target":["production"]}' # Pipe JSON output to jq vercel api GET /v9/projects | jq '.[].name' ``` ### Metrics ```bash # Query project metrics (rich text output with sparklines) vercel metrics # Raw values for scripting vercel metrics --raw-values ``` ## CI/CD Integration Required environment variables for CI: ```bash VERCEL_TOKEN= VERCEL_ORG_ID= VERCEL_PROJECT_ID= ``` ### GitHub Actions Example ```yaml - name: Deploy to Vercel run: | vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }} vercel build --prod --token=${{ secrets.VERCEL_TOKEN }} vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }} ``` ## Global Options | Flag | Purpose | |------|---------| | `--token` | Authentication token (for CI) | | `--cwd ` | Working directory | | `--debug` / `-d` | Verbose output | | `--yes` / `-y` | Skip confirmation prompts | | `--scope ` | Execute as a team | ## Common Workflows ### First-Time Setup ```bash vercel link # Connect to Vercel project vercel env pull # Get environment variables vercel dev # Start local dev ``` ### Deploy from CI ```bash vercel pull --yes --environment=production --token=$TOKEN vercel build --prod --token=$TOKEN vercel deploy --prebuilt --prod --token=$TOKEN ``` ### Quick Preview ```bash vercel # Creates preview deployment, returns URL ``` ## Official Documentation - [Vercel CLI](https://vercel.com/docs/cli) - [Cache Management](https://vercel.com/docs/cli/cache) - [MCP Integration](https://vercel.com/docs/cli/mcp) - [Deployments](https://vercel.com/docs/deployments) - [REST API](https://vercel.com/docs/rest-api/reference) - [GitHub: Vercel CLI](https://github.com/vercel/vercel)