---
title: vercel ai-gateway
product: vercel
url: /docs/cli/ai-gateway
canonical_url: "https://vercel.com/docs/cli/ai-gateway"
last_updated: 2026-09-17
type: reference
prerequisites:
  - /docs/cli
related:
  - /docs/ai-gateway
  - /docs/ai-gateway/observability-and-spend
  - /docs/ai-gateway/models-and-providers/routing-rules
  - /docs/ai-gateway/models-and-providers/virtual-models
  - /docs/ai-gateway/models-and-providers
summary: "Manage AI Gateway resources from the Vercel CLI: API keys, budgets, routing rules, virtual models, models, leaderboards, requests, sessions, and..."
install_vercel_plugin: npx plugins add vercel/vercel-plugin
search_with_vercel_cli: npx vercel@latest docs search "<query>"
---

# vercel ai-gateway

The `vercel ai-gateway` command manages [AI Gateway](/docs/ai-gateway) resources from the Vercel CLI, including API keys, [budgets](/docs/ai-gateway/observability-and-spend), [routing rules](/docs/ai-gateway/models-and-providers/routing-rules), [virtual models](/docs/ai-gateway/models-and-providers/virtual-models), [models](/docs/ai-gateway/models-and-providers), leaderboards, [requests and sessions](/docs/ai-gateway/observability-and-spend/logs), and [coding agents](/docs/ai-gateway/coding-agents).


<!-- docsgraph:related -->
## Related pages

> **For AI agents:** Follow these links to understand how this page connects to the rest of the Vercel ecosystem. For the full cross-link map (inbound, outbound, prerequisites, and semantic neighbors), see the .graph.md link below.

