> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baseten.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Baseten Switch CLI reference

> Install, connect Claude Code, Codex CLI, and Pi, and control routing, spend, and health with the baseten-switch CLI.

The `baseten-switch` CLI configures [Baseten Switch](/inference/model-apis/coding-agents#baseten-switch), a local gateway that routes Claude Code and Codex CLI to [Model APIs](/inference/model-apis/overview). The same CLI installs Pi's direct Baseten provider without starting the gateway.

The menu bar app and these commands edit the same configuration. For the first-success setup, see [Coding agents](/inference/model-apis/coding-agents#baseten-switch).

Baseten Switch is in beta. Its interfaces, configuration, and behavior can change between releases. It requires macOS 13 or newer on Apple Silicon or Intel.

```sh theme={"system"}
baseten-switch [COMMAND]
```

| Command                                 | Description                                           |
| --------------------------------------- | ----------------------------------------------------- |
| [`setup`](#setup)                       | Create the initial configuration and sign in.         |
| [`up`](#up)                             | Start the gateway and install the menu bar app.       |
| [`on`](#on) / [`off`](#off)             | Toggle Baseten routing for Claude Code and Codex CLI. |
| [`spend`](#spend)                       | Print local spend telemetry.                          |
| [`claude on`](#claude-on)               | Point Claude Code at the gateway.                     |
| [`claude route`](#claude-route)         | Map a Claude model family to a Model APIs slug.       |
| [`claude subagents`](#claude-subagents) | Rewrite Task and sidechain requests.                  |
| [`claude off`](#claude-off)             | Restore prior Claude Code settings.                   |
| [`claude reasoning`](#claude-reasoning) | Set a reasoning policy for Claude Code.               |
| [`codex on`](#codex-on)                 | Create the managed Codex profile.                     |
| [`codex route`](#codex-route)           | Set the Baseten model for the Codex profile.          |
| [`codex off`](#codex-off)               | Remove the managed Codex profile.                     |
| [`codex reasoning`](#codex-reasoning)   | Set a reasoning policy for Codex CLI.                 |
| [`pi install`](#pi-install)             | Write Pi's direct Baseten provider.                   |
| [`pi status`](#pi-status)               | Print the installed Pi provider.                      |
| [`pi uninstall`](#pi-uninstall)         | Remove the managed Pi provider.                       |
| [`status`](#status)                     | Summarize local components, auth, and routing.        |
| [`doctor`](#doctor)                     | Inspect the request path and print the first failure. |
| [`auth login`](#auth-login)             | Re-authenticate through the Baseten CLI.              |
| [`uninstall`](#uninstall)               | Remove Switch, launch agents, and the Mac app.        |

Install with Homebrew:

```sh theme={"system"}
brew trust basetenlabs/baseten
brew install basetenlabs/baseten/baseten-switch
```

The fully qualified formula name adds the tap and installs both Baseten Switch and its [Baseten CLI](/reference/cli/baseten/auth) dependency. Switch authenticates with the current Baseten CLI profile. Browser OAuth and API-key profiles both work.

Upgrade with `brew upgrade baseten-switch`, then `baseten-switch up`.

***

## `setup`

Verifies the Baseten CLI and its current credential, opens `baseten auth login` when needed, and creates the initial configuration. It never overwrites an existing configuration.

```sh theme={"system"}
baseten-switch setup
```

***

## `up`

Installs the user launch agents, starts the local gateway, and opens the menu bar app.

```sh theme={"system"}
baseten-switch up [--install]
```

##### `--install`

Also installs Baseten Switch.app in `~/Applications`.

After an upgrade, `baseten-switch up` adopts the new CLI and app version.

***

## `on`

Turns Baseten routing on for Claude Code and Codex CLI.

```sh theme={"system"}
baseten-switch on
```

***

## `off`

Turns routing off. Saved model mappings stay editable, and requests fall back automatically when a route fails.

```sh theme={"system"}
baseten-switch off
```

***

## `spend`

Prints local spend telemetry. The menu bar app charts the same data against an estimate of native-provider cost.

```sh theme={"system"}
baseten-switch spend
```

***

## `claude on`

Points new Claude Code sessions at the gateway. Sets `ANTHROPIC_BASE_URL`, `CLAUDE_CODE_ATTRIBUTION_HEADER`, and `ENABLE_TOOL_SEARCH` in `~/.claude/settings.json`, and backs up the prior values first. Omitting the attribution block improves prompt-cache hit rates on the gateway. Restart Claude Code after enabling or disabling.

```sh theme={"system"}
baseten-switch claude on
```

***

## `claude route`

Pins a Claude model family to a Model APIs slug. The gateway hot-reloads configuration, so you don't restart it.

```sh theme={"system"}
baseten-switch claude route [FAMILY] [TARGET]
```

```sh theme={"system"}
baseten-switch claude route sonnet zai-org/GLM-5.2
```

Send a family back to its native provider:

```sh theme={"system"}
baseten-switch claude route sonnet native
```

Remove the pin so the family follows the global switch:

```sh theme={"system"}
baseten-switch claude route sonnet default
```

With no arguments, prints every family's current mapping:

<CodeGroup>
  ```sh Command theme={"system"}
  baseten-switch claude route
  ```

  ```txt Output theme={"system"}
  claude route: client claude-code (global routing Off)
    fable                  zai-org/GLM-5.2-Fast
    opus                   moonshotai/Kimi-K3
    sonnet                 zai-org/GLM-5.2
    haiku                  default (follow switch)
  ```
</CodeGroup>

***

## `claude subagents`

Rewrites Task and sidechain requests to a cheaper model, leaving your main loop untouched.

```sh theme={"system"}
baseten-switch claude subagents [MODEL|inherit|on]
```

```sh theme={"system"}
baseten-switch claude subagents zai-org/GLM-5.2-Fast
```

Leave the requested model alone:

```sh theme={"system"}
baseten-switch claude subagents inherit
```

Re-enable the model you configured earlier:

```sh theme={"system"}
baseten-switch claude subagents on
```

***

## `claude off`

Restores the Claude Code settings that existed before `claude on`.

```sh theme={"system"}
baseten-switch claude off
```

***

## `claude reasoning`

Sets a reasoning policy for Claude Code. The gateway validates each choice against the model catalog.

```sh theme={"system"}
baseten-switch claude reasoning [off|follow-harness|effort <value>|default]
```

```sh theme={"system"}
baseten-switch claude reasoning off
```

***

## `codex on`

Creates the managed `baseten` profile at `~/.codex/baseten.config.toml`. It does not modify `~/.codex/config.toml`. The first run may request permission to enable the parked Codex listener.

```sh theme={"system"}
baseten-switch codex on
```

***

## `codex route`

Sets the Baseten model for the managed profile. The profile stays byte-identical, so active sessions pick up the new target without a Codex restart.

```sh theme={"system"}
baseten-switch codex route [MODEL]
```

```sh theme={"system"}
baseten-switch codex route moonshotai/Kimi-K3
```

Select the upstream model this way rather than with Codex's `-m` flag. That flag overrides the profile's compatibility model and breaks routing.

***

## `codex off`

Removes the managed profile.

```sh theme={"system"}
baseten-switch codex off
```

***

## `codex reasoning`

Sets a reasoning policy for Codex CLI. The gateway validates each choice against the model catalog.

```sh theme={"system"}
baseten-switch codex reasoning [off|follow-harness|effort <value>|default]
```

```sh theme={"system"}
baseten-switch codex reasoning off
```

***

## `pi install`

Writes Pi's direct Baseten provider from the visible Model APIs catalog. Starts no gateway, installs no launch agents, and does not change another harness profile. The installer joins exact model IDs with the public [models.dev](https://models.dev/) catalog for reasoning and text/image input capabilities. Models without an exact match use conservative defaults and are reported during installation. The API key stays in the environment; Pi's configuration stores only a `$BASETEN_API_KEY` reference.

```sh theme={"system"}
baseten-switch pi install
```

***

## `pi status`

Prints the installed direct provider.

```sh theme={"system"}
baseten-switch pi status
```

***

## `pi uninstall`

Removes only the managed Baseten provider.

```sh theme={"system"}
baseten-switch pi uninstall
```

***

## `status`

Summarizes every local component, your authentication, and each harness's routing.

```sh theme={"system"}
baseten-switch status
```

***

## `doctor`

Inspects the same path read-only and prints the first failure with a concrete fix.

```sh theme={"system"}
baseten-switch doctor [--probe]
```

##### `--probe`

Sends a small live request to verify the whole request path.

```sh theme={"system"}
baseten-switch doctor --probe
```

***

## `auth login`

Delegates to the Baseten CLI, reloads the gateway, and prints the current identity.

```sh theme={"system"}
baseten-switch auth login
```

***

## `uninstall`

Removes managed harness settings, processes, launch agents, runtime residue, and the Mac app. Inspect the exact removal first with `--dry-run`. The default retains configuration, telemetry, logs, and backups.

```sh theme={"system"}
baseten-switch uninstall [--dry-run]
```

```sh theme={"system"}
baseten-switch uninstall
brew uninstall baseten-switch
```

##### `--purge`

Also deletes configuration, telemetry, logs, and backups. Pass `--yes` to skip confirmation.

```sh theme={"system"}
baseten-switch uninstall --purge --yes
brew uninstall baseten-switch
```

Uninstall never removes Baseten CLI credentials or keychain entries.

***

## Next steps

<CardGroup cols={2}>
  <Card title="Coding agents" icon="terminal" href="/inference/model-apis/coding-agents">
    Install Switch and connect Claude Code, Codex CLI, or Pi.
  </Card>

  <Card title="Baseten CLI auth" icon="key" href="/reference/cli/baseten/auth">
    Switch uses the current Baseten CLI profile.
  </Card>

  <Card title="Baseten Switch README" icon="github" href="https://github.com/basetenlabs/baseten-switch">
    Upgrade, uninstall, and configuration fields.
  </Card>
</CardGroup>