vercel ai-gateway

The vercel ai-gateway command manages AI Gateway resources from the Vercel CLI, including API keys, budgets, routing rules, virtual models, models, leaderboards, and coding agents.

vercel ai-gateway [subcommand]

Most subcommands accept --format json (-F json) to print a machine-readable payload instead of a table. The rules, models, and budgets set, list, inspect, and remove subcommands also accept --json, which does the same thing. setup uses --non-interactive instead.

Manage AI Gateway API keys for the current team.

vercel ai-gateway api-keys [subcommand]

Create a new AI Gateway API key. The CLI returns the plaintext key once; store it securely.

vercel ai-gateway api-keys create

vercel ai-gateway api-keys create --name my-key --limit 500 --refresh-period monthly

vercel ai-gateway api-keys create --name escape-hatch --zdr-exempt --expiration 7d

List the AI Gateway API keys for the current team. The table shows each key's ID, name, masked key, quota, and expiry. Alias: ls.

vercel ai-gateway api-keys ls

Show the details of one API key, including its quota, current spend, alert thresholds, and expiry. Keys created with --zdr-exempt also show a zdr exempt row, so you can audit which keys carry the exemption.

vercel ai-gateway api-keys inspect key_123

Remove an API key by its ID. Aliases: rm, delete. Pass --yes to skip the confirmation prompt.

vercel ai-gateway api-keys remove key_123 --yes

Manage AI Gateway budgets, which are metered spend limits scoped to your team, a project, an API key, or a team member.

vercel ai-gateway budgets [subcommand]

Create or update the budget for a scope, or the scope's default budget with --default. Each scope except team takes an identifier after the scope name; a default takes none.

vercel ai-gateway budgets set team --limit 500 --refresh-period monthly

vercel ai-gateway budgets set project my-project --limit 200

vercel ai-gateway budgets set api-key my-key --limit 50 --refresh-period weekly

vercel ai-gateway budgets set user teammate@example.com --limit 100 --refresh-period monthly

vercel ai-gateway budgets set user --default --limit 50 --refresh-period monthly

List the budgets for the current team, with each budget's scope, limit, current spend, and refresh cadence. User-scoped budgets are listed by member handle. Alias: ls. Filter to one scope with --scope-type, or list the team's default budget policy with --defaults.

vercel ai-gateway budgets ls

vercel ai-gateway budgets ls --scope-type user

vercel ai-gateway budgets ls --defaults

Show one budget for a scope, or a scope's default budget with --default, using the same scope names and identifiers as set.

vercel ai-gateway budgets inspect user teammate@example.com

vercel ai-gateway budgets inspect project my-project --format json

Remove the budget for a scope, using the same scope names and identifiers as set, or a scope's default budget with --default. Aliases: rm, delete.

Removing a budget lifts that scope's own cap. A project, key, or member still covered by a default falls back to that default rather than becoming unlimited.

vercel ai-gateway budgets remove team

vercel ai-gateway budgets remove project my-project --yes

vercel ai-gateway budgets remove api-key my-key

vercel ai-gateway budgets remove user teammate@example.com

vercel ai-gateway budgets remove user --default

Manage budget defaults. A default applies to every resource of that scope that has no budget of its own, so new projects, new API keys, and new team members inherit a spend limit instead of starting unlimited.

Set or remove a default with the --default flag on set and remove, show one with inspect, and list the policy with list --defaults:

vercel ai-gateway budgets set project --default --limit 200 --refresh-period monthly

vercel ai-gateway budgets set api-key --default --limit 50

vercel ai-gateway budgets set user --default --limit 50 --refresh-period monthly

vercel ai-gateway budgets ls --defaults

vercel ai-gateway budgets remove user --default

Manage AI Gateway routing rules for the current team. A rule rewrites a request from one model to another, or denies a model. See the routing rules documentation for concepts, request behavior, and propagation details.

vercel ai-gateway rules [subcommand]

Add a routing rule. A rewrite rule requires --destination; a deny rule does not.

vercel ai-gateway rules add --type rewrite --source anthropic/claude-opus-5 --destination anthropic/claude-haiku-4.5

vercel ai-gateway rules add --type deny --source openai/gpt-5.6-sol

List routing rules for the current team. Alias: ls. Pass --include-disabled to also show disabled rules.

vercel ai-gateway rules list

Edit a rule by its ID. Change the destination, reason, or description, or toggle the rule with --enable / --disable.

vercel ai-gateway rules edit rule_123 --disable

