CLI 参考
查找 zg 的主要命令和内置参考，覆盖检索、索引、配置与 AI Agent 接入。
zg 是人与脚本访问本地检索层的终端入口，AI Agent 使用的也是同一个检索层。先通过命令概览找到入口，需要深入理解检索或索引行为时，再进入对应主题文档。
以已安装版本的帮助信息为准
不同版本的参数可能发生变化。使用 zg --help、zg --help <command> 或 zg --<command> --help 查看当前安装版本支持的完整命令。
命令地图
| 命令 | 用途 | 深入阅读 |
|---|---|---|
zg <query> / zg --rg <pattern> [path...] | 搜索索引或运行内置 ripgrep | 检索指南 |
zg --index / zg --status | 构建、更新或检查工作区索引 | 管理索引 |
zg --install / zg --uninstall | 接入或移除 AI Agent | 接入 AI Agent |
zg --server | 启动、停止或检查本地服务 | 本地 Server |
zg --config / zg --auth | 配置模型、Provider 与远程访问 | Embedding 模型 |
zg --help / zg --version | 查看当前安装版本的命令面 | 使用内置帮助 |
搜索无需子命令，管理操作使用标志：zg --index 才会建立索引，单独的 index、query 和 help 都会被当作搜索文本。
构建大型索引前，还应阅读支持的内容，了解内容提取与文件类型边界。
常用起点
# 使用默认混合检索
zg --preview detail "主题偏好在启动时从哪里恢复" --limit 5
# 构建或检查当前工作区索引
zg --index --embedding local/potion-code-16m-v2
zg --status
# 接入 Agent
zg --install --target codex --yes需要理解选择逻辑和完整流程时进入专题指南；需要查找命令时使用本页和内置帮助。
使用内置帮助
zg --help
zg --help search
zg --help models
zg --help file-types
zg --help environment
zg --version最常用的环境变量包括 ZVEC_GREP_MODE、ZVEC_GREP_EMBEDDING、ZVEC_GREP_MODEL_CACHE 和 ZVEC_GREP_DEVICE。完整列表及优先级请运行 zg --help environment。