01. 安装、凭证与第一次跑通

从源码构建

Matcha CLI 是本地运行、自带密钥（BYOK）的工具。没有官方安装器，没有 GitHub Release，也没有 Homebrew、npm、Winget 或 Scoop 包。你从 Matcha CLI 源码检出构建 matcha 二进制，然后运行自己编译出来的那一份。

产品命令是 matcha。产出它的 Cargo 包仍叫 xai-grok-pager-bin。那是内部包名，不是产品名。matcha --version 打印的是 Matcha 产品版本，不是 crate 版本。

构建会产出什么

一次 release 构建会写出三个产物，共用同一份程序，按 argv0 选择行为。把 matcha 放到 PATH 上。不要把 grok 当成产品命令。

二进制作用
matcha放到 PATH 上的 CLI
grok兼容垫片。同一份代码；只在 stderr 打弃用提示
xai-grok-pager内部遗留名。不要当作产品来教或安装

Cargo 默认输出在检出目录下的 target/release/。若设置了 CARGO_TARGET_DIR，同名文件会出现在 $CARGO_TARGET_DIR/release/。

安装工具链

在 Matcha CLI 检出的仓库根目录操作。

  1. Rust：rust-toolchain.toml 钉死 1.94.0。第一次调用 cargo 时，rustup 会装上该工具链。
  2. DotSlash：必需，以便 bin/ 下的隔离工具（尤其是 bin/protoc）能下载并运行。构建前把 dotslash 放到 PATH。
  3. protoc：proto 代码生成经 DotSlash 解析 bin/protoc，否则回退到 PATH / $PROTOC 上的 protoc。
cargo install dotslash
# or: prebuilt packages — https://dotslash-cli.com/docs/installation/
/usr/bin/env dotslash --help   # sanity check

构建二进制

始终只针对该 crate。全工作区构建又慢也不需要：

cargo build -p xai-grok-pager-bin --release

常用变体：

cargo check -p xai-grok-pager-bin            # fast compile check
cargo run -p xai-grok-pager-bin              # debug build + launch the TUI

在 macOS Apple Silicon 上，可重复的本地出证（隔离在 /tmp；不会发布安装器）是：

python3 scripts/rebrand/macos_local_attestation.py

确认调用的是这次构建

若 PATH 上已有另一个 matcha，不要覆盖它。先用路径调用这次构建的二进制，直到确认没有冲突：

command -v matcha
./target/release/matcha --version
# if CARGO_TARGET_DIR is set:
# "$CARGO_TARGET_DIR/release/matcha" --version

--version、-v 和 -V 是等价的早期标志。子命令形式打印同一份内容：

./target/release/matcha version
./target/release/matcha v
./target/release/matcha version --json

普通输出是一行：matcha <product-version-with-commit>，若配置了通道还会带通道标签。--json 只打印 currentVersion 和 channel（不含密钥）。调用 grok 垫片会在 stderr 打弃用提示，stdout 保持干净，以便 JSON 和 --version 仍可解析。

可选：shell 补全

matcha completions 把补全脚本写到 stdout。无副作用（不联网、不鉴权）。生成的脚本始终以 matcha 命名，即使你调用的是 grok 垫片。它从不覆盖遗留的 grok 补全文件。

# bash
./target/release/matcha completions bash > ~/.local/share/bash-completion/completions/matcha

# zsh — put the file on your fpath, then compinit
./target/release/matcha completions zsh > "${fpath[1]}/_matcha"

# fish
./target/release/matcha completions fish > ~/.config/fish/completions/matcha.fish

# powershell / elvish are also accepted by clap
./target/release/matcha completions powershell
./target/release/matcha completions elvish

重新加载 shell（或 source 该文件）之后，才期望 matcha <Tab> 能用。

把 matcha 放到 PATH

仅在冲突检查之后：把二进制复制或符号链接到已在 PATH 上的目录，或把 release 目录前置到 PATH：

export PATH="/absolute/path/to/this/build/release:$PATH"
hash -r   # bash/zsh: drop a stale hashed matcha
command -v matcha
matcha --version

不可用

不要把这些当成安装流程：

  • GitHub Releases、curl 或 PowerShell 安装器、npm、Homebrew、Winget 或 Scoop — 均未发布。
  • matcha update（--check、--force-reinstall、--version、--alpha / --stable）— 没有自动更新通道。从源码重新构建。
  • matcha setup — 没有可拉取的远程配置。