cli: OpenAPI-driven subcommand fallback behind VERCEL_AUTO_API by jeffsee55 · Pull Request #15989 · vercel/vercel

jeffsee55 · 2026-04-15T23:37:12Z

Summary

Adds OpenAPI-driven subcommand resolution behind the VERCEL_AUTO_API=1 environment variable. When enabled:

Top-level tag resolution — unrecognized CLI tokens are matched against OpenAPI tags from openapi.vercel.sh, enabling vercel <tag> <operationId> (e.g. vercel user getAuthUser, vercel teams list).
Per-command fallthrough — commands like vercel projects fall through to OpenAPI tag/operation matching when a token doesn't match a native subcommand (e.g. vercel projects getProject).
x-vercel-cli metadata — operations opt in via x-vercel-cli.supportedSubcommands: true in the OpenAPI spec. Aliases (x-vercel-cli.aliases), positional arguments (x-vercel-cli.kind: 'argument'), and response formatting (x-vercel-cli.displayColumns) are all driven by the spec.
Formatted output — when displayColumns is present in the response schema, results render as a card (single object) or table (array) instead of raw JSON.
The vercel api subcommand itself is unchanged — it continues to handle direct endpoint paths and interactive mode only.

New files

commands/api/display-columns.ts — card/table renderers driven by displayColumns dot-notation paths
commands/api/operation-request-builder.ts — builds API requests from OpenAPI operation specs with interactive prompting
util/openapi/matches-cli-api-tag.ts — checks if a string matches an OpenAPI tag
util/openapi/resolve-by-tag-operation.ts — resolves tag + operationId to an endpoint
util/openapi/resolve-subcommand-with-openapi.ts — merges native subcommands with OpenAPI fallback
util/openapi/try-openapi-fallback.ts — reusable fallback entry point used by top-level and per-command routing

Test plan

Unit tests for matches-cli-api-tag, resolve-by-tag-operation, resolve-subcommand-with-openapi, operation-request-builder
Unit tests for client._fetch teamId preservation
Manual: VERCEL_AUTO_API=1 vercel user getAuthUser renders card with displayColumns
Manual: VERCEL_AUTO_API=1 vercel teams list renders table
Manual: VERCEL_AUTO_API=1 vercel teams get <teamId> renders card
Manual: vercel user getAuthUser (without env var) falls through to normal behavior
Manual: vercel projects list still works as native subcommand

changeset-bot · 2026-04-15T23:37:20Z

🦋 Changeset detected

Latest commit: 9992ee2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
vercel	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2026-04-15T23:38:01Z

Low Risk — New CLI feature gated behind VERCEL_AUTO_API env var — no changes to existing behavior without opt-in.

try-openapi-fallback.ts: new file; early-returns if VERCEL_AUTO_API not set
index.ts: routes unrecognized tokens to OpenAPI tag resolution when env var enabled
client.ts: preserves explicit teamId query param instead of overwriting with config

^{Assessed at 9992ee2.}

github-actions · 2026-04-15T23:38:09Z

📦 CLI Tarball Ready

The Vercel CLI tarball for this PR is now available!

Quick Test

You can test this PR's CLI directly by running:

npx https://vercel-6bo0t97vs.vercel.sh/tarballs/vercel.tgz --help

Use in vercel.json

To use this CLI version in your project builds, add to your vercel.json:

{
  "build": {
    "env": {
      "VERCEL_CLI_VERSION": "vercel@https://vercel-6bo0t97vs.vercel.sh/tarballs/vercel.tgz"
    }
  }
}

Python Runtime Wheel

A vercel-runtime wheel was also built for this PR.
To use in your Python project builds, also set this environment variable:

VERCEL_RUNTIME_PYTHON="vercel-runtime @ https://vercel-6bo0t97vs.vercel.sh/tarballs/vercel_runtime-0.14.0.dev1776368755+9992ee2-py3-none-any.whl"

Python Workers Wheel

A vercel-workers wheel was also built for this PR.
To use in your Python project builds, also set this environment variable:

VERCEL_WORKERS_PYTHON="vercel-workers @ https://vercel-6bo0t97vs.vercel.sh/tarballs/vercel_workers-0.1.0.dev1776368755+9992ee2-py3-none-any.whl"

github-actions · 2026-04-15T23:40:42Z

🧪 Unit Test Strategy

Comparing: 363696d → 9992ee2 (view diff)

Strategy: Affected packages only

✅ Only testing packages that have been modified or depend on modified packages.

Affected packages - 1 (3%)

vercel

Unaffected packages - 39 (98%)

