Three ways to run Matcha

This article is the map. Later guides cover credentials, sessions, and permissions in detail.

Three jobs

A quoted sentence after matcha with no -p is still the TUI: Matcha CLI opens the screen and sends that sentence as the first turn. Headless is only the -p / --single family (and --prompt-json / --prompt-file).

Interactive TUI: `matcha`

From a project directory, once matcha is on your PATH:

command -v matcha
matcha --version
matcha

First launch does not open a browser. Store a Provider key once:

matcha login --provider xai
# or: matcha login --provider openai --from-env

Once the TUI is up:

1. Type a request in the prompt and press Enter.
2. Approve (or deny) tool calls when Matcha CLI asks.
3. Type / to open the live command menu, or Ctrl+P for the command palette (see Live catalog vs written tutorial).
4. Quit with /quit (alias /exit).

You can also start the TUI with a first turn already written:

matcha "fix the failing auth test and run it"
matcha --cwd ~/projects/my-app
matcha -c

-c / --continue reopens the most recent session for this directory. --cwd sets the project root before discovery walks up to .git.

--yolo (same as --always-approve, and the same idea as --permission-mode bypassPermissions) skips interactive permission prompts. Deny rules and hooks still apply. Prefer it for trusted automation, not for everyday chatting.

Headless / CI: `matcha -p`

-p is short for --single (alias --print). Matcha CLI runs one prompt with tools, prints the result, and exits. It does not read a piped stdin as the prompt — pass the text in -p, in $(...), or with --prompt-file.

matcha -p "Explain this codebase"
matcha -p "Review changes for bugs" --output-format json --yolo | jq -r '.text'
matcha --prompt-file ./prompt.txt

--output-format values: plain (default), json, streaming-json, streaming-messages-json. Exit 0 on success, 1 on error, 130 on SIGINT, 143 on SIGTERM.

Headless-only flags include --tools, --disallowed-tools, --max-turns, and --agents. If you pass those to the interactive TUI, Matcha CLI warns and ignores them.

To keep context across two scripted calls, capture sessionId from JSON and resume:

id=$(matcha -p "Remember the module we care about is auth" --output-format json | jq -r '.sessionId')
matcha -p "Now list the tests for that module" --resume "$id"

In CI, set the Provider's official key (XAI_API_KEY, OPENAI_API_KEY, or ANTHROPIC_API_KEY) or run matcha login --provider … --from-env on the image. Do not put secrets on the command line.

Editor embed: `matcha agent stdio`

ACP (Agent Client Protocol) is JSON-RPC. The usual local path is stdio: the editor starts Matcha CLI as a child process and talks on stdin / stdout.

matcha agent --always-approve stdio

Flags that apply to every ACP transport go after agent and before the mode name (stdio, serve, leader). Mode-specific flags go after the mode (for example serve --bind).

matcha agent --always-approve --model grok-4.5 stdio
matcha agent --always-approve serve --bind 127.0.0.1:2419

serve is a local WebSocket server (default bind 127.0.0.1:2419). If you omit --secret, Matcha CLI prints a generated token. Prefer MATCHA_AGENT_SECRET over the older GROK_AGENT_SECRET name.

For a one-shot that prints and exits, keep using matcha -p. The stdio path is for a long-lived client.

Same binary, different surfaces

These also work from the same matcha binary and are not a fourth product:

• matcha doctor — terminal / clipboard / color checks without the TUI
• matcha inspect — what Matcha CLI discovered for this directory
• matcha login / matcha logout — Provider keys only
• matcha version — product SemVer (see Supported platforms)

Try this

1. In a small repo: matcha → ask it to list the top-level files → /quit.
2. Same repo: matcha -p "Name the package in this directory" and confirm it printed and exited.
3. If you use an ACP-capable editor, point it at matcha agent stdio (with --always-approve only if you trust that workspace).

Then read Names, paths, and providers so product names, Provider ids, and the old grok names stay distinct.