Exit codes
hh's exit codes are part of its compatibility contract
(Stability policy, section (a)): an existing code's meaning
for an existing command never changes, and new codes are only ever added. A
script or CI job can rely on everything on this page.
This page describes what hh actually returns today, checked against the
code and pinned by tests in hh/tests/cli_conformance.rs. Where that differs
from what you might expect from the one-line summary
(0 ok · 1 generic error · 2 usage error · 3 session not found ·
4 redaction/policy block), the difference is listed under
Known gaps. Those gaps are documented behavior; changing any
of them would itself be a breaking change.
Summary
| Code | Meaning | Returned by |
|---|---|---|
0 |
Success | Every command, when it succeeds. hh run / hh mcp-proxy: see pass-through. |
1 |
Generic error | Any command, for any failure not listed below. |
2 |
Usage error | Any command, when the command line itself is invalid (clap); hh watch, for a directory it cannot or will not watch. |
3 |
Session not found | inspect, replay, export, delete, rename, scan <session>, redact |
4 |
Redaction/policy block | hh scan when it finds secrets |
| other | The wrapped command's own code | hh run, hh mcp-proxy |
0 — success
The command did what was asked. Some commands give 0 a narrower meaning:
| Command | 0 means |
|---|---|
hh scan |
No secrets found (clean). |
hh doctor |
Every check passed. |
hh init |
Setup succeeded, including "already set up; nothing changed". |
hh run, hh mcp-proxy |
The wrapped command exited 0 (see below). |
hh --help, hh <sub> --help, hh help, hh --version |
Help or version printed. |
1 — generic error
Anything that went wrong and isn't one of the codes below. Every such error
prints an actionable ✗ <what failed> / why: / hint: block to stderr.
Examples, all observed:
- The data directory or database can't be opened (any command that opens the store).
hh import: the file can't be read, or the bundle fails validation. There is deliberately no separate "corrupt bundle" code (Export & import).hh search: an invalid FTS5 query (for example an unterminated").hh doctor: at least one check failed (Doctor).hh init: a directory, the database or the config file could not be created, read, renamed or backed up; the existing config is malformed; or--forcewhile a legacyhalfhand.tomlis the file in use (Setup).hh gc,hh stats: a prune, vacuum or read error.- A refused irreversible action in a non-interactive shell:
hh deleteorhh redactwithout--yes, andhh export --no-redact(which always requires an interactive confirmation). hh replaywithout--webwhen stdout is not a terminal.hh inspect --json --diff(the two output formats are mutually exclusive).hh run --adapter <name>with an unknown adapter name.hh run -- <command>when the command can't be started at all (for example it does not exist).hh mcp-proxywithHH_SESSION_IDset to a session that does not exist.
2 — usage error
The command line could not be parsed, so nothing ran. This comes from the argument parser (clap), before any subcommand logic:
- an unknown flag (
hh list --bogus) or subcommand (hh frobnicate); - a flag value of the wrong type (
hh list --limit many); - a missing required argument (
hh deletewith no session); - flags that conflict (
hh export --html --bundle,hh scan <session> --all,hh inspect --context --step 1); - an invalid session name: empty or blank, longer than 100 characters, or
containing control characters (
hh rename last "",hh run --name "" -- …), orhh renamewith neither a name nor--clear; hhwith no subcommand at all (help is printed to stderr).
hh watch also exits 2 for a usage problem it finds after parsing, before
anything is recorded: a path that does not exist or is not a directory, or
a directory it refuses to watch (your home directory, a directory containing
it, or a filesystem root). See Watching a directory.
hh watch exits 0 when the directory is already being watched (it reports
the running session) and when --stop finds nothing to stop.
3 — session not found
The session argument (a short id, full id, or last) didn't resolve to a
recorded session. last on an empty store counts. Returned by every command
that takes a session argument:
| Command | Notes |
|---|---|
hh inspect [<session>] |
default last |
hh replay [<session>] |
--web, or in a terminal; without a terminal the TTY check fails first (1) |
hh export [<session>] |
default last |
hh delete <session> |
|
hh rename <session> |
|
hh scan [<session>] |
default last; --all on an empty store is clean (0) |
hh redact <session> |
4 — redaction or policy block
hh scan found at least one secret, in the session it was given or, with
--all, in any session. --json keeps the same code. This is the only place
4 is used today, so a CI job can gate on hh scan --all
(Redaction).
hh run and hh mcp-proxy pass the wrapped command's code through
hh run -- make behaves like make: once recording has started, hh run
exits with the wrapped command's own exit code, whatever it is. The same
holds for hh mcp-proxy and the MCP server it wraps.
hh run -- falseexits1;hh run -- sh -c 'exit 3'exits3;hh run -- sh -c 'exit 4'exits4. For these two commands,2,3and4mean whatever the wrapped command meant by them, not usage error, session not found or policy block.- A wrapped command killed by a signal, or whose code can't be determined,
makes
hhexit1. - Errors in
hhitself before the command starts (an unknown--adapter, a command that can't be spawned, a store that can't be opened) are1, and bad flags are2.
The recorded code is also stored: hh list --json / hh inspect --json
report it as exit_code (JSON reference).
Known gaps
Places where today's behavior differs from the one-line contract
0 ok · 1 generic · 2 usage · 3 session not found · 4 policy block. They are
documented, tested and stable; none of them is changed here, because
changing an exit code is a breaking change under the stability policy.
- Pass-through.
hh runandhh mcp-proxyreturn the wrapped command's code, so for them2/3/4do not carry their contract meaning (see above). - Some "session not found" cases exit
1.hh mcp-proxywith an unknownHH_SESSION_ID.hh replay <session>without a terminal: the terminal check runs before the session lookup.
- Some usage-style errors exit
1, not2. These are checked byhhafter parsing, not by the argument parser:hh inspect --json --diff,hh run --adapter <unknown>, andhh replaywithout a terminal. - Policy refusals other than
scanexit1, not4.hh export --no-redactwithout an interactive confirmation, andhh delete/hh redactwithout--yesin a non-interactive shell.4means exactly "hh scanfound secrets".