@vercel-internals/get-package-json
@vercel/backends
@vercel/build-utils
@vercel/cervel
@vercel/cli-auth
@vercel/client
@vercel/config
@vercel/detect-agent
@vercel/edge
@vercel/elysia
@vercel/error-utils
@vercel/express
@vercel/fastify
@vercel/firewall
@vercel/frameworks
@vercel/fs-detectors
@vercel/functions
@vercel/gatsby-plugin-vercel-builder
@vercel/go
@vercel/h3
@vercel/hono
@vercel/hydrogen
@vercel/koa
@vercel/nestjs
@vercel/next
@vercel/node
@vercel/oidc
@vercel/oidc-aws-credentials-provider
@vercel/python
@vercel/python-analysis
@vercel/redwood
@vercel/related-projects
@vercel/remix-builder
@vercel/routing-utils
@vercel/ruby
@vercel/rust
@vercel/static-build
@vercel/static-config
examples

Results

Unit tests: Only affected packages will run unit tests
E2E tests: Running in parallel via E2E Tests workflow
Type checks: Only affected packages will run type checks

This comment is automatically generated based on the affected testing strategy

brookemosby

LGTM

- Wire tryOpenApiFallback into teams command default case - Add resolveOpenApiTagForTeamsCli tag resolver - Download openapi.vercel.sh as test fixture - Add 30 unit tests covering x-vercel-cli metadata, displayColumns extraction, parseArrayColumns [] syntax, renderCard/renderTable, and tag+operationId resolution against the real spec Made-with: Cursor

Integrate both the OpenAPI fallback and the autoInstallVercelPlugin post-switch logic from main. Made-with: Cursor

