HeyDeer CLI
在打开拉取请求之前,从终端审查你的分支和未提交的改动。HeyDeer CLI 会在你工作的地方输出发现的问题,编程代理也能运行它。
安装并登录
CLI 需要 Node.js 22 或更高版本、一个安装了 HeyDeer 的 GitHub 仓库,以及你对该仓库的写入权限。
npm install -g heydeer
heydeer loginheydeer login 会输出一个链接和一个代码。打开链接,用 GitHub 登录 HeyDeer 并输入代码。页面会显示登录请求来自哪里,允许之前请确认是你自己的电脑。
| 命令 | 作用 |
|---|---|
heydeer login | 在这台电脑上登录 HeyDeer。 |
heydeer status | 显示 CLI 以谁的身份操作。 |
heydeer logout | 在这台电脑上退出登录。 |
heydeer --version | 显示已安装的 CLI 版本。 |
CLI 把登录信息保存在 ~/.config/heydeer/credentials.json,Windows 上则在 %APPDATA%\heydeer。登录在最后一次使用后 30 天内有效,最长 90 天;过期后重新运行 heydeer login。
审查你的改动
在仓库目录中运行审查,并用一句话说明这些改动的目的:
heydeer review "Retry failed uploads. Fixes #123."HeyDeer 审查你分支上的提交和已跟踪文件的未提交改动,对比的是与 origin 默认分支的合并基点。它会像读拉取请求描述一样读你的说明,包括其中提到的 issue,并对照说明检查代码。说明较长时,可以写进文件并传入 --description-file。
CLI 会显示仓库、基准、分支和审查深度,列出要发送的文件,并跟进审查进度。审查完成后,它会输出每个发现的问题,以及严重程度、文件和行号。
选项
| 选项 | 作用 |
|---|---|
--description-file <path> | 从文件读取说明,而不是从命令行。 |
--base <ref> | 与另一个分支或提交对比,适用于以它为目标的工作。 |
--include-untracked | 同时审查还没加入 Git 的新文件,被 gitignore 忽略的除外。 |
--depth standard|deep | 这次审查使用与仓库不同的审查深度。深度审查适用于付费方案。 |
--full | 审查所有改动,而不仅是该分支上次审查之后的改动。 |
--dry-run | 列出会发送的文件和留在本机的文件,不需要登录,也不会开始审查。 |
--json | 以 JSON 输出完成的审查,供脚本和编程代理使用。 |
哪些内容留在本机
离开你电脑的只有相对合并基点的 diff 和你的说明;其余代码 HeyDeer 从 GitHub 读取。CLI 会把以下文件排除在审查之外,并在 Left on this machine 下列出:
- 凭证文件,例如 .env 文件和私钥。
- 包含已知格式凭证的改动。
- 二进制文件。
- 单个文件超过 1 MB 的改动。
所有改动合计最多 32 MB 的 diff。超出时,传入更近的 --base,或在拉取请求中审查这些改动。运行 --dry-run 可以在发送前看到确切的清单。
修复后再运行一次
每次审查分支时,都会复查上一次审查留下的未解决问题,所以下一次运行会告诉你修复解决了哪些。
如果仓库开启了只审查新改动,之后对该分支的审查只覆盖上次完整审查以来的改动。连续三次这样的审查之后,或者大部分改动都是那次审查之后的新改动时,下一次会重新审查全部改动。随时传入 --full 都可以审查全部内容。如果自上次审查以来没有任何改动,CLI 会提示并且不会开始审查。
在脚本和编程代理中使用
使用 --json 时,完成的审查会作为一个 JSON 对象输出到标准输出,进度则输出到标准错误。每个发现的问题都包含严重程度、标题、文件和行号,以及解释它的正文。
要让 Claude Code、Codex 或 Cursor 在打开拉取请求前审查自己的工作,可以在 AGENTS.md 中加入这样的指令:
Before opening a pull request, run `heydeer review --json "<what the change does>"`
from the repository root, fix the findings you agree with, and run it again.CLI 会以下列代码之一退出:
| 退出码 | 含义 |
|---|---|
| 0 | 审查完成,无论是否有发现的问题。 |
| 1 | 审查失败,或所有改动的文件都必须留在本机。 |
| 2 | 命令或其选项无效。 |
| 130 | 你按了 Ctrl+C 取消。 |
完成的审查无论有没有发现问题都以 0 退出,所以要从 JSON 中读取发现的问题,来判断分支是否就绪。
积分
本地审查使用安装覆盖该仓库的工作区的积分,并且在所有仓库中都按私有代码计费。试运行,以及自上次审查以来没有改动的运行,不消耗积分。每人每小时最多可以发起 30 次本地审查。Ctrl+C 也会在 HeyDeer 上取消审查;连按两次可立即停止 CLI。