- [AI Gateway now supports Private Inference](https://vercel.com/changelog/ai-gateway-now-supports-private-inference)
- [Ember-1 from Fireworks now available on AI Gateway](https://vercel.com/changelog/ember-1-from-fireworks-now-available-on-ai-gateway)
- [Kimi K3 and Kimi K3 Fast with ZDR and US-based providers now on AI Gateway](https://vercel.com/changelog/kimi-k3-and-kimi-k3-fast-on-ai-gateway)
- [Pixel Canary is now available in stealth for free on AI Gateway](https://vercel.com/changelog/pixel-canary-is-now-available-in-stealth-for-free-on-ai-gateway)
- [Set up coding agents in one command with AI Gateway](https://vercel.com/changelog/set-up-coding-agents-in-one-command-with-ai-gateway)
- [Introducing Virtual Models on AI Gateway](https://vercel.com/blog/ai-gateway-virtual-models)
- [Run Python code securely with AI SDK and Vercel Sandbox](https://vercel.com/kb/guide/python-ai-sdk-vercel-sandbox) — Add an \\`executeCode\\` tool to your AI SDK agent with the \\`ai-sdk-tool-code-execution\\` package to run Python 3.13 insi
- [Amp with AI Gateway](https://vercel.com/docs/ai-gateway/coding-agents/amp) — Connect Amp to AI Gateway through Amp's Model Routing settings. Add an AI Gateway API key, choose models for Amp's modes
- [AI Gateway Trace Drains](https://vercel.com/docs/ai-gateway/observability-and-spend/trace-drains) — Forward an OpenTelemetry trace of every AI Gateway request to your own observability tool, and understand trace drain bi
- [vercel setup](https://vercel.com/docs/cli/setup) — Set up coding agents for Vercel with one command: install the Vercel plugin for Claude Code, Codex, and OpenCode, and co

Full cross-link map for this page: [/docs/cli/ai-gateway.graph.md](/docs/cli/ai-gateway.graph.md)
<!-- /docsgraph:related -->

> **💡 Note:** Connecting a coding agent? [`vercel ai-gateway setup`](#setup) is the
> recommended way to do it. For per-agent behavior, model pickers, and manual
> configuration, see the [coding agents guide](/docs/ai-gateway/coding-agents).

## Usage

```bash filename="terminal"
vercel ai-gateway [subcommand]
```

*Using the \`vercel ai-gateway\` command to manage AI Gateway resources for the
current team.*

Most subcommands accept `--json` to print a machine-readable payload instead of a table. [`leaderboard`](#leaderboard) takes `--format json` instead, and [`setup`](#setup) uses [`--non-interactive`](#non-interactive-output).

## Commands

### api-keys

Manage AI Gateway API keys for the current team.

```bash filename="terminal"
vercel ai-gateway api-keys [subcommand]
```

#### create

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

```bash filename="terminal"
vercel ai-gateway api-keys create
```

*Create an API key with the default settings.*

```bash filename="terminal"
vercel ai-gateway api-keys create --name my-key --amount 500 --refresh-period monthly
```

*Create an API key with a human-readable name and a monthly $500 quota.*

```bash filename="terminal"
vercel ai-gateway api-keys create --name token-pass --token-pass
```

*Create a key that spends only your team's Token Pass credit.*

##### Options

| Option | Type | Description |
| --- | --- | --- |
| `--name <NAME>` | String | Human-readable name for the API key |
| `--amount <USD>` | Number | Quota budget limit in dollars (minimum 1) |
| `--refresh-period <PERIOD>` | String | Quota refresh cadence: `daily`, `weekly`, `monthly`, or `none` (default `none`) |
| `--include-byok` | Boolean | Include [BYOK](/docs/ai-gateway/authentication-and-byok/byok) usage in the key's quota (default off) |
| `--alert-thresholds <LIST>` | String | Comma-separated spend percentages to alert at, a subset of `50`, `75`, and `100`, for example `75,100` |
| `--expiration <PERIOD>` | String | Expiry for the key: `7d`, `30d`, `60d`, `90d`, `1y`, or `none` (default `none`) |
| `--token-pass` | Boolean | Scope the key to [Token Pass](/docs/ai-gateway/token-pass). The key spends only your team's Token Pass credit, on Token Pass models only. You can't change this after creation, and you can't combine it with `--zdr-exempt` or `--bypass-all-settings` |
| `--zdr-exempt` | Boolean | Exempt the key from the team's [zero data retention](/docs/ai-gateway/security-and-compliance/zdr) (ZDR) only model restriction. Team owners only |
| `--bypass-all-settings` | Boolean | Exempt the key from all of the team's restrictions: ZDR-only models, the [provider allowlist](/docs/ai-gateway/security-and-compliance/provider-allowlist) and [model allowlist](/docs/ai-gateway/security-and-compliance/model-allowlist), and the HIPAA and [prompt-training](/docs/ai-gateway/security-and-compliance/disallow-prompt-training) filters. Team owners only |

> **⚠️ Warning:** A ZDR-exempt key can reach models that don't offer zero data retention, which
> is why only team owners can create one. A key created with
> `--bypass-all-settings` skips every team restriction, so the same rule
> applies. Pair either option with `--expiration` so the exemption doesn't
> outlive the work that needed it.

```bash filename="terminal"
vercel ai-gateway api-keys create --name escape-hatch --zdr-exempt --expiration 7d
```

*Create a ZDR-exempt key that expires in seven days.*

```bash filename="terminal"
vercel ai-gateway api-keys create --name escape-hatch --bypass-all-settings --expiration 7d
```

*Create a key that bypasses all team restrictions and expires in seven days.*

#### list

List the AI Gateway API keys for the current team. The table shows each key's ID, name, masked key, budget, current spend, refresh period, and creation date. The list leaves out expired keys unless you pass `--state expired` or `--state any`.

```bash filename="terminal"
vercel ai-gateway api-keys list
```

##### Options

| Option | Type | Description |
| --- | --- | --- |
| `--query <TEXT>`, `-q` | String | Only list keys whose name or key suffix contains this text. The match ignores case |
| `--creator <USER>` | String | Only list keys that one team member created. Pass an email, username, or user ID, or `me` for your own keys |
| `--state <STATE>` | String | Which keys to list: `active` (not expired), `expired`, `deleted`, or `any` (default `active`) |
| `--sort <FIELD>` | String | Sort by `createdAt`, `lastActiveAt`, `name`, or `expiresAt`. Add `:asc` or `:desc` to set the direction (default `lastActiveAt:desc`) |
| `--limit <NUMBER>` | Number | Maximum number of keys per page (default 20, maximum 100) |
| `--next <CURSOR>` | String | Fetch the next page using the cursor from `pagination.next` |
| `--json` | Boolean | Print the full key payload as JSON |

JSON output includes `pagination.next` when another page is available. Human-readable output prints a next-page command hint. Fetch a page of 50 keys, then use the returned cursor:

```bash filename="terminal"
vercel ai-gateway api-keys list --limit 50 --json
vercel ai-gateway api-keys list --limit 50 --next='<cursor>' --json
```

API key lookup by name, such as `budgets set api-key my-key`, searches all pages of keys.

#### inspect

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

```bash filename="terminal"
vercel ai-gateway api-keys inspect key_123
```

##### Options

| Option | Type | Description |
| --- | --- | --- |
| `--json` | Boolean | Print the full key payload as JSON |

#### revoke

Revoke an API key by its ID. Pass `--yes` to skip the confirmation prompt.

```bash filename="terminal"
vercel ai-gateway api-keys revoke key_123 --yes
```

##### Options

| Option | Type | Description |
| --- | --- | --- |
| `--yes`, `-y` | Boolean | Skip the confirmation prompt |
| `--json` | Boolean | Print the machine-readable payload as JSON |

### budgets

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

```bash filename="terminal"
vercel ai-gateway budgets [subcommand]
```

#### set

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.

| Scope | Identifier |
| --- | --- |
| `team` | None |
| `project` | Project name or ID |
| `api-key` | Key name or ID. A name shared by several keys errors and asks for the ID, which `api-keys list` shows |
| `user` | Member email, username, or user ID |

```bash filename="terminal"
vercel ai-gateway budgets set team --amount 500 --refresh-period monthly
```

*Cap team-wide AI Gateway spend at $500 per month.*

```bash filename="terminal"
vercel ai-gateway budgets set project my-project --amount 200
```

*Cap one project at $200.*

```bash filename="terminal"
vercel ai-gateway budgets set api-key my-key --amount 50 --refresh-period weekly
```

*Cap one API key at $50 per week.*

```bash filename="terminal"
vercel ai-gateway budgets set user teammate@example.com --amount 100 --refresh-period monthly
```

*Cap one team member at $100 per month across every key attributed to them.*

```bash filename="terminal"
vercel ai-gateway budgets set user --default --amount 50 --refresh-period monthly
```

*Give every team member without their own budget a $50 monthly limit.*

```bash filename="terminal"
vercel ai-gateway budgets set user teammate@example.com --amount 100 --message "Eval run for the launch"
```

*Record why the budget changed in the team's activity log.*

##### Options

| Option | Type | Description |
| --- | --- | --- |
| `--amount <USD>` | Number | Budget limit in dollars (minimum 1) |
| `--refresh-period <PERIOD>` | String | Budget refresh cadence: `daily`, `weekly`, `monthly`, or `none` (default `monthly`) |
| `--message <TEXT>` | String | The [reason for the change](/docs/ai-gateway/observability-and-spend/budgets#reasons-for-budget-changes), recorded in the team's [activity log](/docs/activity-log) and shown as `Reason` in the output. Optional, up to 500 characters |
| `--default` | Boolean | Target the scope's default budget, applied to resources of that scope without their own budget |
| `--json` | Boolean | Print the machine-readable payload as JSON |

#### list

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. Filter to one scope with `--scope-type`, or list the team's default budget policy with `--defaults`.

```bash filename="terminal"
vercel ai-gateway budgets list
```

```bash filename="terminal"
vercel ai-gateway budgets list --scope-type user
```

*List only the user-scoped budgets.*

```bash filename="terminal"
vercel ai-gateway budgets list --defaults
```

*List the team's budget defaults.*

##### Options

| Option | Type | Description |
| --- | --- | --- |
| `--scope-type <SCOPE>` | String | Only list budgets for one scope: `team`, `project`, `user`, or `api-key` |
| `--defaults` | Boolean | List the team's default budgets instead of individual budgets |
| `--json` | Boolean | Print the machine-readable payload as JSON |

#### inspect

Show one budget for a scope, or a scope's default budget with `--default`, using the same scope names and identifiers as [`set`](#set).

```bash filename="terminal"
vercel ai-gateway budgets inspect user teammate@example.com
```

*Show one team member's budget and current spend.*

```bash filename="terminal"
vercel ai-gateway budgets inspect project my-project --json
```

*Print a project budget's machine-readable payload.*

##### Options

| Option | Type | Description |
| --- | --- | --- |
| `--default` | Boolean | Show the scope's default budget |
| `--json` | Boolean | Print the machine-readable payload as JSON |

#### remove

Remove the budget for a scope, using the same scope names and identifiers as [`set`](#set), or a scope's default budget with `--default`.

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

```bash filename="terminal"
vercel ai-gateway budgets remove team
```

```bash filename="terminal"
vercel ai-gateway budgets remove project my-project --yes
```

```bash filename="terminal"
vercel ai-gateway budgets remove api-key my-key
```

```bash filename="terminal"
vercel ai-gateway budgets remove user teammate@example.com --message "Left the team"
```

```bash filename="terminal"
vercel ai-gateway budgets remove user --default
```

*Remove the per-member default budget.*

##### Options

| Option | Type | Description |
| --- | --- | --- |
| `--yes`, `-y` | Boolean | Skip the confirmation prompt |
| `--message <TEXT>` | String | The reason for the change, recorded in the team's [activity log](/docs/activity-log). Optional, up to 500 characters |
| `--default` | Boolean | Remove the scope's default budget |
| `--json` | Boolean | Print the machine-readable payload as JSON |

#### Default budgets

A default budget applies to every project, API key, or team member 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`](#set) and [`remove`](#remove), show one with [`inspect`](#budgets-inspect), and list the policy with [`list --defaults`](#budgets-list):

```bash filename="terminal"
vercel ai-gateway budgets set project --default --amount 200 --refresh-period monthly
```

*Give every project without its own budget a $200 monthly limit.*

```bash filename="terminal"
vercel ai-gateway budgets set api-key --default --amount 50
```

*Give every API key without its own quota a $50 limit.*

```bash filename="terminal"
vercel ai-gateway budgets set user --default --amount 50 --refresh-period monthly
```

*Give every team member without their own budget a $50 monthly limit.*

```bash filename="terminal"
vercel ai-gateway budgets list --defaults
```

*List the team's budget defaults.*

```bash filename="terminal"
vercel ai-gateway budgets remove user --default
```

*Remove the per-member default budget.*

### rules

Manage [AI Gateway routing rules](/docs/ai-gateway/models-and-providers/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](/docs/ai-gateway/models-and-providers/routing-rules) for concepts, request behavior, and propagation details.

```bash filename="terminal"
vercel ai-gateway rules [subcommand]
```

#### add

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

```bash filename="terminal"
vercel ai-gateway rules add --type rewrite --source anthropic/claude-opus-5 --destination anthropic/claude-haiku-4.5
```

*Route requests for one model to another.*

```bash filename="terminal"
vercel ai-gateway rules add --type deny --source openai/gpt-5.6-sol
```

*Block requests for a model.*

##### Options

| Option | Type | Description |
| --- | --- | --- |
| `--type <TYPE>` | String | Rule type: `rewrite` or `deny` (required) |
| `--source <MODEL>` | String | Model the rule matches (required) |
| `--destination <MODEL>` | String | Target model a `rewrite` rule routes to |
| `--reason <TEXT>` | String | Reason surfaced when the rule applies |
| `--description <TEXT>` | String | Human-readable description of the rule |
| `--json` | Boolean | Print the machine-readable payload as JSON |

#### list

List routing rules for the current team. Pass `--include-disabled` to also show disabled rules.

```bash filename="terminal"
vercel ai-gateway rules list
```

#### update

Update a rule by its ID. Change the destination, reason, or description. Pass `--no-enable` to turn a rule off, and `--enable` to turn it back on:

```bash filename="terminal"
vercel ai-gateway rules update rule_123 --no-enable
```

#### remove

Remove a rule by its ID. Pass `--yes` to skip the confirmation prompt.

```bash filename="terminal"
vercel ai-gateway rules remove rule_123 --yes
```

### setup

Connect local coding agents to [AI Gateway](/docs/ai-gateway).

Run the setup command with `npx`:

```bash filename="terminal"
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:

```bash filename="terminal"
npm i -g vercel@latest
vercel ai-gateway setup
```

Configure [supported coding agents](#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](#gateway-urls-the-command-writes) per agent, keeps your key out of plaintext config on macOS, and preserves your existing desktop sessions. The [coding agents guide](/docs/ai-gateway/coding-agents) covers the same agents from the other direction, with per-agent features and manual configuration for the tools this command doesn't handle.

```bash filename="terminal"
vercel ai-gateway setup --yes
```

*Connect the coding agents detected on this machine without any prompts.*

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](#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](#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. **Team** that owns the key.
6. **API key name** for a new key. The prompt suggests `[<user>'s <device>] Coding Agents`.
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.

#### Supported coding agents

| Agent | `--agent` value |
| --- | --- |
| [Aider](/docs/ai-gateway/coding-agents/aider) | `aider` |
| [Claude Code](/docs/ai-gateway/coding-agents/claude-code) | `claude-code` |
| [Cline](/docs/ai-gateway/coding-agents/cline) | `cline` |
| [Codex](/docs/ai-gateway/coding-agents/openai-codex) | `codex` |
| [Continue CLI](/docs/ai-gateway/coding-agents/continue) | `continue` |
| [GitHub Copilot CLI](/docs/ai-gateway/coding-agents/copilot) | `copilot` |
| [Crush](/docs/ai-gateway/coding-agents/crush) | `crush` |
| [Cursor](/docs/ai-gateway/coding-agents/cursor) | `cursor` |
| [Deep Agents CLI](/docs/ai-gateway/coding-agents/deepagents) | `deepagents` |
| [DeepSeek Harness](/docs/ai-gateway/coding-agents/deepseek) | `deepseek` |
| [Factory Droid](/docs/ai-gateway/coding-agents/droid) | `droid` |
| [ForgeCode](/docs/ai-gateway/coding-agents/forge) | `forge` |
| [fx](/docs/ai-gateway/coding-agents/fx) | `fx` |
| [Goose](/docs/ai-gateway/coding-agents/goose) | `goose` |
| [gptme](/docs/ai-gateway/coding-agents/gptme) | `gptme` |
| [Grok Build](/docs/ai-gateway/coding-agents/grok-build) | `grok` |
| [Hermes](/docs/ai-gateway/coding-agents/hermes) | `hermes` |
| [Junie CLI](/docs/ai-gateway/coding-agents/junie) | `junie` |
| [Kilo Code](/docs/ai-gateway/coding-agents/kilo-code) | `kilo` |
| [Kimi CLI](/docs/ai-gateway/coding-agents/kimi) | `kimi` |
| [omp](/docs/ai-gateway/coding-agents/omp) | `omp` |
| [OpenClaw](/docs/ai-gateway/coding-agents/openclaw) | `openclaw` |
| [OpenCode](/docs/ai-gateway/coding-agents/opencode) | `opencode` |
| [OpenHands](/docs/ai-gateway/coding-agents/openhands) | `openhands` |
| [Pi](/docs/ai-gateway/coding-agents/pi) | `pi` |
| [Qwen Code](/docs/ai-gateway/coding-agents/qwen) | `qwen` |
| [Mistral Vibe](/docs/ai-gateway/coding-agents/vibe) | `vibe` |
| [ZCode](/docs/ai-gateway/coding-agents/zcode) | `zcode` |
| [Zed](/docs/ai-gateway/coding-agents/zed) | `zed` |

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`:

```bash filename="terminal"
vercel ai-gateway setup --agent cursor --agent kilo
```

*Connect specific agents by naming each one with \`--agent\`.*

With `--token-pass`, setup creates a [Token Pass](/docs/ai-gateway/token-pass) key instead and only offers the agents that [`vercel token-pass`](/docs/cli/token-pass) supports: fx, OpenCode, and Pi.

#### Gateway URLs the command writes

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:

| Agent | URL | Why this surface |
| --- | --- | --- |
| Claude Code | `https://ai-gateway.vercel.sh/claude-code` | Anthropic-compatible surface with a Claude Code shaped model catalog, so gateway models appear in the `/model` picker. The Anthropic SDK appends `/v1/messages` itself, so the URL has no `/v1` |
| Codex | `https://ai-gateway.vercel.sh/codex/v1` | OpenAI-compatible surface that also serves `/codex/v1/models` in the `ModelsResponse` shape Codex decodes at startup. Every other path falls through to the standard `/v1` handlers |
| Cursor | `https://ai-gateway.vercel.sh/cursor/v1` | OpenAI-compatible surface that normalizes the non-spec bodies Cursor's base URL override sends to `/chat/completions`, which the standard schema rejects. Every other path falls through to the standard `/v1` handlers |
| Aider, Continue CLI, Copilot CLI, Deep Agents CLI, Factory Droid, gptme, Grok Build, Hermes, Kimi CLI, Kilo Code, OpenClaw, OpenHands, Qwen Code, Mistral Vibe, ZCode, Zed | `https://ai-gateway.vercel.sh/coding-agent/v1` | The [coding agent surface](#the-coding-agent-surface), for agents with no dedicated endpoint of their own |
| ForgeCode, Goose, Junie CLI | `https://ai-gateway.vercel.sh/coding-agent/v1/chat/completions` | These configs require the full Chat Completions endpoint rather than a base URL. ForgeCode also uses `https://ai-gateway.vercel.sh/coding-agent/v1/models` for model discovery |
| Cline, Crush, OpenCode, Pi | None | These agents ship a first-party AI Gateway provider and already know the URL, so only the credential is written |
| DeepSeek Harness | None | The pi-based harness keeps its provider URL and reads the key from `AI_GATEWAY_API_KEY` |
| fx, omp | None | These agents talk to the gateway natively and read the key from `AI_GATEWAY_API_KEY` |

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.

#### The coding agent surface

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

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

Except for model discovery, 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. `/coding-agent/v1/models` omits models that a coding agent can't use for text responses, such as embedding, image, and video models, so they don't appear in agent model pickers. Use this surface 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`.

#### What it configures

| Agent | Files | What's written |
| --- | --- | --- |
| Claude Code | `~/.claude/settings.json` (honors `$CLAUDE_CONFIG_DIR`); shell startup file in Keychain mode | `env.ANTHROPIC_BASE_URL`, `env.ANTHROPIC_API_KEY=""`, and `env.CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1`; the key as `env.ANTHROPIC_AUTH_TOKEN` or a Keychain-resolved shell export |
| Codex | `~/.codex/config.toml` (honors `$CODEX_HOME`) plus shell startup file | `model_provider=vercel` and a `vercel` provider (`base_url`, `wire_api=responses`, `env_key=AI_GATEWAY_API_KEY`); the shell file exports `AI_GATEWAY_API_KEY` |
| OpenCode | `~/.config/opencode/opencode.json` (honors `$XDG_CONFIG_HOME`); shell startup file in Keychain mode | A `vercel` provider entry; the key as `provider.vercel.options.apiKey` or the `AI_GATEWAY_API_KEY` shell export |
| Pi | `~/.pi/agent/auth.json` (mode `0600`, honors `$PI_CODING_AGENT_DIR`) | A `vercel-ai-gateway` API-key entry. Pi always stores the key in this file, even in Keychain mode |
| Cline | `~/.cline/data/settings/providers.json` (mode `0600`) | A `vercel-ai-gateway` provider with your key, set as `lastUsedProvider` and given the default model below |
| Cursor | None | Cursor keeps API-key settings in its account-synced store, so the command exports `AI_GATEWAY_API_KEY` and prints the steps to finish in **Settings** -> **Models**, including the `/cursor/v1` base URL to paste |
| Hermes | `~/.hermes/config.yaml` | A `vercel-ai-gateway` provider (`key_env=AI_GATEWAY_API_KEY`, `discover_models: true`) plus the default model below; the shell file exports the key |
| Kilo Code | `~/.config/kilo/kilo.json` (honors `$XDG_CONFIG_HOME`) | An `openai-compatible` provider whose `apiKey` is the `{env:AI_GATEWAY_API_KEY}` reference Kilo resolves at runtime; the shell file exports the key |
| OpenClaw | `~/.openclaw/openclaw.json` | A `vercel-ai-gateway` provider whose `apiKey` is an `${AI_GATEWAY_API_KEY}` reference, a starter model list, and the default model below; the shell file exports the key |
| Aider | `~/.aider.conf.yml` plus a sibling `.aider.model.metadata.json` | The gateway base URL and an `openai/`-prefixed default model, plus model metadata and settings generated from the gateway catalog so the prefixed IDs resolve with real context windows and diff edits; the shell file exports `AIDER_OPENAI_API_KEY` |
| Continue CLI | `~/.continue/config.yaml` | A gateway provider with a shortlist of the most-used models (see [Model selection](#model-selection)), the key referenced through Continue's secrets syntax, and the onboarding marker so an interactive `cn` doesn't rewrite the config |
| GitHub Copilot CLI | None | Configured entirely through the shell: `COPILOT_PROVIDER_BASE_URL` points at the gateway, `COPILOT_PROVIDER_API_KEY` carries the key, and `COPILOT_MODEL` selects the default gateway model |
| Crush | `~/.config/crush/crush.json` | A `providers.vercel` entry with an `$AI_GATEWAY_API_KEY` reference Crush resolves itself, and the large/small model roles pinned to gateway models |
| Deep Agents CLI | `~/.deepagents/config.toml` | A `vercel-ai-gateway` provider with `api_key_env` naming `AI_GATEWAY_API_KEY`, a `/model` switcher shortlist, and per-model profile tables carrying display names and token limits |
| DeepSeek Harness | `$DSH_HOME/settings.yaml` (default `~/.dsh`) | An `llm-pi-ai` section naming `AI_GATEWAY_API_KEY` as the key env var, plus a model shortlist that leads with the newest DeepSeek models |
| Factory Droid | `~/.factory/settings.json` | BYOK `customModels` entries referencing `AI_GATEWAY_API_KEY` through Droid's env-reference syntax |
| ForgeCode | `~/.forge/.forge.toml` plus a sibling `.credentials.json` (mode `0600`) | A gateway `[[providers]]` entry and `[session]` defaults; the key goes in `.credentials.json` (the only key source Forge 2.13+ reads), with `api_key_vars` kept for older releases |
| fx | `~/.fx/settings.json`; shell startup file | `credential_source` pinned to the exported `AI_GATEWAY_API_KEY`, ahead of a stored `fx login` session |
| Goose | `~/.config/goose/custom_providers/` plus `config.yaml` | A declarative provider JSON that shadows Goose's built-in `vercel_ai_gateway` definition and resolves the key from `AI_GATEWAY_API_KEY`, and the default provider and model in `config.yaml` |
| gptme | `~/.config/gptme/config.toml` | A `vercel-ai-gateway` entry in the `[[providers]]` array with `api_key_env` naming `AI_GATEWAY_API_KEY`, and `[models].default` pointed at the gateway default model |
| Grok Build | `~/.grok/config.toml` (honors `$GROK_HOME`) | `endpoints.models_base_url` pointed at the gateway and a default model entry whose `env_key` references `AI_GATEWAY_API_KEY` |
| Junie CLI | `$JUNIE_HOME/models/` (default `~/.junie`) | A stable `vercel-ai-gateway` profile pinned to the top model, plus one profile per shortlisted gateway model, each with an env reference to `AI_GATEWAY_API_KEY` |
| Kimi CLI | `$KIMI_SHARE_DIR/config.toml` (default `~/.kimi`, mode `0600`) | A gateway provider and a `[models]` shortlist; Kimi requires a literal `api_key`, so the key lands in this file |
| omp | None | omp reads `AI_GATEWAY_API_KEY` natively and fills `/model` from the gateway catalog, so only the shell export is written, never omp's SQLite store |
| OpenHands | `~/.openhands/agent_settings.json` | A minimal `llm` block pointing at the gateway with an `openai/`-prefixed model ID; an existing condenser LLM is repointed the same way, and the pinned model's per-token cost fields come from the gateway catalog |
| Qwen Code | `~/.qwen/settings.json` | `modelProviders.openai` entries, each with an `envKey` reference to `AI_GATEWAY_API_KEY` so the key never lands in the file |
| Mistral Vibe | `$VIBE_HOME/config.toml` (default `~/.vibe`) | The gateway provider and an unaliased `[[models]]` shortlist, with `api_key_env_var` keeping the key in the shell environment and `active_model` pinned to the leading Mistral model |
| ZCode | `~/.zcode/v2/config.json` (mode `0600`) | A gateway provider entry with the base URL and a model shortlist. ZCode has no env-var lookup for custom providers, so the key is stored in this file |
| Zed | Zed's JSONC `settings.json` (honors `$XDG_CONFIG_HOME` on Linux and `$APPDATA` on Windows); shell startup file | Zed's first-party `vercel_ai_gateway` provider (comment-preserving merge) pointed at the coding-agent endpoint, the Agent Panel default model, and a `VERCEL_AI_GATEWAY_API_KEY` shell export |

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 selection

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. A harness with a preferred model family starts on the leading model from that family instead, and Grok Build always starts on a Grok model. Change it at any time:

| Agent | How to switch models |
| --- | --- |
| Cline | In-session, or `cline auth -p vercel-ai-gateway -m <gateway-model-id>` |
| Hermes | `/model custom:vercel-ai-gateway:<gateway-model-id>` |
| OpenClaw | Add the model to the provider's `models` array in `openclaw.json`, then select it |
| Aider | `/model openai/<gateway-model-id>`, or edit `~/.aider.conf.yml` |
| Continue CLI | Pick from the provider's models in-session, or edit `~/.continue/config.yaml` |
| GitHub Copilot CLI | Set `COPILOT_MODEL`, or pass `--model` |
| Crush | In-session with `ctrl+p` |
| Deep Agents CLI | `/model` switcher |
| ForgeCode | In-session with `:config-model` (the picker fills from the gateway catalog) |
| Goose | Set `GOOSE_MODEL` in `config.yaml`, or run `goose configure` |
| gptme | `-m vercel-ai-gateway/<gateway-model-id>` |
| Junie CLI | Run `junie --model custom:vercel-ai-gateway`, or pick the model with `/model` |
| OpenHands | Edit the `llm` block in `agent_settings.json` |
| ZCode | Pick the model in-session |
| Zed | Agent Panel model picker (the model list loads from `/models` once the key is visible) |

#### Desktop session migration

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.

| Agent | What gets copied |
| --- | --- |
| Claude Code | Claude Desktop session records, copied into the gateway (`Claude-3p`) identity with each `model` rewritten to its gateway ID. The command doesn't switch Claude Desktop to AI Gateway, and the gateway identity only exists after Claude Desktop's first gateway launch. [Switch the desktop app manually](/docs/ai-gateway/coding-agents/claude-code#with-the-claude-desktop-app), then re-run setup |
| Codex | Codex Desktop rollout files under `sessions` and `archived_sessions`, copied with a deterministic new session ID and `model_provider` set to `vercel` |

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`.

#### Warnings and consent

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.

> **💡 Note:** ZCode warns you to quit the desktop app before running setup because it
> rewrites its config file on exit and silently discards edits made while it
> runs. Codex used to warn that connecting broke the Codex desktop app. That
> warning is gone now that setup migrates desktop sessions instead.

#### Key storage

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`.

#### Applying the changes

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:

| Mode | Behavior |
| --- | --- |
| `--apply edit` | Write the files. This is the default |
| `--apply prompt` | Emit the agent prompt on stdout instead of writing. Requires the macOS Keychain, so the prompt never contains a plaintext key |

#### Re-running and key rotation

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.

#### Options

| Option | Type | Description |
| --- | --- | --- |
| `--agent <NAME>` | String | Coding agent to configure. Repeatable. See [supported coding agents](#supported-coding-agents) for values. In runs without prompts, also grants consent for that agent's warnings |
| `--all` | Boolean | Configure every [supported coding agent](#supported-coding-agents), whether or not it's detected on this machine |
| `--key <KEY>` | String | Use an existing AI Gateway API key instead of creating one. Skips key creation and the name, team, budget, and expiry prompts |
| `--token-pass` | Boolean | Create a [Token Pass](/docs/ai-gateway/token-pass) key, which spends only your team's Token Pass credit. Limits setup to fx, OpenCode, and Pi. See [`vercel token-pass`](/docs/cli/token-pass) |
| `--name <NAME>` | String | Name for a newly created API key |
| `--amount <USD>` | Number | Spend limit for a new key, in US dollars (minimum 1) |
| `--refresh-period <PERIOD>` | String | Quota reset cadence for a new key: `daily`, `weekly`, `monthly`, or `none` |
| `--include-byok` | Boolean | Include [BYOK](/docs/ai-gateway/authentication-and-byok/byok) usage in a new key's quota |
| `--expiration <PERIOD>` | String | Expiry for a new key: `7d`, `30d`, `60d`, `90d`, `1y`, or `none` (default `none`) |
| `--reconfigure` | Boolean | Run setup again when agents are already configured, for example to rotate the key or switch teams |
| `--agent-config <AGENT=PATH>` | String | Override an agent's config file path, for example `claude-code=/path/settings.json`. Repeatable |
| `--shell-rc <PATH>` | String | Shell startup file that receives the managed export block |
| `--base-url <URL>` | String | Override the AI Gateway base URL written into agent configs, for example a preview deployment. ForgeCode, Goose, and Junie CLI append `/chat/completions` |
| `--apply <MODE>` | String | How to apply the changes: `edit` (default) or `prompt` |
| `--dry-run` | Boolean | Show what would change without writing files or creating a key |
| `--no-backup` | Boolean | Do not write `.bak` backups of changed files |
| `--no-session-migration` | Boolean | Do not copy existing Claude Desktop or Codex Desktop sessions |
| `--no-keychain` | Boolean | Write the key into the agent config files and shell startup file instead of the macOS Keychain |
| `--yes`, `-y` | Boolean | Run without prompts |
| `--scope <SLUG>` | String | Team that owns a newly created key. A global option, also available as `-S` |

#### Defaults with `--yes`

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:

| Prompt | Default |
| --- | --- |
| Agents | The agents detected on your machine. If none are detected, the command errors and asks you to pass `--agent` or `--all`. The command skips agents with warnings unless you name them |
| API key | Creates a new key unless you pass `--key`, or the configs already point at the gateway and the stored key can be recovered |
| Key name | Omitted, so the server assigns a name. Interactively, the prompt suggests `[<user>'s <device>] Coding Agents` |
| Team or scope | Uses `--scope`, or your currently selected team. Without one, the command errors with `missing_scope`. Not needed with `--key` |
| Spend limit | Unlimited, unless you pass `--amount` |
| Refresh | One-time limit with no reset, unless you pass `--refresh-period` |
| Expiration | Never (`--expiration none`) |
| Key storage | Your macOS Keychain when available, otherwise the agent config files. Pass `--no-keychain` to always use config |
| Session migration | Eligible desktop sessions are copied. Pass `--no-session-migration` to skip |
| Apply mode | `edit`, so the files are written. Pass `--apply prompt` for the prompt instead |
| Backups | Enabled. The command writes `.bak` files unless you pass `--no-backup` |

#### Non-interactive output

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.

| `reason` | Meaning |
| --- | --- |
| `coding_agents_configured` | Files were written |
| `already_configured` | Nothing to do; no key was created |
| `sessions_migrated` | Only desktop sessions were copied |
| `agent_prompt` | `--apply prompt` returned a prompt instead of writing |
| `dry_run` | Preview only |
| `requires_consent` | Every selected agent needs an explicit `--agent` |
| `session_migration_failed` | A session copy failed, so no configuration was changed |
| `unparseable_config` | No agent config could be written |
| `keychain_error` | The key couldn't be stored in the macOS Keychain |
| `missing_scope` | No team was selected for a new key |

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.

#### Notes

- 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 doesn't configure the Claude Desktop app, which keeps its provider in its own settings. [Switch it manually](/docs/ai-gateway/coding-agents/claude-code#with-the-claude-desktop-app). Codex Desktop needs no extra step because it reads the same `~/.codex/config.toml` as the Codex CLI.
- The command follows the [CLI exit-code contract](/docs/cli/global-options#exit-codes): `0` for success, a no-op, or help; `1` for an operational failure; and `2` for a usage error. One exception: in human-readable output, an invalid option value, such as an unsupported `--apply` mode, exits `1`.

> **⚠️ Warning:** Your API key is sensitive. Human-readable output only shows it masked (for
> example `vck_••••1234`), but the JSON payload includes it in full, and the
> agent config files or shell startup file hold it whenever the macOS Keychain
> isn't used. Keep all of these secret.

### virtual-models

Manage [virtual models](/docs/ai-gateway/models-and-providers/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](/docs/ai-gateway/models-and-providers/virtual-models) for concepts and request behavior.

```bash filename="terminal"
vercel ai-gateway virtual-models [subcommand]
```

Every subcommand accepts `--json` for machine-readable output.

#### create

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

```bash filename="terminal"
vercel ai-gateway virtual-models create
```

*Create a virtual model interactively.*

```bash filename="terminal"
vercel ai-gateway virtual-models create my-model --model openai/gpt-5.1
```

*Create a virtual model in a single command.*

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

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

*Set provider options alongside the common flags.*

##### Options

| Option | Type | Description |
| --- | --- | --- |
| `--kind <KIND>` | String | Virtual model kind: `alias` or `relay` (default: `alias`). A relay also needs a `baseUrl` in `--config`, and the team has to be allowlisted for it |
| `--model <SLUG>` | String | Model the virtual model points at. Required unless you set `modelSlug` in `--config` or answer the prompt |
| `--display-name <NAME>` | String | Human-readable name shown in the dashboard |
| `--description <TEXT>` | String | Description of the virtual model |
| `--provider-order <LIST>` | String | Comma-separated providers to try, in order |
| `--provider-only <LIST>` | String | Comma-separated providers to restrict routing to |
| `--config <JSON>` | String | JSON object of any other virtual model fields |

#### list

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

```bash filename="terminal"
vercel ai-gateway virtual-models list
```

#### inspect

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

```bash filename="terminal"
vercel ai-gateway virtual-models inspect my-model
```

#### update

Update 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.

```bash filename="terminal"
vercel ai-gateway virtual-models update my-model --model anthropic/claude-sonnet-4.5
```

*Point an existing virtual model at a different model.*

#### delete

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

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

```bash filename="terminal"
vercel ai-gateway virtual-models delete my-model
```

#### restore

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

```bash filename="terminal"
vercel ai-gateway virtual-models restore my-model
```

### private-inference

Manage [private inference](/docs/ai-gateway/security-and-compliance/private-inference) for the current team. A private provider is an inference endpoint of your own that you connect to AI Gateway, and a private model is a model that provider serves. Requests call a private model as `private/<slug>`.

```bash filename="terminal"
vercel ai-gateway private-inference [subcommand]
```

Run it without a subcommand to show each private provider with its private models nested under it, like the dashboard's **Private Inference** page:

```bash filename="terminal"
vercel ai-gateway private-inference
```

With `--json`, the output is `{ "privateProviders": [...] }`. Each provider includes its `privateModels`, and each model includes its `gatewayModelId`. A model whose provider isn't listed appears under `privateModelsWithoutProvider`. Every `private-inference` subcommand accepts `--json`.

#### providers list

List the team's private providers, sorted by slug, with each provider's slug, name, connection type, base URL, and status. Alias: `ls`. Running `vercel ai-gateway private-inference providers` on its own runs the same list. A team can have up to 25 private providers.

```bash filename="terminal"
vercel ai-gateway private-inference providers list
```

With `--json`, the output is `{ "privateProviders": [...] }`.

#### providers inspect

Show one private provider and the private models that use it. The output shows only the last four characters of the provider's API key.

```bash filename="terminal"
vercel ai-gateway private-inference providers inspect acme-vllm
```

#### providers discover

List the models a private provider's endpoint serves, and mark the ones you've already added as private models. The command asks the endpoint for up to 1,000 models with the provider's stored API key, changes nothing, and suggests the command that adds the rest. It needs permission to update private providers, which the Developer role doesn't have.

```bash filename="terminal"
vercel ai-gateway private-inference providers discover acme-vllm --query llama
```

*Find the Llama models a private provider serves.*

| Option | Type | Description |
| --- | --- | --- |
| `--query <TEXT>`, `-q` | String | Only show models whose ID or name contains this text. The match ignores case |

#### providers create

Connect an inference endpoint to AI Gateway as a private provider. In a terminal, the command asks for a missing base URL, connection type, or API key, with the key masked, then prints the command to run it again without prompts. Without a terminal, a missing option fails and names the option.

```bash filename="terminal"
vercel ai-gateway private-inference providers create acme-vllm --base-url https://vllm.example.com/v1
```

*Create a provider and enter its API key at a masked prompt.*

`--api-key` takes only `-`, which reads the key from stdin, so the key never appears in your shell history. The CLI never prints the key:

```bash filename="terminal"
cat key.txt | vercel ai-gateway private-inference providers create acme-vllm --base-url https://vllm.example.com --connection-type anthropic --api-key - --json
```

*Create an Anthropic Messages provider in a script, with the API key on stdin.*

The connection types match the [compatible API formats](/docs/ai-gateway/security-and-compliance/private-inference#compatible-api-formats): `openai` is OpenAI Chat Completions, `openai-responses` is OpenAI Responses, `open-responses` is Open Responses, and `anthropic` is Anthropic Messages.

##### Options

| Option | Type | Description |
| --- | --- | --- |
| `--base-url <URL>` | String | Base URL of the provider's API, such as `https://vllm.example.com/v1`. Must use HTTPS on port 443 |
| `--connection-type <TYPE>` | String | API format the endpoint accepts: `openai` (default), `openai-responses`, `open-responses`, or `anthropic` |
| `--api-key -` | String | Read the provider's API key from stdin. Takes only `-`, never the key itself |
| `--name <NAME>` | String | Display name (default: the slug) |
| `--icon-url <URL>` | String | HTTPS URL of an icon for the dashboard |
| `--zdr` | Boolean | Mark the provider as retaining no request data. See [zero data retention](/docs/ai-gateway/security-and-compliance/zdr) |
| `--no-enable` | Boolean | Create the provider turned off, so its models serve no requests |
| `--json` | Boolean | Print `{ "outcome": "created", "privateProvider": { ... } }` |

#### providers update

Change a private provider's settings. Settings you leave out stay as they are. The command takes the same options as [`providers create`](#providers-create), plus `--no-zdr` to mark the provider as one that may retain request data and `--enable` to turn it back on. The receipt shows only the last four characters of a replaced API key, and a key passed as the option's value is refused.

```bash filename="terminal"
cat key.txt | vercel ai-gateway private-inference providers update acme-vllm --api-key -
```

*Replace a provider's API key, reading it from stdin.*

```bash filename="terminal"
vercel ai-gateway private-inference providers update acme-vllm --no-enable
```

*Turn a provider off.*

With `--json`, the output is `{ "outcome": "updated", "privateProvider": { ... } }`.

#### providers delete

Delete a private provider. Aliases: `rm` and `del`. The command shows what it deletes and asks first. Without a terminal, approve the delete with `--confirm-name <slug>`. A provider that private models still use isn't deleted unless you pass `--with-models`, which deletes those models first under the same approval.

```bash filename="terminal"
vercel ai-gateway private-inference providers delete my-vllm --with-models --confirm-name my-vllm
```

| Option | Type | Description |
| --- | --- | --- |
| `--with-models` | Boolean | Delete the private models that use the provider first |
| `--confirm-name <SLUG>` | String | Approve the delete by naming the provider's slug |
| `--yes`, `-y` | Boolean | Deprecated. Use `--confirm-name`. Coding agents can't approve a delete with `--yes` |

#### models list

List the team's private models, sorted by slug, by the model ID requests call them with (`private/<slug>`), with their provider, API model, type, and status. Alias: `ls`. Running `vercel ai-gateway private-inference models` on its own runs the same list. A team can have up to 100 private models.

```bash filename="terminal"
vercel ai-gateway private-inference models list --provider acme-vllm --json
```

*List one provider's models as JSON.*

`--provider <PROVIDER>` shows only the models of one private provider, by slug, and fails when the team has no provider with that slug. With `--json`, the output is `{ "privateModels": [...] }`, and each model includes its `gatewayModelId`.

#### models inspect

Show a private model's model ID, provider, limits, and status. Pass the slug or the model ID `private/<slug>`.

```bash filename="terminal"
vercel ai-gateway private-inference models inspect acme-llama
```

#### models create

Create private models from the models a private provider serves, one or several at a time. Pass `--api-model` more than once to create several. In a terminal, leave out `--provider` or `--api-model` to pick from the models the provider lists, with the ones you already added marked.

```bash filename="terminal"
vercel ai-gateway private-inference models create --provider acme-vllm --api-model acme/llama-70b
```

*Create one private model.*

```bash filename="terminal"
vercel ai-gateway private-inference models create --provider acme-vllm --api-model acme/small --api-model acme/large --json
```

*Create two private models and read the result.*

The slug defaults to one derived from the API model ID. When the CLI can read the provider's model list, it takes slugs, names, and token limits from it. An `--api-model` you already added on the provider is skipped with a warning. The CLI creates models one at a time. If one fails, it lists what it created, what failed, and what it didn't attempt, and exits `1`.

##### Options

| Option | Type | Description |
| --- | --- | --- |
| `--provider <PROVIDER>` | String | Private provider that serves the models |
| `--api-model <MODEL>` | String | Model ID the provider's API expects. Repeatable, to create a private model for each |
| `--type <TYPE>` | String | Model type: `language` (default), `embedding`, or `image`. See [supported model types](/docs/ai-gateway/security-and-compliance/private-inference#supported-model-types) |
| `--name <NAME>` | String | Display name, for one model (default: the API model ID) |
| `--description <TEXT>` | String | Description, for one model |
| `--context-window <NUMBER>` | Number | Context window in tokens, for one model |
| `--max-tokens <NUMBER>` | Number | Maximum output tokens, for one model |
| `--label <LABEL>` | String | Label shown with the models. Repeatable up to 20 times |
| `--no-enable` | Boolean | Create the models turned off |
| `--json` | Boolean | Print the machine-readable result as JSON |

#### models update

Update a private model. Only the options you pass change, and the model keeps its `private/<slug>` ID, even when you move it to another provider.

```bash filename="terminal"
vercel ai-gateway private-inference models update my-llama --provider acme-vllm-2
```

*Serve a private model from another provider.*

```bash filename="terminal"
vercel ai-gateway private-inference models update my-llama --no-enable
```

*Turn a private model off. Requests to it fail until you turn it back on.*

##### Options

| Option | Type | Description |
| --- | --- | --- |
| `--provider <PROVIDER>` | String | Private provider to serve the model |
| `--api-model <MODEL>` | String | Model ID the provider is called with |
| `--name <NAME>` | String | Display name |
| `--type <TYPE>` | String | Model type, such as `language` or `embedding` |
| `--description <TEXT>` | String | Description of the model. An empty value clears it |
| `--context-window <NUMBER>` | Number | Context window in tokens |
| `--max-tokens <NUMBER>` | Number | Maximum output tokens |
| `--label <LABEL>` | String | Label shown with the model. Repeatable up to 20 times. Replaces every label |
| `--no-label` | Boolean | Remove every label |
| `--enable` | Boolean | Turn the model on |
| `--no-enable` | Boolean | Turn the model off |
| `--json` | Boolean | Print the machine-readable result as JSON |

#### models delete

Delete a private model by its slug or model ID. Aliases: `rm` and `del`. The command shows what it deletes and asks first. Without a terminal, approve the delete with `--confirm-name <slug>`.

```bash filename="terminal"
vercel ai-gateway private-inference models delete my-model --confirm-name my-model
```

| Option | Type | Description |
| --- | --- | --- |
| `--confirm-name <SLUG>` | String | Approve the delete by naming the private model's slug |
| `--yes`, `-y` | Boolean | Deprecated. Use `--confirm-name`. Coding agents can't approve a delete with `--yes` |

### models

Browse the [models](/docs/ai-gateway/models-and-providers) available through AI Gateway and compare the providers that serve them. Both commands are read-only. Add `--json` to either command for the full, machine-readable payload.

```bash filename="terminal"
vercel ai-gateway models [subcommand]
```

#### list

List the models available through AI Gateway. The table shows each model's ID, name, owner, and type. Your team's [virtual models](/docs/ai-gateway/models-and-providers/virtual-models) are listed alongside the catalog, and you can narrow the list to one or the other.

```bash filename="terminal"
vercel ai-gateway models list
```

*List every model available through AI Gateway.*

```bash filename="terminal"
vercel ai-gateway models list --query claude
```

*Find models by ID or name.*

```bash filename="terminal"
vercel ai-gateway models list --virtual
```

*List only your team's virtual models.*

##### Options

| Option | Type | Description |
| --- | --- | --- |
| `--query <TEXT>`, `-q` | String | Only list models whose ID or name contains this text. The match ignores case |
| `--virtual`, `--no-virtual` | Boolean | Narrow the list. `--virtual` shows only your team's virtual models, and `--no-virtual` hides them. By default, the list shows catalog models and virtual models |
| `--json` | Boolean | Output the full model payload as JSON |

#### endpoints

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 list` to find model IDs.

```bash filename="terminal"
vercel ai-gateway models endpoints <model-id>
```

```bash filename="terminal"
vercel ai-gateway models endpoints anthropic/claude-opus-5
```

*Compare the providers that serve a model, with pricing, latency, and uptime.*

An unknown model ID fails with a not-found error. When the name matches a model, such as `glm-5.3`, the error suggests the full ID, such as `zai/glm-5.3`.

##### Options

| Option | Type | Description |
| --- | --- | --- |
| `--json` | Boolean | Output the full endpoints payload as JSON, including throughput and tags |

### leaderboard

Explore the [AI Gateway leaderboards](/docs/ai-gateway/leaderboards), the open, anonymized usage data published under CC BY 4.0. Alias: `leaderboards`. Every subcommand is read-only.

```bash filename="terminal"
vercel ai-gateway leaderboard [subcommand]
```

| Subcommand | Description |
| --- | --- |
| `models` | The most-used models |
| `labs` | The most-used model creators |
| `apps` | The top apps built on AI Gateway |
| `providers` | The top inference providers |

```bash filename="terminal"
vercel ai-gateway leaderboard models --modality text
```

*Show the most-used text models.*

```bash filename="terminal"
vercel ai-gateway leaderboard labs --metric spend
```

*Rank model creators by spend instead of request count.*

```bash filename="terminal"
vercel ai-gateway leaderboard models --format csv --output models.csv
```

*Export the full model leaderboard as CSV.*

#### Options

| Option | Type | Description |
| --- | --- | --- |
| `--modality <MODALITY>` | String | Filter by modality: `all`, `text`, `image`, or `video` (default `all`). Applies to `models` and `labs` |
| `--metric <METRIC>` | String | Metric for the table view: `requests`, `tokens`, `spend`, `imageCount`, or `videoCount` (default `requests`). Applies to `models` and `labs` |
| `--date <YYYY-MM-DD>` | String | Day to show in the table view (default: most recent). Applies to `models` and `labs` |
| `--format <FORMAT>` | String | Output format: `table`, `json`, or `csv` (default: `table` in a terminal, `json` otherwise) |
| `--output <PATH>`, `-o` | String | Write the payload to a file instead of stdout. Defaults to JSON; use `--format csv` for CSV |

### requests

List and inspect your team's AI Gateway requests from the terminal. These are the requests the [Logs](/docs/ai-gateway/observability-and-spend/logs) page shows, one row per generation.

```bash filename="terminal"
vercel ai-gateway requests [subcommand]
```

Running `vercel ai-gateway requests` without a subcommand runs `requests list` and takes the same options.

#### list

List requests, newest first. Alias: `ls`. Each row shows the request's time, generation ID, model, provider, HTTP status, tokens, cost, duration, auth method, and spend attribution. In a terminal, the team appears above the table.

```bash filename="terminal"
vercel ai-gateway requests list
```

*List the requests of the last hour.*

```bash filename="terminal"
vercel ai-gateway requests list --since 24h --user me --model openai/gpt-5.6-sol --status 4xx --status 5xx --json
```

*List your own failed requests to one model in the last day as JSON.*

```bash filename="terminal"
vercel ai-gateway requests list --session <session-id> --since 7d --order asc
```

*List a session's requests, oldest first.*

Without `--since`, the list covers the hour before `--until`, which defaults to now. Pass an ISO 8601 time with its zone, such as `2026-11-15T18:00:00Z`, or a relative duration, such as `24h` or `7d`. The range can start at most 32 days ago, and an older `--since` is a usage error. The output shows times in UTC.

Filters run on the server and match exact values. Repeat a repeatable option, or separate its values with commas, to match any of them. Different options must all match. `--session` takes one ID, commas included.

##### Options

| Option | Type | Description |
| --- | --- | --- |
| `--since <TIME>`, `-s` | String | Start of the time range (default: 1 hour before `--until`) |
| `--until <TIME>`, `-u` | String | End of the time range (default: now) |
| `--project <NAME_OR_ID>` | String | Filter by project name or ID |
| `--environment <ENVIRONMENT>` | String | Filter by environment, such as `production`. Repeatable |
| `--model <MODEL>` | String | Filter by model, such as `openai/gpt-5.6-sol`. Repeatable |
| `--provider <PROVIDER>` | String | Filter by provider, such as `anthropic`. Repeatable |
| `--key <KEY_ID>` | String | Filter by API key ID. Repeatable |
| `--status <STATUS>` | String | Filter by HTTP status, such as `429` or `5xx`. Repeatable |
| `--session <SESSION>` | String | Filter by client session ID |
| `--agent <AGENT>` | String | Filter by coding agent, such as `Codex`. Repeatable |
| `--auth-method <METHOD>` | String | Filter by auth method: `api_key`, `oidc`, `app_token`, `personal_access_token`, or `client_secret`. Repeatable |
| `--user <USER>` | String | Filter by user: `me`, a team member's email or username, or a user ID. Repeatable |
| `--order <ORDER>` | String | Sort by time: `asc` or `desc` (default `desc`) |
| `--limit <NUMBER>` | Number | Number of requests to return (default 100, maximum 1000) |
| `--next <CURSOR>` | String | Continue the previous list from its cursor |
| `--json` | Boolean | Print the result as JSON |

`--user` matches the user of a request, meaning the owner of its credential. That's the user behind a personal access token or an app token, or the user an API key's spend is [attributed](/docs/ai-gateway/authentication-and-byok/api-keys#spend-attribution) to. It never matches a request made with a project's OIDC token, a request made with a key whose spend is attributed to the team, or a request that cost nothing, like most failed requests. An email or username matches a team member in any letter case. A user ID doesn't have to belong to a current member, so it also finds a user who left the team.

The spend attribution column shows whose spend a request is: `user` with the username, `team`, `project` with the project's name for a project's OIDC token, or nothing when AI Gateway recorded none.

`--limit` is the total number of rows to return. The CLI fetches them in pages of up to 100, and `--next` continues the same query after the last row. The cursor keeps the filters, sort order, and time range, so you can only pass `--limit` and `--json` with `--next`. With `--json`, the output is `{ "requests": [...], "pagination": { "next": "<cursor>" } }`, and `next` holds the command for the next page.

When request logs are temporarily unavailable, the CLI suggests a shorter time range or a retry after the wait the API gives, which `--json` reports as `retryAfter` in seconds. When a later page fails, the output keeps the rows already fetched, says that it's incomplete, and gives the command that continues after the last row. With `--json`, the error reports `data.rowsFetched` and the cursor to restart from in `data.pagination.next`.

#### inspect

Show one request by its generation ID, as `requests list` shows it. The output includes the model, provider, HTTP status, token counts, cost, and timing, and the project, API key, session, coding agent, and user the request came from.

```bash filename="terminal"
vercel ai-gateway requests inspect gen_01KA0Z5V7M3QK8T2N9X4B6C1DE
```

With `--json`, the output is `{ "request": { ... } }` with the fields the API returns.

### sessions

List and inspect your team's AI Gateway sessions. A session is the requests that share a client session ID, which the caller or a coding agent sends, or which AI Gateway derives from the conversation.

```bash filename="terminal"
vercel ai-gateway sessions [subcommand]
```

Running `vercel ai-gateway sessions` without a subcommand runs `sessions list` and takes the same options.

#### list

List sessions by their last request, newest first. Alias: `ls`. Each row shows the session ID, last request, request and failure counts, tokens, cost, coding agent, last model, auth method, and spend attribution.

```bash filename="terminal"
vercel ai-gateway sessions list
```

*List the sessions of today and yesterday in UTC.*

```bash filename="terminal"
vercel ai-gateway sessions list --since 7d --user me --agent "Claude Code"
```

*List your own sessions with one coding agent in the last 7 days.*

`--since` and `--until` pick whole UTC days, not exact times. The list holds every session with a request in the days the time range touches. Without `--since`, the range starts 24 hours before `--until`, and it can start at most 7 days ago. Totals cover only those days, so a session that began before the first of them shows only its part.

Every filter matches only the session's last request. Filters run on the server and match exact values. Repeat `--key`, `--agent`, `--auth-method`, or `--user`, or separate values with commas, to match any of them. `--user` and spend attribution work as they do for [`requests list`](#requests).

##### Options

| Option | Type | Description |
| --- | --- | --- |
| `--since <TIME>`, `-s` | String | Start of the time range (default: 24 hours before `--until`, at most 7 days ago) |
| `--until <TIME>`, `-u` | String | End of the time range (default: now) |
| `--project <NAME_OR_ID>` | String | Only sessions whose last request was in this project |
| `--key <KEY_ID>` | String | Only sessions whose last request used this API key, by ID. Repeatable |
| `--agent <AGENT>` | String | Only sessions whose last request came from this coding agent, such as `Cursor`. Repeatable |
| `--auth-method <METHOD>` | String | Only sessions whose last request used this auth method: `api_key`, `oidc`, `app_token`, `personal_access_token`, or `client_secret`. Repeatable |
| `--user <USER>` | String | Only sessions whose last request belongs to this user: `me`, a team member's email or username, or a user ID. Repeatable |
| `--limit <NUMBER>` | Number | Number of sessions to return (default 100, maximum 1000) |
| `--next <CURSOR>` | String | Continue the previous list from its cursor |
| `--json` | Boolean | Print the result as JSON |

`--limit` and `--next` work as they do for `requests list`. With `--json`, the output is `{ "sessions": [...], "pagination": { "next": "<cursor>" } }`, where `next` is `null` on the last page.

#### inspect

Show one session: its request and failure counts, first and last request, cost, tokens, cache hit rate, models, providers, and the details of its last request.

```bash filename="terminal"
vercel ai-gateway sessions inspect <session-id>
```

The command looks at the last 7 days, which is as far back as sessions go, or at `--since` and `--until` within them. Like `sessions list`, the range picks whole UTC days, and totals cover only those days. The output ends with the command that lists the session's requests from the first one:

```bash filename="terminal"
vercel ai-gateway requests list --session <session-id> --since <first-request-time> --order asc
```

A session ID that starts with `-` goes after `--`, for example `vercel ai-gateway sessions inspect -- -abc123`. With `--json`, the output is `{ "session": { ... }, "next": [...] }`, with every field and up to 50 models and providers.

## Examples

### Create an API key with a monthly budget

```bash filename="terminal"
vercel ai-gateway api-keys create --name my-key --amount 500 --refresh-period monthly --alert-thresholds 75,100
```

*Create an API key named \`my-key\` with a $500 monthly quota that alerts at 75%
and 100% of the limit.*

### Give every new project a spend limit

```bash filename="terminal"
vercel ai-gateway budgets set project --default --amount 200 --refresh-period monthly
```

*Apply a $200 monthly budget to any project that has no budget of its own.*

### Find the last day's failed requests

```bash filename="terminal"
vercel ai-gateway requests --since 24h --status 4xx --status 5xx
```

*List the team's requests from the last 24 hours that returned a 4xx or 5xx
status.*

### Connect detected coding agents

```bash filename="terminal"
vercel ai-gateway setup --yes
```

*Connect the detected agents with a new, unlimited, non-expiring key.*

### Connect specific agents with a budgeted key

```bash filename="terminal"
vercel ai-gateway setup \
  --agent claude-code --agent codex \
  --name "My Coding Key" \
  --scope my-team \
  --amount 500 --refresh-period monthly \
  --expiration 30d \
  --yes
```

*Connect Claude Code and Codex with a $500 monthly key that expires in 30
days.*

### Connect every supported agent

```bash filename="terminal"
vercel ai-gateway setup --all --yes
```

*Configure every supported agent, including the ones not installed on this
machine yet.*

### Hand the edits to a coding agent instead of writing them

```bash filename="terminal"
vercel ai-gateway setup --apply prompt --yes
```

*Create the key, store it in the macOS Keychain, and emit a prompt that
describes the edits.*

### Reuse an existing key and preview changes

```bash filename="terminal"
vercel ai-gateway setup --key vck_... --dry-run
```

*Reuse an existing key and preview the changes without writing any files.*

### Reconfigure an already-connected machine

```bash filename="terminal"
vercel ai-gateway setup --reconfigure --yes
```

*Run setup again on an already-configured machine, for example to rotate the
key or switch teams.*

### Point an agent at a different gateway base URL

```bash filename="terminal"
vercel ai-gateway setup --agent codex --base-url https://preview.ai-gateway.vercel.sh/coding-agent/v1
```

*Write a preview deployment's URL instead of the default surface.*

## Related

- [AI Gateway overview](/docs/ai-gateway)
- [Coding agents](/docs/ai-gateway/coding-agents)
- [AI Gateway models and providers](/docs/ai-gateway/models-and-providers)
- [AI Gateway routing rules](/docs/ai-gateway/models-and-providers/routing-rules)
- [AI Gateway authentication](/docs/ai-gateway/authentication-and-byok)
- [AI Gateway API keys](/docs/ai-gateway/authentication-and-byok/api-keys)
- [AI Gateway budgets](/docs/ai-gateway/observability-and-spend/budgets)
- [AI Gateway request logs](/docs/ai-gateway/observability-and-spend/logs)
- [`vercel token-pass`](/docs/cli/token-pass)

## Global Options

The following [global options](/docs/cli/global-options) can be passed when using the `vercel ai-gateway` command:

- [`--cwd`](/docs/cli/global-options#current-working-directory)
- [`--debug`](/docs/cli/global-options#debug)
- [`--global-config`](/docs/cli/global-options#global-config)
- [`--help`](/docs/cli/global-options#help)
- [`--local-config`](/docs/cli/global-options#local-config)
- [`--no-color`](/docs/cli/global-options#no-color)
- [`--non-interactive`](/docs/cli/global-options#non-interactive)
- [`--scope`](/docs/cli/global-options#scope)
- [`--token`](/docs/cli/global-options#token)
- [`--version`](/docs/cli/global-options#version)

For more information on global options and their usage, refer to the [options section](/docs/cli/global-options).

## Search the docs from your terminal

Search the Vercel docs and read pages as Markdown with the Vercel CLI. No login required.

```bash
# Find docs pages by keyword
npx vercel@latest docs search "environment variables"
npx vercel@latest docs search "function timeout"

# Print a docs page as Markdown, by path or URL
npx vercel@latest docs inspect <page>
```

---

[View full sitemap](/docs/sitemap)


If you encounter incorrect information, can’t find what you need, need a capability Vercel doesn’t currently offer, or have any other feedback to report, please do it by following the instructions at https://vercel.com/feedback.md.
