Configure a Provider (BYOK)

MatchaCode is not a model vendor. Requests go to the Provider you choose: xAI, OpenAI, Anthropic, Ollama, or an OpenAI-compatible endpoint. xAI is a Provider, not the product. Model ids such as grok-4.5 stay that Provider's real ids.

Where the key is stored

matcha login --provider <id> reads a key (secure TTY prompt, stdin pipe, or the Provider's official environment variable), runs local checks, optionally probes the Provider over the network, and stores the secret in the vault:

1. OS keyring when available (macOS Keychain, Windows Credential Manager, Linux Secret Service).
2. File fallback: ~/.matcha/credentials/secrets.json with owner-only mode 0600 on Unix.

~/.matcha/auth.json keeps metadata (which Provider is configured). It is not a plaintext dump of API keys.

Provider ids

--provider also accepts a few hyphenated aliases (x-ai, x.ai, open-ai) that map to the same ids. Unknown ids fail with a list of built-ins.

Credential precedence at inference time, highest first:

1. Per-model api_key or env_key in ~/.matcha/config.toml
2. Vault secret from matcha login
3. The Provider's official environment variable

Provider official variables are not given MATCHA_* aliases. Prefer MATCHA_HOME over a registered GROK_HOME; if both a Matcha name and a registered GROK_* alias are set, Matcha CLI wins and a diagnostic names the variables, not their values.

Interactive prompt

Work from a terminal that can run the matcha binary you built. This is the usual path:

matcha login --provider xai

You should see:

Enter xAI API key (input hidden; Ctrl-C to cancel):

Type the key and press Enter. Echo is disabled on Unix TTYs. On success, stderr reports something like:

Stored xAI API key for Provider `xai` (source: prompt).

If a key for that Provider was already stored: Replaced the previous key for this Provider. Repeat with --provider openai or --provider anthropic to store a different Provider. Keys are isolated; storing OpenAI does not overwrite xAI.

--provider is required unless a Provider is already selected in config, env, or vault. If none is selected:

Specify a Provider with `--provider <id>` (one of: xai, openai, anthropic, openai_compatible, ollama).
Example: matcha login --provider xai

Import from the Provider environment variable

export OPENAI_API_KEY="sk-..."          # example shape only — use your real key
matcha login --provider openai --from-env

--from-env reads the official variable for that Provider and does not print the value. Source is reported as env.

If the variable is unset or empty, the command fails and does not change an existing vault key:

Environment variable `OPENAI_API_KEY` is not set or empty. Existing credentials were not changed.

Pipe on stdin

Use a pipe when stdin is not a terminal:

printf 'KEY' | matcha login --provider anthropic

Do not echo a key into an interactive prompt (history). If stdin is a TTY and you did not pass --from-env, Matcha CLI uses the secure prompt. If stdin is not a TTY and you did not pass --from-env, it reads the first line from the pipe.

Optional network probe

matcha login --provider xai --validate

--validate is off by default so offline setup works. When set, Matcha CLI probes the Provider endpoint (about five seconds) before storing:

• xAI: GET {base}/api-key with Authorization: Bearer
• Anthropic: GET {base}/v1/models with x-api-key
• Other key Providers: GET {base}/models with Bearer

A 200–299 probe prints Online validation succeeded. A 401 / 403 is Provider rejected the API key. Existing credentials were not changed. A network or other HTTP failure is inconclusive and does not overwrite an existing valid key. openai_compatible needs a configured base URL or --validate fails with Online validation requires a Provider base URL.

OpenAI-compatible and Ollama

For an OpenAI-compatible gateway, store the key with the prompt or a pipe, then set the base URL in ~/.matcha/config.toml. Do not invent a Matcha-branded env var for that key.

For Ollama, do not expect matcha login --provider ollama to store a secret. Ollama is local / no-auth. The command fails with:

Provider `Ollama` does not use an API key (local / no-auth). Nothing to store.

Point Matcha CLI at a loopback Ollama daemon in config instead (default base is http://127.0.0.1:11434/v1 when that Provider is selected).

Typed /login in the TUI

/login is hidden from the slash menu. If you type it, it does not open a browser and does not start a wizard. It prints the same BYOK examples:

Account login is unavailable in this Matcha build (Mode A). Configure a Provider API key from a terminal:
  matcha login --provider xai
  matcha login --provider openai --from-env
  printf 'KEY' | matcha login --provider anthropic

Leave the TUI and run one of those commands from a terminal.

Logout

matcha logout

Typed /logout in the TUI asks the runtime to clear stored credentials and returns you to the no-Provider configure state. It does not open a product login screen. Logout does not revoke the key at the Provider; rotate the key on the Provider's console if it may have leaked.

Not available as procedures

These flags exist so leftover scripts get a clear error. Do not set them up:

matcha login --oauth
matcha login --oidc
matcha login --device-auth
matcha login --device-code

Expected stderr:

Account login is unavailable in this Matcha build (Mode A). Configure a Provider API key instead, for example:
  matcha login --provider xai
  matcha login --provider openai --from-env

--oauth and --device-auth conflict with each other. There is no grok.com sign-in, no product OAuth, no device-code polling, no SSO / enterprise OIDC, and no SuperGrok billing.

If something goes wrong