First launch and the welcome screen

• No Provider — a configure state. You cannot send a turn yet.
• Provider configured — the welcome screen with a composer, so you can type a prompt.

Neither screen offers SuperGrok, device-code chrome, a preferred_method picker, or a MatchaCode account.

What startup writes

On startup Matcha CLI writes new files under ~/.matcha (override with MATCHA_HOME). If ~/.grok exists from Grok Build, it copy-migrates recoverable data into ~/.matcha and leaves the old directory in place. Project .grok/ is read and migrated to .matcha/; conflicting files are not silently merged.

How-to pages that ship with the CLI are copied to ~/.matcha/docs/user-guide/ on startup. In the TUI, type /docs or /tutorial (aliases /tour, /onboarding).

The welcome hero uses the product wordmark matcha and the tagline A calmer way to ship code. The shortcuts bar at the bottom shows the keys that apply to the current state.

Launch from the directory you want as the workspace

cd /path/to/your/project
matcha

Or pass a directory:

matcha --cwd ~/projects/my-app

Headless / CI (matcha -p …) and editor ACP (matcha agent) are other entry styles. This article is the interactive TUI.

If no Provider is configured

You should see status copy:

No model Provider is configured

The full sentence used in the TUI is:

No model Provider is configured. Run `matcha login --provider <id>` or add credentials in config.toml.

The primary action is Configure a model Provider, shortcut c. l is still accepted as an alias; Enter activates the selected menu row. There is a Quit row (q).

What this state does not do:

• It does not draw a Type a message... / ❯ composer. You cannot submit a turn here.
• It does not show grok.com, SuperGrok, device code, browser OAuth, or always-approve.
• Pressing c, l, or Enter does not open a login wizard. The action fail-closes and repeats the BYOK sentence above.

Leave the TUI (q on this screen exits immediately) and run:

matcha login --provider xai

Then start matcha again. Repeat with openai, anthropic, or another supported Provider id if that is the key you have. Matcha CLI does not default inference to xAI.

If a Provider is configured

You should land on the welcome screen, not the configure interceptor.

On a typical 102×43 terminal you should see:

• the matcha wordmark
• tagline A calmer way to ship code.
• Quit
• a composer that can submit — focused prompt shows ❯; unfocused copy is Type a message...

The footer may still say Logged in with API key. That is BYOK status, not a MatchaCode account. There is no grok.com, SuperGrok, device-code, preferred_method, or steep an idea chrome.

Type a short request and press Enter. The assistant streams into the scrollback above the prompt (responses, shell commands, file edits). While a turn is running, Enter queues the next message; Esc cancels the turn and keeps your draft.

Paths after a successful start

Override the home with MATCHA_HOME. Do not delete ~/.grok as part of using Matcha CLI; leftover Grok sockets and crash dumps stay there. matcha doctor can list them without modifying them.

Not offered on this screen