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:

Terminal
npm install -g hatchback-tools

If 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:

Terminal
npx -y hatchback-tools@latest feedback

Check that it worked:

Terminal
hatchback --version

Sign in

Terminal
hatchback login

The 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-browser and 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 whoami at 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:

Terminal
hatchback link

If 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:

Terminal
hatchback projects create "My site" --url https://my-site.com

hatchback snippet prints the tag again later, and hatchback snippet --check http://localhost:3000 confirms a page includes it.

Try it

Terminal
hatchback feedback          # open feedback in the active session
hatchback feedback show <id>   # one item, with its replies

Next: 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:

Environment
HATCHBACK_TOKEN=hb_...          # store this as a CI secret
HATCHBACK_PROJECT=my-site       # instead of .hatchback.json

Store 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

Terminal
npm install -g hatchback-tools@latest
hatchback skills update     # in each repo where you installed the agent skills

You 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

VariableWhat it does
HATCHBACK_TOKENAPI token. Overrides hatchback login.
HATCHBACK_PROJECTProject slug or id. Overrides .hatchback.json.
HATCHBACK_APIAPI URL. Defaults to the server you signed in to, then https://api.hatchback.app. It must use https, except for localhost.
HATCHBACK_CONFIG_DIRWhere the login is saved. Defaults to ~/.config/hatchback.
HATCHBACK_JSON=1The same as passing --json to every command.
HATCHBACK_NO_UPDATE_NOTIFIER=1Turns 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_DIR set. The error names the directory it found and the export line to use.
  • “The API rejected your token”: it expired or was revoked. Run hatchback login again.
  • project_not_found when 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

Terminal
hatchback logout                  # revokes this machine's token
npm uninstall -g hatchback-tools