Installation
The hatchback CLI brings your project's feedback into the terminal. You can read what reviewers pinned, reply, mark fixes and run review sessions without opening the app. Coding agents use the same commands.
Using a coding agent? Paste one prompt into Claude Code, Cursor or Codex and it will handle the setup. See agent installation.
Requirements
- Node.js 20 or newer. Check with
node --version. - A Hatchback account with access to at least one project.
- macOS, Linux or Windows.
Install
Install the CLI globally to get the hatchback command:
npm install -g hatchback-toolsIf you use pnpm, run pnpm add -g hatchback-tools instead. To try it without installing anything, put npx -y hatchback-tools@latest in front of any command:
npx -y hatchback-tools@latest feedbackCheck that it worked:
hatchback --versionSign in
hatchback loginThe CLI shows a one-time code and opens Hatchback in your browser. Check that the code matches, then approve. The CLI saves a token for this machine in ~/.config/hatchback/credentials.json. Only your user account can read that file. The token lasts a year, and hatchback logout revokes it.
- On a machine without a browser, such as over SSH, run
hatchback login --no-browserand open the printed link on any device. - Only approve a sign-in you started yourself. Anyone holding the token can act as you.
- Run
hatchback whoamiat any time to see who you're signed in as, and which server and saved login are in use.
Link a repository to a project
In the repository for your site, pick the Hatchback project its feedback belongs to:
hatchback linkIf you have more than one project, the CLI asks which one. You can also name it directly with hatchback link my-site, using its slug, id or exact name. Run hatchback projects to list slugs. Linking writes .hatchback.json, which holds the project slug and no secrets. Commit it so teammates and CI use the same project.
No project for this site yet? Create one and link it in one step. It prints the script tag to add to your site:
hatchback projects create "My site" --url https://my-site.comhatchback snippet prints the tag again later, and hatchback snippet --check http://localhost:3000 confirms a page includes it.
Try it
hatchback feedback # open feedback in the active session
hatchback feedback show <id> # one item, with its repliesNext: every command and when to use it, or connect a coding agent.
CI and scripts
In CI there's no browser for hatchback login, so use an API token instead. Create one in Settings → API & agents. You can limit it to one project, choose its permissions and set an expiry. Then set:
HATCHBACK_TOKEN=hb_... # store this as a CI secret
HATCHBACK_PROJECT=my-site # instead of .hatchback.jsonStore the token as a secret, never in the repository. The same token works with the HTTP API at https://api.hatchback.app/api/v1, sent as Authorization: Bearer hb_.... Each account can make 300 requests a minute (60 of them writes). Over the limit, the API returns 429 with a Retry-After header.
Updating
npm install -g hatchback-tools@latest
hatchback skills update # in each repo where you installed the agent skillsYou don't need to watch for releases. When a newer version is out, commands print a one-line notice with the right update command. They also tell you when a repository's agent skills are older than your CLI. Turn the notices off with HATCHBACK_NO_UPDATE_NOTIFIER=1. They're never shown with --json or in CI.
Configuration
| Variable | What it does |
|---|---|
HATCHBACK_TOKEN | API token. Overrides hatchback login. |
HATCHBACK_PROJECT | Project slug or id. Overrides .hatchback.json. |
HATCHBACK_API | API URL. Defaults to the server you signed in to, then https://api.hatchback.app. It must use https, except for localhost. |
HATCHBACK_CONFIG_DIR | Where the login is saved. Defaults to ~/.config/hatchback. |
HATCHBACK_JSON=1 | The same as passing --json to every command. |
HATCHBACK_NO_UPDATE_NOTIFIER=1 | Turns off update notices. |
Troubleshooting
Start with hatchback whoami. It shows which account, server and saved login are in use. Most errors also say what to do next.
- “Not logged in” in one terminal but not another: you signed in with
HATCHBACK_CONFIG_DIRset. The error names the directory it found and theexportline to use. - “The API rejected your token”: it expired or was revoked. Run
hatchback loginagain. project_not_foundwhen linking: slugs often differ from names. The error lists the projects you can access.- Empty feedback list: feedback may be in an older session. Run
hatchback feedback --all. cli_outdated: this version is too old for the API. Run the update command shown in the error.
Uninstall
hatchback logout # revokes this machine's token
npm uninstall -g hatchback-tools