Remove a rule by its ID. Aliases: rm, delete. Pass --yes to skip the confirmation prompt.

vercel ai-gateway rules remove rule_123 --yes

Connect local coding agents to AI Gateway.

Run the setup command with npx:

npx vercel ai-gateway setup

npx runs Vercel CLI without installing it globally. To keep vercel available as a global command, install or update the CLI before running setup:

npm i -g vercel@latest
vercel ai-gateway setup

vercel ai-gateway setup is the canonical command. The older spelling, vercel ai-gateway coding-agents setup, still works as an alias, and managed shell blocks written under the old name are still recognized as configured.

Configure supported coding agents to route requests through AI Gateway. The command provisions or reuses an AI Gateway API key and writes each agent's config file so requests use the gateway with your key.

This is the recommended way to connect an agent because it picks the right compatibility URL per agent, keeps your key out of plaintext config on macOS, and preserves your existing desktop sessions. The coding agents guide covers the same agents from the other direction, with per-agent features and manual configuration for the tools this command doesn't handle.

vercel ai-gateway setup --yes

Run the command without flags to step through each prompt in order:

1. Agents to configure. The agents detected on your machine (their config directory exists) are pre-selected.
2. Consent for any agent with a pre-flight warning, described in Warnings and consent. Declining skips that agent and continues with the others.
3. Session migration, when you have Claude Desktop or Codex Desktop sessions that would otherwise disappear from the switched provider. See Desktop session migration.
4. API key source: create a new key or paste an existing one. The prompt defaults to create, and to use an existing key when your agent configs already point at the gateway.
5. API key name for a new key. The prompt suggests [<user>'s <device>] Coding Agents.
6. Team that owns the key.
7. Spend limit (quota) for the key.
8. Expiration for the key.
9. Keychain storage on macOS: whether to store the key in your Keychain (default yes).

When a selected agent isn't found at its default location, the command also offers to set a custom config path. It then prints a summary and the planned changes as a per-file diff with the key masked, and asks you to confirm. Declining writes nothing and never creates a key.

The command treats every agent the same way. Detection pre-selects the ones already installed on your machine, --all covers every agent in the table, and the interactive checklist lists them in this order. To connect a subset, name each one with --agent:

vercel ai-gateway setup --agent cursor --agent kilo

AI Gateway serves several compatibility surfaces, and each agent gets the one its client speaks. The command picks these for you, which is the main reason to prefer it over hand-editing a config file:

Pass --base-url <URL> to write a different base URL, for example a preview deployment of the gateway. Most agents write the value verbatim. ForgeCode, Goose, and Junie CLI append /chat/completions, and ForgeCode also appends /models for model discovery. The option has no effect on agents that use a first-party provider.

Every agent without a dedicated endpoint should point at the shared coding agent surface:

https://ai-gateway.vercel.sh/coding-agent/v1

It passes straight through to the standard /v1 handlers, so auth, routing, billing, CORS, and errors behave exactly as they do on the bare /v1 surface, and unknown paths return the same JSON 404. Use it anyway because it marks the traffic as coming from a coding agent. It also gives behavior shared across harnesses somewhere to live later, without requiring another config edit.

For a client that speaks the Anthropic protocol and appends /v1/messages itself, drop the /v1 and use https://ai-gateway.vercel.sh/coding-agent.

The command edits existing files in place, preserving their formatting, and saves a .bak copy first. Disable backups with --no-backup. If it can't parse a file, it skips that file instead of overwriting it.

Shell exports live in a marked, removable block in your shell's startup file: ~/.zshrc for zsh (honors $ZDOTDIR), ~/.bash_profile on macOS or ~/.bashrc elsewhere for bash, config.fish for fish, or ~/.profile otherwise. Pass --shell-rc <path> to target a different file, or --agent-config <agent>=<path> to override an agent's config location. On Windows, there's no shell startup file to manage. The command tells you which environment variable to set and prints a newly created key once so you don't lose it.

Model lists come from the AI Gateway leaderboard instead of a hardcoded snapshot. The command ranks text models by spend and writes the top 10 into each agent's picker. A harness with a preferred model family, such as DeepSeek Harness, Kimi CLI, Qwen Code, or Mistral Vibe, leads its shortlist with the newest models from that family and follows with the leaderboard's most-used.

For Claude Code, Codex, OpenCode, Pi, Kilo Code, Cursor, fx, and omp, the command pins no model, so you keep choosing your own inside the agent. The other agents can't start without one, so they get the top-ranked model as a starting point, falling back to anthropic/claude-fable-5 when the leaderboard lookup fails. Change it at any time:

Switching providers hides the sessions that were recorded under the old one. When the command finds those sessions, it offers to copy them into the gateway provider so your history stays visible. Originals are never moved, edited, or deleted.

Copies are atomic, use mode 0600, and never clobber an existing destination. Re-running is safe because the command skips sessions that were already copied. If a copy fails, the command leaves your agent configuration untouched and exits 1 so you can retry.

Interactively, you get one prompt and can decline. With --yes or in non-interactive mode, eligible sessions are copied. Pass --no-session-migration to skip the whole step. Compressed Codex sessions (.jsonl.zst) can't be rewritten. Decompress them first, or pass --no-session-migration.

Connecting can break an agent's existing setup. Before asking any key questions, the command checks each selected agent for known conflicts and asks for explicit consent, so you can bail before a key is created. Detection only checks whether an app is installed; the command never reads your data.

Interactively, each warned agent gets its own confirmation, defaulting to no. Declining leaves that agent's files untouched, and the run continues with the other agents.

With --yes or in non-interactive mode, naming an agent with --agent (or passing --all) counts as consent, so the run proceeds and prints the warnings. The command skips a warned agent that was only selected by detection, with reason requires_consent and a hint to pass --agent <id>. If that skips every agent, the command exits 1 with reason requires_consent and a ready-to-run command that replays the invocation with the consent flags added. --dry-run never asks for consent; it prints the warnings and shows what a real run would do.

On macOS, the command stores the API key in your login Keychain by default instead of writing it into plaintext config. It saves the key as a generic password with the service name "Vercel AI Gateway", and agents read it through shell exports that call security find-generic-password when a terminal starts. Some agents are the exception because they can't read the Keychain: Pi, Cline, ForgeCode, Kimi CLI, OpenHands, and ZCode always keep the key in their own config files.

Pass --no-keychain, or run on a non-macOS host, to write the key directly into each agent's config file, or into the shell startup file, instead. If the Keychain write fails during setup, the command falls back to this mode automatically.

The command uses a single Keychain item, so connecting a different team replaces the stored key. Human-readable output masks the key as vck_••••1234.

By default the command writes the files itself. On a Keychain setup, the confirmation prompt offers a third option. Instead of writing, it generates a prompt describing the exact edits and copies it to your clipboard, so you can hand the work to a coding agent you already have open. Because the key lives in the Keychain, that prompt carries no secret.

Pass --apply to choose without prompting:

Re-running the command against an already-configured setup doesn't mint a second key or orphan the working one. When your agent configs already point at the gateway, the command reuses the key it finds. Interactively, the key prompt defaults to Use an existing key so you can paste a different one; without prompts, the stored key (Keychain entry or managed shell export) is recovered and used. This also refreshes stale model lists, since the shortlists come from the leaderboard. When nothing needs to change, the command asks whether to reconfigure interactively (default no) and otherwise exits 0, reporting reason already_configured in non-interactive output. No new key is minted.

• Pass --reconfigure to run setup again when agents are already configured, for example to rotate the key or switch teams.
• Run setup --key <new-key> on a Keychain setup to swap in a rotated or expired key. The command refreshes the Keychain entry in place without touching config files.
• When everything is already configured but sessions are still waiting to be copied, the run does the migration alone and leaves your key and config as they are.

The --yes option skips every prompt, which makes the command fully non-interactive. Combined with the defaults below, vercel ai-gateway setup --yes is the shortest complete run:

Pass --non-interactive to emit a single JSON object instead of human-readable output. The CLI also switches to this mode on its own when it detects it's running inside a coding agent and stdin isn't a TTY. Agent selection follows the same detected-agents default as --yes.

The payload includes status, a reason, a message, the list of configured files (changes for a dry run), any migrated sessions, any skipped entries, per-agent notes, and a warnings array of {agent, code, message} objects. On a consent failure, a next array carries a ready-to-run replay command. The success payload contains the full API key, and --apply prompt returns the generated prompt in prompt, so treat the output as a secret.

If at least one agent config can be written, the run exits 0 and lists the rest under skipped. When nothing can be written, the command exits 1 and doesn't create a key.

• Open a new terminal after connecting so the shell exports load. Codex always reads AI_GATEWAY_API_KEY from your environment; in Keychain mode, every agent except Pi, Cline, ForgeCode, Kimi CLI, OpenHands, and ZCode reads its key from the shell.
• Restart Claude Code so it picks up the new settings, and restart the OpenClaw gateway process so it loads the new provider.
• The command exits 0 on success or a no-op, 1 on an operational failure or invalid input, and 2 when it shows help (--help).

Manage virtual models for the current team. A virtual model is a reusable model configuration you call as vmc/<slug>, so routing, credentials, and provider options live in one place instead of in every request. See the virtual models documentation for concepts and request behavior.

vercel ai-gateway virtual-models [subcommand]

Every subcommand accepts --format json (or --json) for machine-readable output.

Create a virtual model. Run it with no arguments to be prompted for the slug and target model.

vercel ai-gateway virtual-models create

vercel ai-gateway virtual-models create my-model --model openai/gpt-5.1

Fields without a dedicated flag are set through --config, which takes a JSON object. Flags take precedence over the same key in --config.

vercel ai-gateway virtual-models create my-model --model openai/gpt-5.1 --config '{"sort":"cost","zeroDataRetention":true}'

List virtual models for the current team. Alias: ls. Archived virtual models are hidden unless you pass --include-archived.

vercel ai-gateway virtual-models list

Show every field set on a virtual model, by slug.

vercel ai-gateway virtual-models inspect my-model

Edit a virtual model by its slug. Takes the same field flags and --config as create except --kind, which is create-only, and requires at least one of them.

vercel ai-gateway virtual-models edit my-model --model anthropic/claude-sonnet-4.5

Remove a virtual model by its slug. Aliases: rm and delete. There is no confirmation prompt, so the virtual model is removed as soon as the command runs. Requests to vmc/<slug> stop resolving once it is removed, and the configuration is preserved so you can restore it later.

Removing is not the same as archiving. A removed virtual model stops resolving and no longer appears in list, even with --include-archived. An archived one still appears, labeled archived.

vercel ai-gateway virtual-models rm my-model

Restore a removed virtual model by its slug. Requests to vmc/<slug> resolve again, using the configuration the virtual model had before it was removed. Because a removed virtual model is not listed, you need to know its slug.

vercel ai-gateway virtual-models restore my-model

Browse the models available through AI Gateway and compare the providers that serve them. Both commands are read-only. Add --format json to either command for the full, machine-readable payload.

vercel ai-gateway models [subcommand]

List the models available through AI Gateway. The table shows each model's ID, name, owner, and type. Alias: ls. Your team's virtual models are listed alongside the catalog, and you can narrow the list to one or the other.

vercel ai-gateway models ls

vercel ai-gateway models ls --virtual

List the provider endpoints that serve a model. The table shows each endpoint's context window, input and output pricing, time-to-first-token latency, and uptime. Run vercel ai-gateway models ls to find model IDs.

vercel ai-gateway models endpoints <model-id>

vercel ai-gateway models endpoints anthropic/claude-opus-5

Explore the AI Gateway leaderboards, the open, anonymized usage data published under CC BY 4.0. Alias: leaderboards. Every subcommand is read-only.

vercel ai-gateway leaderboard [subcommand]

vercel ai-gateway leaderboard models --modality text

vercel ai-gateway leaderboard labs --metric spend

vercel ai-gateway leaderboard models --format csv --out models.csv

vercel ai-gateway api-keys create --name my-key --limit 500 --refresh-period monthly --alert-thresholds 75,100

vercel ai-gateway budgets set project --default --limit 200 --refresh-period monthly

vercel ai-gateway setup --yes

vercel ai-gateway setup \
  --agent claude-code --agent codex \
  --name "My Coding Key" \
  --scope my-team \
  --budget 500 --refresh-period monthly \
  --expiration 30d \
  --yes

vercel ai-gateway setup --all --yes

vercel ai-gateway setup --apply prompt --yes

vercel ai-gateway setup --key vck_... --dry-run

vercel ai-gateway setup --reconfigure --yes

vercel ai-gateway setup --agent codex --base-url https://preview.ai-gateway.vercel.sh/coding-agent/v1

• AI Gateway overview
• Coding agents
• AI Gateway models and providers
• AI Gateway routing rules
• AI Gateway authentication
• AI Gateway API keys

The following global options can be passed when using the vercel ai-gateway command:

• --cwd
• --debug
• --global-config
• --help
• --local-config
• --no-color
• --non-interactive
• --scope
• --team
• --token
• --version

For more information on global options and their usage, refer to the options section.