HeyDeer CLI
Review your branch and uncommitted changes from the terminal before you open a pull request. The HeyDeer CLI prints the findings where you work, and coding agents can run it too.
Install and sign in
The CLI needs Node.js 22 or later, a repository on GitHub with HeyDeer installed, and write access to that repository.
npm install -g heydeer
heydeer loginheydeer login prints a link and a code. Open the link, sign in to HeyDeer with GitHub and enter the code. The page shows where the sign-in was requested from, so check that it’s your computer before you allow it.
| Command | What it does |
|---|---|
heydeer login | Signs in to HeyDeer on this computer. |
heydeer status | Shows who the CLI acts as. |
heydeer logout | Signs out on this computer. |
heydeer --version | Shows the version of the CLI you have installed. |
The CLI saves its sign-in in ~/.config/heydeer/credentials.json, or in %APPDATA%\heydeer on Windows. A sign-in lasts 30 days after it was last used, and 90 days at most; run heydeer login again when it ends.
Review your changes
Run the review from inside the repository, with a sentence about what the changes are meant to do:
heydeer review "Retry failed uploads. Fixes #123."HeyDeer reviews the commits on your branch and the uncommitted changes to tracked files, against the merge base with origin’s default branch. It reads the description like a pull request’s, including the issues it mentions, and checks the code against it. For a longer description, write it in a file and pass --description-file.
The CLI shows the repository, base, branch and depth, lists the files it sends, and follows the review’s progress. When the review finishes, it prints each finding with its severity, file and line.
Options
| Option | What it does |
|---|---|
--description-file <path> | Reads the description from a file instead of the command line. |
--base <ref> | Compares against another branch or commit, for work that targets it. |
--include-untracked | Also reviews new files you haven’t added to Git yet, unless they’re gitignored. |
--depth standard|deep | Runs this review at another depth than the repository’s. Deep is on paid plans. |
--full | Reviews all the changes, not only those since the branch’s last review. |
--dry-run | Lists the files that would be sent and the ones that stay on your machine, without signing in or starting a review. |
--json | Prints the finished review as JSON, for scripts and coding agents. |
What stays on your machine
Only the diff from the merge base and your description leave your computer; HeyDeer reads the rest of the code from GitHub. The CLI keeps these files out of the review and lists them under Left on this machine:
- Credential files, such as .env files and private keys.
- Changes that contain a credential in a known format.
- Binary files.
- A change to one file larger than 1 MB.
All the changes together can be up to 32 MB of diff. For more than that, pass a closer --base or review the changes in a pull request. Run --dry-run to see the exact list before anything is sent.
Run it again after fixing
Each review of a branch rechecks the findings its last review left open, so the next run tells you which ones your fix resolved.
When the repository has Review only new changes on, a later review of the branch covers just what changed since its last full review. After three such reviews, or once most of the changes are new since that review, the next one covers all the changes again. Pass --full to review everything at any time. If nothing changed since the last review, the CLI says so and starts no review.
Use it from scripts and coding agents
With --json, the finished review goes to standard output as one JSON object and the progress goes to standard error. Each finding has a severity, a title, a file and line, and a body that explains it.
To have Claude Code, Codex or Cursor review its own work before opening a pull request, add an instruction like this to 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.The CLI exits with one of these codes:
| Exit code | Meaning |
|---|---|
| 0 | The review finished, with or without findings. |
| 1 | The review failed, or every changed file had to stay on your machine. |
| 2 | The command or its options weren’t valid. |
| 130 | You canceled with Ctrl+C. |
A finished review exits with 0 whether or not it has findings, so read the findings from the JSON to decide whether a branch is ready.
Credits
A local review uses the credits of the workspace whose installation covers the repository, and is charged as private code in every repository. A dry run, and a run where nothing changed since the last review, use no credits. Each person can start up to 30 local reviews an hour. Ctrl+C cancels the review on HeyDeer too; press it twice to stop the CLI at once.