From 269560798e91580c428a9701fd8c69c56c61df34 Mon Sep 17 00:00:00 2001 From: Yash Kothari Date: Mon, 6 Apr 2026 14:22:08 -0700 Subject: [PATCH 1/2] add routing.md reference for vercel routes CLI commands --- generated/build-from-skills.manifest.json | 2 +- generated/skill-manifest.json | 2 +- skills/vercel-cli/SKILL.md | 1 + skills/vercel-cli/references/routing.md | 142 ++++++++++++++++++ skills/vercel-cli/upstream/SKILL.md | 1 + .../vercel-cli/upstream/references/routing.md | 142 ++++++++++++++++++ 6 files changed, 288 insertions(+), 2 deletions(-) create mode 100644 skills/vercel-cli/references/routing.md create mode 100644 skills/vercel-cli/upstream/references/routing.md diff --git a/generated/build-from-skills.manifest.json b/generated/build-from-skills.manifest.json index e0b1a99..62cd204 100644 --- a/generated/build-from-skills.manifest.json +++ b/generated/build-from-skills.manifest.json @@ -1,6 +1,6 @@ { "version": 1, - "generatedAt": "2026-04-06T17:43:11.206Z", + "generatedAt": "2026-04-06T21:21:36.980Z", "templates": [ { "template": "agents/ai-architect.md.tmpl", diff --git a/generated/skill-manifest.json b/generated/skill-manifest.json index 5c8aee3..1897fed 100644 --- a/generated/skill-manifest.json +++ b/generated/skill-manifest.json @@ -1,5 +1,5 @@ { - "generatedAt": "2026-04-06T17:43:11.165Z", + "generatedAt": "2026-04-06T21:21:43.018Z", "version": 2, "skills": { "vercel-agent": { diff --git a/skills/vercel-cli/SKILL.md b/skills/vercel-cli/SKILL.md index 7d8a349..19196e2 100644 --- a/skills/vercel-cli/SKILL.md +++ b/skills/vercel-cli/SKILL.md @@ -126,6 +126,7 @@ Use this to route to the correct reference file: - **Logs, debugging, or accessing preview deploys** → `references/monitoring-and-debugging.md` - **Blob storage** → `references/storage.md` - **Integrations (databases, storage, etc.)** → `references/integrations.md` +- **Routing rules** → `references/routing.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` diff --git a/skills/vercel-cli/references/routing.md b/skills/vercel-cli/references/routing.md new file mode 100644 index 0000000..0bcfbf9 --- /dev/null +++ b/skills/vercel-cli/references/routing.md @@ -0,0 +1,142 @@ +# 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 + +```bash +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: + +| Syntax | Example | When to use | +|--------|---------|-------------| +| `regex` | `^/api/(.*)$` | Full regex control. | +| `path-to-regexp` | `/api/:path*` | Express-style named params. More readable. | +| `equals` | `/about` | Exact string match. Simplest option. | + +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: + +| Action | Required flags | Description | +|--------|---------------|-------------| +| `rewrite` | `--dest` | Proxy to destination URL (transparent to the client) | +| `redirect` | `--dest` + `--status` (301/302/307/308) | Redirect the client to a new URL | +| `set-status` | `--status` (100-599) | Return a status code (no destination) | + +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. + +```bash +# 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. + +```bash +--set-response-header "Cache-Control=public, max-age=3600" +--append-request-header "X-Forwarded-Host=myapp.com" +--delete-request-query "debug" +``` + +### Examples + +```bash +# 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 + +```bash +# 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. + +```bash +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: # move after another +vercel routes reorder "My Route" --position before: # move before another +``` + +## Publishing & Versioning + +```bash +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 # roll back to a previous version +``` diff --git a/skills/vercel-cli/upstream/SKILL.md b/skills/vercel-cli/upstream/SKILL.md index 91b5799..76f0e15 100644 --- a/skills/vercel-cli/upstream/SKILL.md +++ b/skills/vercel-cli/upstream/SKILL.md @@ -45,6 +45,7 @@ Use this to route to the correct reference file: - **Logs, debugging, or accessing preview deploys** → `references/monitoring-and-debugging.md` - **Blob storage** → `references/storage.md` - **Integrations (databases, storage, etc.)** → `references/integrations.md` +- **Routing rules** → `references/routing.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` diff --git a/skills/vercel-cli/upstream/references/routing.md b/skills/vercel-cli/upstream/references/routing.md new file mode 100644 index 0000000..0bcfbf9 --- /dev/null +++ b/skills/vercel-cli/upstream/references/routing.md @@ -0,0 +1,142 @@ +# 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 + +```bash +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: + +| Syntax | Example | When to use | +|--------|---------|-------------| +| `regex` | `^/api/(.*)$` | Full regex control. | +| `path-to-regexp` | `/api/:path*` | Express-style named params. More readable. | +| `equals` | `/about` | Exact string match. Simplest option. | + +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: + +| Action | Required flags | Description | +|--------|---------------|-------------| +| `rewrite` | `--dest` | Proxy to destination URL (transparent to the client) | +| `redirect` | `--dest` + `--status` (301/302/307/308) | Redirect the client to a new URL | +| `set-status` | `--status` (100-599) | Return a status code (no destination) | + +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. + +```bash +# 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. + +```bash +--set-response-header "Cache-Control=public, max-age=3600" +--append-request-header "X-Forwarded-Host=myapp.com" +--delete-request-query "debug" +``` + +### Examples + +```bash +# 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 + +```bash +# 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. + +```bash +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: # move after another +vercel routes reorder "My Route" --position before: # move before another +``` + +## Publishing & Versioning + +```bash +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 # roll back to a previous version +``` From c9614226d8faebf229d09780242cecf089b083fb Mon Sep 17 00:00:00 2001 From: Yash Kothari Date: Mon, 6 Apr 2026 15:06:29 -0700 Subject: [PATCH 2/2] expand routing.md: add missing flags, export subcommand, aliases, clearing flags, list options --- generated/build-from-skills.manifest.json | 2 +- generated/skill-manifest.json | 2 +- skills/vercel-cli/references/routing.md | 66 ++++++++++++++++--- .../vercel-cli/upstream/references/routing.md | 66 ++++++++++++++++--- 4 files changed, 114 insertions(+), 22 deletions(-) diff --git a/generated/build-from-skills.manifest.json b/generated/build-from-skills.manifest.json index 62cd204..742ef78 100644 --- a/generated/build-from-skills.manifest.json +++ b/generated/build-from-skills.manifest.json @@ -1,6 +1,6 @@ { "version": 1, - "generatedAt": "2026-04-06T21:21:36.980Z", + "generatedAt": "2026-04-06T22:06:15.070Z", "templates": [ { "template": "agents/ai-architect.md.tmpl", diff --git a/generated/skill-manifest.json b/generated/skill-manifest.json index 1897fed..ad019e7 100644 --- a/generated/skill-manifest.json +++ b/generated/skill-manifest.json @@ -1,5 +1,5 @@ { - "generatedAt": "2026-04-06T21:21:43.018Z", + "generatedAt": "2026-04-06T22:06:19.654Z", "version": 2, "skills": { "vercel-agent": { diff --git a/skills/vercel-cli/references/routing.md b/skills/vercel-cli/references/routing.md index 0bcfbf9..a1ef8e9 100644 --- a/skills/vercel-cli/references/routing.md +++ b/skills/vercel-cli/references/routing.md @@ -13,9 +13,14 @@ All changes are staged as drafts. Run `vercel routes publish` to push staged cha ## Viewing Routing Rules ```bash -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 +vercel routes list # all routing rules (alias: ls) +vercel routes list --diff # staged changes vs production +vercel routes list --expand # show expanded details for each route +vercel routes list --search "api" # search by name, description, source, or destination +vercel routes list --filter rewrite # filter by type: rewrite, redirect, set_status, transform +vercel routes list --production # list routes from the live production version +vercel routes list --version-id # list routes from a specific version +vercel routes inspect "My Route" # full details of a specific rule ``` ## Creating Routing Rules @@ -75,6 +80,16 @@ Response headers, request headers, and request query parameters can each be set, --delete-request-query "debug" ``` +### Additional create flags + +```bash +--disabled # create the route in disabled state +--position start # place at the top (highest priority) +--position end # place at the bottom +--position after: # place after a specific route +--position before: # place before a specific route +``` + ### Examples ```bash @@ -101,6 +116,11 @@ vercel routes add "Auth Required" \ --action redirect --dest "/login" --status 307 \ --missing "cookie:session" \ --description "Redirect unauthenticated users to login" --yes + +# Create disabled at a specific position +vercel routes add "Maintenance Mode" \ + --src "/(.*)" --action set-status --status 503 \ + --disabled --position start --yes ``` ## Editing Routing Rules @@ -116,6 +136,15 @@ vercel routes edit "My Route" 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 + +# Remove fields +vercel routes edit "My Route" --no-dest --yes # remove destination +vercel routes edit "My Route" --no-status --yes # remove status code + +# Clear collections +vercel routes edit "My Route" --clear-conditions --yes # remove all has/missing conditions +vercel routes edit "My Route" --clear-headers --yes # remove all response headers +vercel routes edit "My Route" --clear-transforms --yes # remove all request transforms ``` ## Managing Routing Rules @@ -123,13 +152,29 @@ vercel routes edit "My Route" --name "New Name" --yes Use `vercel routes list` or `inspect` to find routing rule names and IDs. ```bash -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: # move after another -vercel routes reorder "My Route" --position before: # move before another +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 (alias: rm) +vercel routes delete "Route A" "Route B" # delete multiple at once +vercel routes reorder "My Route" --first --yes # move to top (highest priority) +vercel routes reorder "My Route" --last --yes # move to bottom (lowest priority) +vercel routes reorder "My Route" --position 3 --yes # move to a specific position (1-based) +vercel routes reorder "My Route" --position start # move to top (same as --first) +vercel routes reorder "My Route" --position end # move to bottom (same as --last) +vercel routes reorder "My Route" --position after: # move after another route +vercel routes reorder "My Route" --position before: # move before another route +``` + +Aliases: `reorder` → `move`, `delete` → `rm`. + +## Exporting Routes + +Export routes in `vercel.json` or `vercel.ts` format for use in deployment configuration: + +```bash +vercel routes export # export all routes as JSON +vercel routes export --format ts # export as TypeScript (vercel.ts) +vercel routes export "My Route" # export a specific route ``` ## Publishing & Versioning @@ -138,5 +183,6 @@ vercel routes reorder "My Route" --position before: # move before anothe 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 list-versions --count 20 # fetch up to N versions vercel routes restore # roll back to a previous version ``` diff --git a/skills/vercel-cli/upstream/references/routing.md b/skills/vercel-cli/upstream/references/routing.md index 0bcfbf9..a1ef8e9 100644 --- a/skills/vercel-cli/upstream/references/routing.md +++ b/skills/vercel-cli/upstream/references/routing.md @@ -13,9 +13,14 @@ All changes are staged as drafts. Run `vercel routes publish` to push staged cha ## Viewing Routing Rules ```bash -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 +vercel routes list # all routing rules (alias: ls) +vercel routes list --diff # staged changes vs production +vercel routes list --expand # show expanded details for each route +vercel routes list --search "api" # search by name, description, source, or destination +vercel routes list --filter rewrite # filter by type: rewrite, redirect, set_status, transform +vercel routes list --production # list routes from the live production version +vercel routes list --version-id # list routes from a specific version +vercel routes inspect "My Route" # full details of a specific rule ``` ## Creating Routing Rules @@ -75,6 +80,16 @@ Response headers, request headers, and request query parameters can each be set, --delete-request-query "debug" ``` +### Additional create flags + +```bash +--disabled # create the route in disabled state +--position start # place at the top (highest priority) +--position end # place at the bottom +--position after: # place after a specific route +--position before: # place before a specific route +``` + ### Examples ```bash @@ -101,6 +116,11 @@ vercel routes add "Auth Required" \ --action redirect --dest "/login" --status 307 \ --missing "cookie:session" \ --description "Redirect unauthenticated users to login" --yes + +# Create disabled at a specific position +vercel routes add "Maintenance Mode" \ + --src "/(.*)" --action set-status --status 503 \ + --disabled --position start --yes ``` ## Editing Routing Rules @@ -116,6 +136,15 @@ vercel routes edit "My Route" 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 + +# Remove fields +vercel routes edit "My Route" --no-dest --yes # remove destination +vercel routes edit "My Route" --no-status --yes # remove status code + +# Clear collections +vercel routes edit "My Route" --clear-conditions --yes # remove all has/missing conditions +vercel routes edit "My Route" --clear-headers --yes # remove all response headers +vercel routes edit "My Route" --clear-transforms --yes # remove all request transforms ``` ## Managing Routing Rules @@ -123,13 +152,29 @@ vercel routes edit "My Route" --name "New Name" --yes Use `vercel routes list` or `inspect` to find routing rule names and IDs. ```bash -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: # move after another -vercel routes reorder "My Route" --position before: # move before another +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 (alias: rm) +vercel routes delete "Route A" "Route B" # delete multiple at once +vercel routes reorder "My Route" --first --yes # move to top (highest priority) +vercel routes reorder "My Route" --last --yes # move to bottom (lowest priority) +vercel routes reorder "My Route" --position 3 --yes # move to a specific position (1-based) +vercel routes reorder "My Route" --position start # move to top (same as --first) +vercel routes reorder "My Route" --position end # move to bottom (same as --last) +vercel routes reorder "My Route" --position after: # move after another route +vercel routes reorder "My Route" --position before: # move before another route +``` + +Aliases: `reorder` → `move`, `delete` → `rm`. + +## Exporting Routes + +Export routes in `vercel.json` or `vercel.ts` format for use in deployment configuration: + +```bash +vercel routes export # export all routes as JSON +vercel routes export --format ts # export as TypeScript (vercel.ts) +vercel routes export "My Route" # export a specific route ``` ## Publishing & Versioning @@ -138,5 +183,6 @@ vercel routes reorder "My Route" --position before: # move before anothe 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 list-versions --count 20 # fetch up to N versions vercel routes restore # roll back to a previous version ```