Switch models

How the catalog is assembled

Matcha CLI talks to one current Provider at a time. The five built-in Provider ids are:

The catalog for the current Provider is assembled from custom [model.*] rows in ~/.matcha/config.toml, the Provider's remote model list when that request succeeds, and an origin-and-auth-matched on-disk cache when the remote list fails. Rows loaded from cache are marked (cached) in matcha models and in the picker. A corrupt cache is ignored; Matcha CLI does not retry a second fetch from it.

After the catalog is assembled for the current Provider, the default pick order is:

1. CLI -m / --model
2. MATCHA_DEFAULT_MODEL (the older GROK_DEFAULT_MODEL name is read only when the Matcha name is unset)
3. [models].default in ~/.matcha/config.toml
4. First selectable catalog entry

Configure a Provider first

Store a key (or point at a local daemon) before you expect a catalog. Do not put secrets on the matcha command line.

matcha login --provider xai
matcha login --provider openai --from-env
printf 'KEY' | matcha login --provider anthropic
matcha login --provider openai_compatible
matcha login --provider ollama

See Install, Credentials, and First Success for BYOK details. This article assumes a Provider is already selected.

List what the current Provider exposes

matcha models

The command prints an auth banner, the selected Provider as Display (id), the default model id, an optional Catalog source line, then each row as id — Name (Provider) with (cached) when the row came from disk. The current default is marked * … (default).

With no Provider selected the list is empty and the command points at matcha login --provider <id> or [model_providers].

Switch in the session

Slash command

Type / and run /model (alias /m). The name is required:

/model grok-4.5
/model Grok 4.5
/m gpt-4o

Matcha CLI resolves a model id or display name, case-insensitively. Display names may contain spaces (Grok 4.5); the command prefers a full-string catalog match so a shorter name cannot steal the prefix.

Bare /model <name> switches this session and writes [models].default for later sessions. A toast confirms Default model: <display name>. Typing /model with no name prints Usage: /model <name> [effort] — it does not open the picker.

For a reasoning model you can add an effort level as a second argument. That form is session-scoped (it does not go through the default-model writer). See Reasoning effort.

/model Reasoning X high

Autocomplete: after /model, the menu lists Name (Provider) and tags (cached) / (current). Reasoning models insert a trailing space so a second menu can offer that model's effort levels.

Picker from scrollback

Press Ctrl+M from the scrollback pane (not the prompt). The picker lists the same catalog as /model, including custom [model.*] rows. Insert text stays the model name, so /model grok-4.5 still works after you leave the picker.

Pin a default in config

[models]
default = "grok-4.5"

Use an id the current Provider actually serves. A missing [models].default / -m / MATCHA_DEFAULT_MODEL value produces the missing-id hint above.

Headless and one-shot

matcha -p "Hello" -m grok-4.5
matcha --model gpt-4o
matcha agent -m claude-opus-4-6

-m / --model wins over env and [models].default for that process.

Confirm the session

/session-info (aliases /status, /info) shows the auth method, the active model, turn count, and context usage.

What Matcha CLI does not do

• There is no MatchaCode-owned default catalog independent of Providers.
• There is no Matcha-hosted model marketplace, account-tier catalog, or remote campaign that silently replaces your default.
• Model ids are never renamed for branding.
• Image generation, video generation, and product web search are unavailable. [models] web_search and MATCHA_WEB_SEARCH_MODEL do not enable a MatchaCode search service.