00. How to Read This Documentation

Names, paths, and providers

Three naming systems sit in the same binary. Mixing them up is the usual way people look for a MatchaCode account that does not exist, or treat xAI as the product. Keep them apart.

The idea

Kind	What it names	Examples
Product	The CLI you run and the files it writes	MatchaCode (family), Matcha CLI, `matcha`, `~/.matcha`, `MATCHA_*`
Provider	A third-party model API you opted into	`xai`, `openai`, `anthropic`, `openai_compatible`, `ollama`
Compatibility	Old Grok Build names, read-only	`grok` shim, `GROK_*`, `~/.grok`, `.grok/`

xAI is only an optional Provider. Matcha CLI does not sign you into grok.com, and it does not create a MatchaCode account. Provider model ids (for example grok-4.5) stay the Provider’s real ids — this guide does not rename them.

Product names you should use

Family / product name: MatchaCode
CLI display name: Matcha CLI
Command: matcha
User home: ~/.matcha (override with MATCHA_HOME)
Project directory: .matcha/ at the repo root (workflows, local config the project owns)
Environment prefix: MATCHA_* (MATCHA_HOME, MATCHA_MEMORY, MATCHA_AGENT_SECRET, MATCHA_LOG_FILE, …)

New writes go under those names. Prefer them in shell profiles and in notes you paste to teammates.

echo "$MATCHA_HOME"          # empty means the default ~/.matcha
matcha inspect               # layers Matcha CLI discovered for this directory

Credentials live in the Matcha Credential Vault (OS keyring when available, otherwise ~/.matcha/credentials/secrets.json with mode 0600). ~/.matcha/auth.json is metadata (which Provider is configured), not the secret itself.

Provider ids (BYOK)

You bring an API key. First launch does not open a browser.

`--provider` id	Display name	Official key env var
`xai`	xAI	`XAI_API_KEY`
`openai`	OpenAI	`OPENAI_API_KEY`
`anthropic`	Anthropic	`ANTHROPIC_API_KEY`
`openai_compatible` (alias `openai-compatible`)	OpenAI-compatible	the key that endpoint expects
`ollama`	Ollama	none (local; loopback)

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

The key is never accepted as a matcha login argument. --from-env imports the Provider’s official variable. --validate optionally probes the endpoint before storing (needs network).

Do not invent Matcha-shaped names for Provider keys (MATCHA_API_KEY is not a substitute for OPENAI_API_KEY). Official Provider variables stay Provider-real and are not rewritten into a MatchaCode secret.

/model and matcha -m take a Provider model id, not a MatchaCode brand. /docs Custom Models covers Ollama and OpenAI-compatible base URLs.

An old xAI token, if Matcha CLI imports one, is stored only as xAI Provider credentials. It is never turned into a MatchaCode account.

Compatibility names (read-only window)

If you used Grok Build (grok) before:

Old name	What Matcha CLI does
`grok` binary	Same code as `matcha`; deprecation on stderr only (stdout, including `--version` / JSON, stays clean)
`GROK_*`	Read when the matching `MATCHA_*` is unset. If both are set, Matcha CLI wins and a diagnostic names the variables, never the values
`~/.grok`	Discovered and copy-migrated into `~/.matcha`. Never deleted automatically
`.grok/`	Read and migrated to `.matcha/`. Conflicting files are not silently merged
Themes `groknight` / `grokday`	Still load as MatchaNight / MatchaDay
Assistant ids `grok-build*`	Mapped; new writes use `matcha-build` / `matcha-build-plan`

# Prefer:
export MATCHA_HOME="$HOME/.matcha-work"
# Still works if MATCHA_HOME is unset:
export GROK_HOME="$HOME/.matcha-work"

The shim, registered GROK_* names, and read-only ~/.grok discovery remain for at least two Matcha CLI stable releases or 6 months, whichever is longer. After that they may go away; do not start new scripts on grok.

What these names are not

Not a MatchaCode login, OAuth account, SuperGrok, or billing portal.
Not a product cloud or plugin marketplace.
Not permission to rename xAI, Grok, or model ids in API headers and fixtures — those stay real Provider names.

/login in the TUI is hidden from the menu. If you type it, it prints BYOK examples and does not open a browser. /logout clears the local vault only.

Try this

matcha login --provider with the Provider you actually use — not “whatever is default.”
matcha inspect and confirm paths under ~/.matcha (or $MATCHA_HOME).
If ~/.grok exists, confirm it is still there after the first matcha launch (migration copies; it does not delete).
Prefer MATCHA_* in new shell rc files. Leave GROK_* only where a leftover script still needs the alias.