baseten-switch CLI configures Baseten Switch, a local gateway that routes Claude Code and Codex CLI to Model APIs. The same CLI installs Pi’s direct Baseten provider without starting the gateway.
The menu bar app and these commands edit the same configuration. To connect a coding agent, see Coding agents.
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.
Install with Homebrew:
auth api-key.
Upgrade with brew upgrade baseten-switch, then baseten-switch up.
setup
Checks authentication and creates the initial configuration without overwriting an existing file. A saved Switch API key skips the CLI credential check and login. Otherwise, setup verifies the Baseten CLI and its current credential, then opens baseten auth login when needed.
up
Starts the local gateway and installs or refreshes the menu bar app. Healthy components stay running; components running an older version restart with the current binary.
boolean
default:"false"
Installs two launchd user agents that start at sign-in and keep the door and router running. Can’t be combined with
--uninstall.boolean
default:"false"
Unloads and removes the launchd user agents. Can’t be combined with
--install.baseten-switch up adopts the new CLI and app version.
down
Stops the door and router, then quits the menu bar app. Use off instead to disable Baseten routing while keeping the gateway running for native-provider requests.
restart
Stops and starts Switch with the same configuration. If shutdown fails, Switch doesn’t start the components again.
menubar
Installs or refreshes the menu bar app from the current Homebrew package and opens it.
boolean
default:"false"
Prints the CLI binary selected for the menu bar app without installing or opening the app.
on
Turns Baseten routing on for Claude Code and Codex CLI.
off
Turns Baseten routing off. Saved model mappings stay editable. Native model requests use their native provider; requests that explicitly select a Baseten model fail locally while routing is off.
spend
Prints spend estimates calculated from local telemetry. The menu bar app compares these estimates with native-provider costs. Its Traffic totals include cached tokens and report usage coverage; calculated costs are estimates, not a billing statement.
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. The attribution block stays enabled for compatibility with Anthropic’s Auto mode checks. Restart Claude Code after enabling or disabling.
claude route
Pins a Claude model family to a Model APIs slug. The gateway hot-reloads configuration, so you don’t restart it.
claude picker
Manages the Baseten models appended to Claude Code’s /model picker. Claude Code retains its native model choices. On an existing installation, enabling the picker starts with an empty list; add the models you want to expose.
string
Selects an existing routing alias for the model when more than one alias points to the same slug. Use an alias from the preview’s choices. If you omit this option, Switch reuses the model’s only alias or creates one when none exists.
boolean
default:"false"
Previews
picker enable or picker add without applying the change. Both commands require --json for previews. Don’t use this flag with other picker commands: picker sync ignores it and can still rewrite Claude Code settings.boolean
default:"false"
Prints structured output for
picker enable, disable, add, remove, move, and sync. Required with --dry-run for enable and add. picker status always prints JSON; picker list prints plain text and ignores this flag.<alias> and <other-alias> with aliases from picker list. Removing a row keeps its routing alias. These changes don’t alter a running Claude Code session. Reopen /model after a change; restart Claude Code if the picker hasn’t refreshed.
claude subagents
Rewrites Task and sidechain requests to the model you select, leaving your main loop untouched.
claude off
Restores the Claude Code settings that existed before claude on.
claude reasoning
Sets a Claude Code reasoning policy for a specific Baseten model. The gateway validates the choice against the model’s catalog capabilities and the client protocol.
<model> with the routed model’s exact slug. default removes the override. follow-harness uses the harness’s reasoning choice where the adapter supports it, and effort <value> requires a catalog-supported effort. Not every model and protocol supports every mode. The app shows the supported On and Off controls for the selected model.
codex on
Creates the managed baseten profile at ~/.codex/baseten.config.toml and enables the Codex controls in the Switch menu bar app. It doesn’t modify ~/.codex/config.toml. On the first run, Switch may ask you to enable the parked Codex listener.
codex route. Don’t edit the managed profile or its model catalog directly.
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.
<model> with a Model APIs slug.
-m flag. That flag overrides the profile’s compatibility model and breaks routing.
codex off
Removes the managed profile.
codex reasoning
Sets a Codex CLI reasoning policy for a specific Baseten model. The gateway validates the choice against the model’s catalog capabilities and the client protocol. The policy applies only to Codex requests for that model.
<model> with the routed model’s exact slug. default removes the override. The available modes have the same meanings as claude reasoning, but support depends on the Codex protocol adapter and selected model.
config fallback
Controls whether eligible Baseten rate-limit and server errors can fall back to the configured native provider. Inspect the policy or change which responses permit fallback:
on. Fallback requires a valid native target and happens before response bytes reach the client. Turning a policy off returns the Baseten error; a rate-limit response retains its Retry-After header. These controls don’t enable fallback when global routing is off or the request already targets a native provider.
Inspect or set the native model used when a Claude request explicitly selects a Baseten model:
<native-model> with a full Anthropic model ID. Requests that originally selected a native model keep that original model for fallback. Native fallback requires credentials accepted by the native provider.
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 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.
pi status
Prints the installed direct provider.
pi uninstall
Removes only the managed Baseten provider.
status
Summarizes every local component, your authentication, and each harness’s routing.
doctor
Checks authentication, local services, harness configuration, and telemetry. Prints the first failure with a suggested fix. Without --fix, diagnostics don’t change the configuration.
boolean
default:"false"
Sends small live requests to verify the request path. These requests can incur inference charges.
boolean
default:"false"
Prompts before applying supported repairs and checks the result after each repair. Can’t be combined with
--json.boolean
default:"false"
Prints the diagnostic checks as JSON.
boolean
default:"false"
Includes details for passing checks.
boolean
default:"false"
Confirms repair and probe-cost prompts automatically.
number
default:"5"
Sets the timeout in seconds for each probe.
baseten-switch doctor --fix, approve the repair, and restart Claude Code. Attribution is required for Claude Code Auto permission checks.
auth login
Delegates to the Baseten CLI, reloads the gateway, and prints authentication information. Login leaves any saved Switch API key in place; that key continues to take precedence over the CLI credential.
auth api-key
Saves a Switch API key or removes it to restore CLI authentication. A saved key takes precedence over the current Baseten CLI profile and works without a CLI login.
Read the key from a local file through standard input:
/path/to/key-file with a file containing your API key. On macOS, Switch stores the key in Keychain, separately from Baseten CLI credentials. It doesn’t print the key or store it in gateway.yaml. Saving checks the key’s format; Baseten checks its permissions when you use it.
To remove the saved key:
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.
--purge
Also deletes configuration, telemetry, logs, and backups. Pass --yes to skip confirmation.
Next steps
Coding agents
Install Switch and connect Claude Code, Codex CLI, or Pi.
Baseten CLI auth
Switch uses the current Baseten CLI profile.
Baseten Switch README
Upgrade, uninstall, and configuration fields.