This PR was opened by the [Changesets release](https://github.com/changesets/action) GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated. # Releases ## vercel@51.6.0 ### Minor Changes - Add `vercel connex list` command ([#16018](#16018)) ### Patch Changes - Add OpenAPI-driven subcommand fallback behind `VERCEL_AUTO_API=1`. ([#15989](#15989)) When the env var is set, unrecognized CLI tokens are matched against OpenAPI tags and operation IDs from `openapi.vercel.sh`. This enables `vercel <tag> <operationId>` (e.g. `vercel user getAuthUser`) at the top level, and per-command fallthrough (e.g. `vercel projects getProject`) when a token doesn't match a native subcommand. When `x-vercel-cli.displayColumns` is present in the OpenAPI response schema, results render as a card (single object) or table (array) instead of raw JSON. - [experimental-services] add new job service type support ([#15944](#15944)) - Add naming and formatting utilities for OpenAPI CLI integration. ([#16010](#16010)) Introduces `foldNamingStyle` for case-insensitive matching across camelCase/kebab-case/snake_case, `humanReadableColumnLabel` for converting schema property paths to readable headers, and `inferCliSubcommandAliases` for auto-generating CLI aliases from HTTP methods. - Updated dependencies \[[`44d519b8660185754d8280517adbe0ab7268f540`](44d519b), [`2a6344e205910dafc05cb74a80f98165d95322d7`](2a6344e)]: - @vercel/detect-agent@1.2.3 - @vercel/build-utils@13.17.2 - @vercel/python@6.33.3 - @vercel/backends@0.0.64 - @vercel/elysia@0.1.67 - @vercel/express@0.1.77 - @vercel/fastify@0.1.70 - @vercel/go@3.5.0 - @vercel/h3@0.1.76 - @vercel/hono@0.2.70 - @vercel/hydrogen@1.3.6 - @vercel/koa@0.1.50 - @vercel/nestjs@0.2.71 - @vercel/next@4.16.8 - @vercel/node@5.7.9 - @vercel/redwood@2.4.12 - @vercel/remix-builder@5.7.2 - @vercel/ruby@2.3.2 - @vercel/rust@1.1.1 - @vercel/static-build@2.9.17 ## @vercel/backends@0.0.64 ### Patch Changes - Updated dependencies \[[`2a6344e205910dafc05cb74a80f98165d95322d7`](2a6344e)]: - @vercel/build-utils@13.17.2 ## @vercel/build-utils@13.17.2 ### Patch Changes - [experimental-services] add new job service type support ([#15944](#15944)) ## @vercel/cervel@0.0.51 ### Patch Changes - Updated dependencies \[]: - @vercel/backends@0.0.64 ## @vercel/client@17.3.6 ### Patch Changes - Updated dependencies \[[`2a6344e205910dafc05cb74a80f98165d95322d7`](2a6344e)]: - @vercel/build-utils@13.17.2 ## @vercel/config@0.2.1 ### Patch Changes - [experimental-services] add new job service type support ([#15944](#15944)) ## @vercel/detect-agent@1.2.3 ### Patch Changes - Add v0 to detect-agent supported agents ([#16016](#16016)) ## @vercel/elysia@0.1.67 ### Patch Changes - Updated dependencies \[]: - @vercel/node@5.7.9 ## @vercel/express@0.1.77 ### Patch Changes - Updated dependencies \[]: - @vercel/node@5.7.9 - @vercel/cervel@0.0.51 ## @vercel/fastify@0.1.70 ### Patch Changes - Updated dependencies \[]: - @vercel/node@5.7.9 ## @vercel/fs-detectors@5.18.2 ### Patch Changes - [experimental-services] add new job service type support ([#15944](#15944)) - Updated dependencies \[[`2a6344e205910dafc05cb74a80f98165d95322d7`](2a6344e)]: - @vercel/build-utils@13.17.2 ## @vercel/gatsby-plugin-vercel-builder@2.1.17 ### Patch Changes - Updated dependencies \[[`2a6344e205910dafc05cb74a80f98165d95322d7`](2a6344e)]: - @vercel/build-utils@13.17.2 ## @vercel/h3@0.1.76 ### Patch Changes - Updated dependencies \[]: - @vercel/node@5.7.9 ## @vercel/hono@0.2.70 ### Patch Changes - Updated dependencies \[]: - @vercel/node@5.7.9 ## @vercel/koa@0.1.50 ### Patch Changes - Updated dependencies \[]: - @vercel/node@5.7.9 ## @vercel/nestjs@0.2.71 ### Patch Changes - Updated dependencies \[]: - @vercel/node@5.7.9 ## @vercel/node@5.7.9 ### Patch Changes - Updated dependencies \[[`2a6344e205910dafc05cb74a80f98165d95322d7`](2a6344e)]: - @vercel/build-utils@13.17.2 ## @vercel/python@6.33.3 ### Patch Changes - [experimental-services] add new job service type support ([#15944](#15944)) ## @vercel/static-build@2.9.17 ### Patch Changes - Updated dependencies \[]: - @vercel/gatsby-plugin-vercel-builder@2.1.17 Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

jeffsee55 added 2 commits April 15, 2026 15:25

Add vercel api <tag> <operationId> as an alternative to raw paths

b42c567

Use env var for feature flag instead of behind api sub-command

2be7f4a

jeffsee55 changed the title ~~Add vercel api <tag> <operationId> as an alternative to raw paths~~ Add support for fallback to openapi vercel <tag> <operationId> Apr 15, 2026

vercel Bot deployed to Preview April 15, 2026 23:37 View deployment

Revert changes to api

f26e76f

vercel Bot deployed to Preview April 15, 2026 23:42 View deployment

jeffsee55 changed the title ~~Add support for fallback to openapi vercel <tag> <operationId>~~ cli: OpenAPI-driven subcommand fallback behind VERCEL_AUTO_API Apr 15, 2026

brookemosby approved these changes Apr 16, 2026

View reviewed changes

Improve display logic

d0cb46f

vercel Bot deployed to Preview April 16, 2026 19:15 View deployment

vercel Bot deployed to Preview April 16, 2026 19:40 View deployment

jeffsee55 marked this pull request as ready for review April 16, 2026 19:44

jeffsee55 requested review from a team as code owners April 16, 2026 19:44

Merge main, resolve conflict in project/index.ts

9992ee2

Integrate both the OpenAPI fallback and the autoInstallVercelPlugin post-switch logic from main. Made-with: Cursor

vercel Bot deployed to Preview April 16, 2026 19:47 View deployment

jeffsee55 commented Apr 16, 2026

View reviewed changes

Comment thread packages/cli/src/commands/api/command.ts

jeffsee55 enabled auto-merge (squash) April 16, 2026 20:29

jeffsee55 merged commit fc007cd into main Apr 16, 2026
179 checks passed

jeffsee55 deleted the api-cli-2 branch April 16, 2026 20:38

vercel-cli-release-bot mentioned this pull request Apr 16, 2026

Version Packages #16006

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

cli: OpenAPI-driven subcommand fallback behind VERCEL_AUTO_API#15989

cli: OpenAPI-driven subcommand fallback behind VERCEL_AUTO_API#15989
jeffsee55 merged 6 commits into
mainfrom
api-cli-2

jeffsee55 commented Apr 15, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Apr 15, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Apr 15, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 15, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 15, 2026 •

edited

Loading

Uh oh!

brookemosby left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

jeffsee55 commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

New files

Test plan

Uh oh!

changeset-bot Bot commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel Bot commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📦 CLI Tarball Ready

Quick Test

Use in vercel.json

Python Runtime Wheel

Python Workers Wheel

Uh oh!

github-actions Bot commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🧪 Unit Test Strategy

Results

Uh oh!

brookemosby left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jeffsee55 commented Apr 15, 2026 •

edited

Loading

changeset-bot Bot commented Apr 15, 2026 •

edited

Loading

vercel Bot commented Apr 15, 2026 •

edited

Loading

github-actions Bot commented Apr 15, 2026 •

edited

Loading

github-actions Bot commented Apr 15, 2026 •

edited

Loading