00. 怎么读这份文档

三种运行方式

Matcha CLI 是一份二进制，三种进入方式。同一个 matcha 可以占满终端、打印一次性答案然后退出，或待在编辑器后面。你选的入口改变的是怎么跟它说话，不是产品本身。

本文是地图。后面的指南会详细讲凭证、会话和权限。

三种用途

用途入口你会看到
待在项目里对话matcha全屏 TUI（或精简；见全屏与精简）
脚本或 CI：一次提示，然后退出matcha -pstdout 上的文本（或 JSON）
通过 ACP 嵌入编辑器matcha agent stdiostdin / stdout 上的 JSON-RPC

matcha 后面跟一句引号里的话、但没有 -p，仍然是 TUI：Matcha CLI 打开屏幕，并把那句话作为第一轮发出。无界面只属于 -p / --single 这一族（以及 --prompt-json / --prompt-file）。

交互式 TUI：`matcha`

在项目目录里，当 matcha 已在 PATH 上时：

command -v matcha
matcha --version
matcha

首次启动不会打开浏览器。把服务商密钥存一次：

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

TUI 起来之后：

  1. 在提示符里输入请求，按 Enter。
  2. Matcha CLI 询问时，批准（或拒绝）工具调用。
  3. 输入 / 打开现场命令菜单，或用 Ctrl+P 打开命令面板（见现场目录与书面教程）。
  4. 用 /quit 退出（别名 /exit）。

也可以带着已经写好的第一轮启动 TUI：

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

-c / --continue 重新打开此目录最近一次会话。--cwd 在向上发现 .git 之前设定项目根。

--yolo（等同 --always-approve，思路也等同 --permission-mode bypassPermissions）会跳过交互式权限提示。拒绝规则和 hooks 仍然生效。适合受信任的自动化，不适合日常对话。

无界面 / CI：`matcha -p`

-p 是 --single 的缩写（别名 --print）。Matcha CLI 带着工具跑一次提示，打印结果，然后退出。它不会把管道进来的 stdin 当成提示 — 请把文本放进 -p、$(...)，或用 --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 取值：plain（默认）、json、streaming-json、streaming-messages-json。成功退出 0，出错 1，SIGINT 为 130，SIGTERM 为 143。

仅无界面的参数包括 --tools、--disallowed-tools、--max-turns 和 --agents。如果把它们传给交互式 TUI，Matcha CLI 会警告并忽略。

要在两次脚本调用之间保留上下文，从 JSON 里取出 sessionId 再继续：

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"

在 CI 里，设置服务商官方密钥（XAI_API_KEY、OPENAI_API_KEY 或 ANTHROPIC_API_KEY），或在镜像上运行 matcha login --provider … --from-env。不要把密钥写在命令行上。

嵌入编辑器：`matcha agent stdio`

ACP（Agent Client Protocol）是 JSON-RPC。本地常见路径是 stdio：编辑器把 Matcha CLI 作为子进程启动，在 stdin / stdout 上通信。

matcha agent --always-approve stdio

适用于所有 ACP 传输方式的参数写在 agent 之后、模式名（stdio、serve、leader）之前。某一模式专用的参数写在模式名之后（例如 serve --bind）。

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

serve 是本地 WebSocket 服务器（默认绑定 127.0.0.1:2419）。如果省略 --secret，Matcha CLI 会打印生成的 token。优先用 MATCHA_AGENT_SECRET，而不是旧名 GROK_AGENT_SECRET。

一次性打印并退出，请继续用 matcha -p。stdio 路径给长驻客户端用。

同一个二进制，不同入口

这些也来自同一个 matcha 二进制，不是第四个产品：

  • matcha doctor — 不打开 TUI，检查终端 / 剪贴板 / 颜色
  • matcha inspect — Matcha CLI 为此目录发现了什么
  • matcha login / matcha logout — 只处理服务商密钥
  • matcha version — 产品 SemVer（见支持的平台）

试一试

  1. 在一个小仓库里：matcha → 让它列出顶层文件 → /quit。
  2. 同一个仓库：matcha -p "Name the package in this directory"，确认它打印后退出。
  3. 如果使用支持 ACP 的编辑器，把它指向 matcha agent stdio（只有在信任该工作区时才加 --always-approve）。

接着读名称、路径与服务商，好把产品名、服务商 id 和旧的 grok 名称分开。