10. Configuration, Themes, and Terminals

Files and environment variables

Matcha CLI keeps its own files under ~/.matcha and reads product settings from MATCHA_* environment variables. This article is where those files live, which names win, and what is not synced from a server.

Provider API keys (XAI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY) are not Matcha names. They stay Provider-official. Configure them when you set up a Provider (BYOK).

What you need

A matcha binary you can run. You do not have to create any file first: if ~/.matcha/config.toml is missing, built-in defaults apply.

To see every layer Matcha discovered for the current directory:

matcha inspect

Add --json when a script needs the same report.

Home directory

The user home is ~/.matcha unless you override it.

How	Result
Unset	`~/.matcha`
`MATCHA_HOME=/path`	That directory
Only `GROK_HOME=/path`	That directory (legacy, read when `MATCHA_HOME` is unset)

If both MATCHA_HOME and GROK_HOME are set, Matcha uses MATCHA_HOME and reports the conflict by variable name, never by value. matcha doctor and matcha inspect show the same kind of name-only conflict for other registered pairs.

On first use of the default home, Matcha copies missing entries from ~/.grok into ~/.matcha. The old tree is not deleted. Setting MATCHA_HOME (or GROK_HOME) skips that copy: the override path is used as given.

User files

Edit only what you need. Matcha creates the rest as you use sessions, login, skills, and plugins.

Path	Role
`~/.matcha/config.toml`	Main settings (`[ui]`, `[models]`, `[features]`, MCP, skills, and related sections)
`~/.matcha/pager.toml`	Fullscreen layout, padding, animation, alt-screen policy
`~/.matcha/auth.json`	Auth metadata (auto-managed; secrets live in the vault)
`~/.matcha/credentials/secrets.json`	File fallback for Provider secrets when the OS keyring is unavailable (`0600`)
`~/.matcha/sessions/`	Persisted sessions, grouped by working directory
`~/.matcha/memory/`	Cross-session memory (when memory is enabled)
`~/.matcha/skills/`, `plugins/`, `agents/`, `workflows/`	User-scoped extensions
`~/.matcha/logs/`	Internal logs
`~/.matcha/last-copy.txt`	Clipboard backup (override with `MATCHA_COPY_FILE`)

schema_version = 1 is stamped when Matcha writes config.toml. Files without a version still load. Legacy keys such as [auth], theme ids groknight / grokday, and assistant ids grok-build* are mapped on read; new writes use Matcha names (matchanight, matchaday, matcha-build). Unknown keys are preserved.

In-session changes from /settings write user config.toml. Palette choice is [ui] theme in that file, not a theme key in pager.toml. See Themes for the fullscreen palette.

Project files

Place a .matcha/ directory in the repository (or current project root) for project-only MCP servers, plugins, permission rules, skills, hooks, assistants, and LSP.

File	What it configures
`.matcha/config.toml`	`[mcp_servers]`, `[plugins]`, `[permission]`, and `[mcp] max_output_bytes` only
`.matcha/skills/`, `hooks/`, `agents/`, `plugins/`	Project-scoped extensions
`.matcha/lsp.json`	Project LSP servers
`.matcha/sandbox.toml`	Custom sandbox profiles
`AGENTS.md`	Project instructions for the assistant

Every other config.toml section loads only from ~/.matcha/config.toml.

Priority for [mcp_servers] and [plugins]: current-dir .matcha/config.toml > <repo-root>/.matcha/config.toml > ~/.matcha/config.toml. Permission rules merge across those files (deny > ask > allow).

If .matcha/ is absent, Matcha still discovers a leftover .grok/ project tree. It does not delete it.

Precedence

Highest wins:

CLI flags (for example --model, --sandbox, --yolo)
Environment variables (MATCHA_*, plus Provider-official keys)
~/.matcha/config.toml
Built-in defaults

If a leftover managed_config.toml or requirements.toml is already on disk, matcha inspect still lists layers it finds. Do not treat those files as something Matcha downloads or refreshes for you.

Self-update, product telemetry, a marketplace, and account OAuth are also unavailable. Setting [cli] auto_update, [features] telemetry, or OIDC environment variables does not turn those services on.

Environment variables

Product names use the MATCHA_ prefix. Registered GROK_* aliases are read-only compatibility: they apply only when the Matcha name is unset. If both are set, Matcha wins and a diagnostic names the two variables.

Common product variables:

Variable	Role
`MATCHA_HOME`	Config directory (default `~/.matcha`)
`MATCHA_THEME`	Registered theme override. Prefer `/theme` or `[ui] theme` if you need a change you can see immediately — see Themes.
`MATCHA_APPEARANCE`	Registered `dark` / `light` hint for `theme = "auto"`
`MATCHA_MEMORY`	`1` / `0` — cross-session memory
`MATCHA_SUBAGENTS`	`1` / `0` — sub-assistants
`MATCHA_WORKFLOWS`	`1` / `0` — background workflows (default on)
`MATCHA_SANDBOX`	Sandbox profile
`MATCHA_LOG_FILE`	Log file path (used verbatim)
`MATCHA_RESPECT_GITIGNORE`	`1` / `0` — overrides `[tools] respect_gitignore`
`MATCHA_COPY_FILE`	Clipboard backup path
`MATCHA_CLIPBOARD_NO_OSC52`	`1` — disable the OSC 52 copy route
`MATCHA_MODELS_BASE_URL`	Custom OpenAI-compatible models/inference base URL
`RUST_LOG`	Log level filter (not a Matcha name)

Check your work

Run matcha inspect in a project that has .matcha/config.toml and one that does not. Confirm project MCP and plugin layers appear only in the first.
Set MATCHA_HOME to an empty directory and launch Matcha. Confirm new files land there, not in ~/.matcha.
If you still have GROK_* from Grok Build, unset the Matcha twin and confirm the legacy name still works; set both and confirm matcha doctor names the conflict without printing secrets.