/vercel-cli

Routing Rules

Overview

vercel routes manages project-level routing rules. Each rule matches requests by path pattern and optional conditions (headers, cookies, query parameters), then applies an action (rewrite, redirect, set status) or modifies headers and query parameters.

Routing rules take effect immediately without a deployment and take precedence over routes defined in your deployment configuration (vercel.json, next.config.js, etc.).

Each routing rule has a unique name within the project, used to identify it in edit, delete, enable, disable, and reorder commands. Rules are evaluated in priority order (top to bottom). Use reorder to control placement.

All changes are staged as drafts. Run vercel routes publish to push staged changes to production.

Viewing Routing Rules

vercel routes list                       # all routing rules
vercel routes list --diff                # staged changes vs production
vercel routes inspect "My Route"         # full details of a specific rule

Creating Routing Rules

Use --ai with a natural language description to generate routing rules with AI. For full control, use flags or interactive mode.

Source path (--src and --src-syntax)

Use --src to specify the path pattern and --src-syntax to control how it's interpreted:

Defaults to regex if --src-syntax is not specified. path-to-regexp and equals paths must start with /.

Actions

Each routing rule can have at most one primary action:

A routing rule without a primary action can still set response headers or apply request transforms.

Conditions

Conditions control when a routing rule matches. Use --has to require something is present, and --missing to require it is absent. Supported types are header, cookie, query, and host. Conditions are repeatable, up to 16 per rule.

# Existence check
--has "cookie:session"
--missing "header:Authorization"

# Value matching
--has "header:X-API-Key:eq=my-secret"          # exact match
--has "cookie:theme:contains=dark"              # value contains substring
--has "header:Accept:re=application/json.*"     # regex match
--missing "query:debug:eq=true"                 # must NOT have debug=true

# Host matching (no key, just value)
--has "host:eq=example.com"

Response headers & request transforms

Response headers, request headers, and request query parameters can each be set, appended to, or deleted. All flags are repeatable.

--set-response-header "Cache-Control=public, max-age=3600"
--append-request-header "X-Forwarded-Host=myapp.com"
--delete-request-query "debug"

Examples

# AI — describe what you want
vercel routes add --ai "Rewrite /api/* to https://backend.example.com/*"

# Interactive — guided builder with prompts
vercel routes add

# Rewrite with path-to-regexp syntax and a request header
vercel routes add "API Proxy" \
  --src "/api/:path*" --src-syntax path-to-regexp \
  --action rewrite --dest "https://api.example.com/:path*" \
  --set-request-header "X-Forwarded-Host=myapp.com" --yes

# Redirect with status
vercel routes add "Legacy Redirect" \
  --src "/old-blog" --src-syntax equals \
  --action redirect --dest "/blog" --status 301 --yes

# Routing rule with conditions and a description
vercel routes add "Auth Required" \
  --src "/dashboard/:path*" --src-syntax path-to-regexp \
  --action redirect --dest "/login" --status 307 \
  --missing "cookie:session" \
  --description "Redirect unauthenticated users to login" --yes

Editing Routing Rules

# AI — describe the changes
vercel routes edit "My Route" --ai "Add CORS headers and change to 308 redirect"

# Interactive — choose which fields to modify
vercel routes edit "My Route"

# Change specific fields
vercel routes edit "My Route" --dest "https://new-api.example.com/:path*" --yes
vercel routes edit "My Route" --action redirect --dest "/new" --status 301 --yes
vercel routes edit "My Route" --name "New Name" --yes

Managing Routing Rules

Use vercel routes list or inspect to find routing rule names and IDs.

vercel routes enable "My Route"           # enable a disabled routing rule
vercel routes disable "My Route"          # disable without removing
vercel routes delete "My Route"           # delete a routing rule
vercel routes reorder "My Route" --position start           # move to top
vercel routes reorder "My Route" --position end             # move to bottom
vercel routes reorder "My Route" --position after:<id>      # move after another
vercel routes reorder "My Route" --position before:<id>     # move before another

Publishing & Versioning

vercel routes publish                    # promote staged changes to production
vercel routes discard-staging            # discard all staged changes
vercel routes list-versions              # view version history
vercel routes restore <version-id>       # roll back to a previous version