vercel ai-gateway

The vercel ai-gateway command manages AI Gateway resources from the Vercel CLI, including API keys, budgets, routing rules, 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, and remove subcommands also accept --json, which does the same thing. coding-agents 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 --budget 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. Each scope except team takes an identifier after the scope name.

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

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.

vercel ai-gateway budgets ls

Remove the budget for a scope, using the same scope names and identifiers as set. 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

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.

vercel ai-gateway budgets defaults [subcommand]

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

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

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

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.

vercel ai-gateway coding-agents [subcommand]

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: 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 coding-agents 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 name for a new key. The prompt suggests [<user>'s <device>] Coding Agents.
5. Team that owns the key.
6. Spend limit (quota) for the key.
7. Expiration for the key.
8. 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 coding-agents 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. The value is written verbatim to the agents that carry a URL, and it 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: it marks the traffic as coming from a coding agent, and it gives behavior that turns out to be common to every harness somewhere to live later, without you having to edit your config again.

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.

For Claude Code, Codex, OpenCode, Pi, Kilo Code, and Cursor, the command pins no model, so you keep choosing your own inside the agent. Cline, Hermes, and OpenClaw can't start without one, so they get anthropic/claude-fable-5 as a starting point. 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: a session that was already copied is skipped. 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: 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. Pi is the exception: it always keeps the key in its own auth file.

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 is a no-op: it 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 the full setup again, 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 coding-agents 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 and Cline 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).

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.

vercel ai-gateway models ls

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 --budget 500 --refresh-period monthly --alert-thresholds 75,100

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

vercel ai-gateway coding-agents setup --yes

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

vercel ai-gateway coding-agents setup --all --yes

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

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

vercel ai-gateway coding-agents setup --reconfigure --yes

vercel ai-gateway coding-agents 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.