Errors & exit codes

When hirotm fails, it exits with a non-zero status. With the default global --format ndjson, stderr is JSON: an object that always includes error (a short human-readable message). It usually includes code (a stable machine-readable string) and sometimes retryable, hint, status, url, or extra fields that help you fix the command. With --format human, the same information is printed as plain text on stderr (not JSON). Use exit code ($? in shells) for coarse decisions, and code when you want a precise reason without parsing text.

Success stdout follows global --format (ndjson vs human). Failures use stderr; ndjson → JSON payload, human → plain text.

Exit codes

Code	When it happens	What to do
0	Command succeeded	Parse stdout per Response format: default `ndjson` (line-oriented lists, single-line JSON for writes) or `human` (tables / labeled text).
1	Generic failure, many 5xx API errors, rate limits, or other unmapped HTTP cases	Read `error` and `code`. If `retryable` is true, a short backoff may help.
2	Wrong or incomplete command line (missing flags, bad values before the API is called)	Fix flags and arguments; do not retry the same line unchanged.
3	Not found (often API 404), or a path / id that does not exist locally (for example a missing file or release id)	Refresh ids or slugs (`boards list`, `boards describe`), or fix file paths.
4	Forbidden — CLI policy or 403; you are not allowed to do this	Change access in the app; do not keep retrying writes.
5	Conflict — 409 (duplicate or conflicting state)	Adjust idempotency: skip create, pick another name, or resolve the conflict in the app.
6	Unreachable — no HTTP response (server down, connection refused, etc.)	Start the app or run the `hint` command (often `hirotm server start`), and verify `--dev` and `--profile` match the running server, and that `port` in that profile’s `config.json` matches the process you expect.
7	Timeout — API request timed out, or the server did not become healthy in time	Retry after a delay; check load and logs.
8	Version mismatch — reserved for future CLI/API compatibility checks	Update Task Manager or the CLI per the message.
9	Bad request — API 400 / 422 (validation or bad body)	Fix parameters or payload shape; different from “not found”.
10	Unauthenticated — 401	Configure CLI access / API key in the app when that flow exists.

Fields on stderr

Field	Meaning
`error`	Human-readable summary (always present).
`code`	Stable identifier; prefer this in automation.
`retryable`	If `true`, a later retry may succeed (timeouts, some server errors).
`hint`	Optional copy-paste recovery (for example how to start the server).
`status`	HTTP status when the failure came from the API.
`url`	Request URL that failed (when applicable).
`serverCode`	If the API sent its own `code` field, it is preserved here while `code` stays the normalized CLI value.

Common `code` values (from the API)

These appear when the CLI talked to the server and got an HTTP error:

`code`	Typical meaning
`bad_request`	Validation or malformed input (400, 422).
`unauthenticated`	Missing or invalid credentials (401).
`auth_cli_key_required`	The server profile has `require_cli_api_key: true` and the request did not include an `Authorization: Bearer …` header. Mint a key with `hirotaskmanager server api-key generate` and put it in the active profile’s `api_key`, or pass `--api-key` per command. See Server operations → CLI API keys.
`auth_invalid_cli_key`	A CLI API key was sent but did not match any active key on the server (revoked or wrong). Re-issue or paste the correct key.
`forbidden`	Not allowed for this board / CLI policy (403).
`not_found`	Board, task, list, or route does not exist (404).
`conflict`	Duplicate or state conflict (409). For example, creating or renaming a release to a name that already exists on that board returns 409 (not 400), so `hirotm` exits 5 with this `code`.
`request_timeout`	HTTP 408 (rare) or aligned server timeout.
`version_mismatch`	426 — upgrade path may be required later.
`rate_limited`	429 — slow down and retry.
`internal_error`	5xx — server-side problem; may be `retryable`.
`http_error`	Other HTTP status mapped to exit 1.

Common `code` values (before the API)

These are checked locally when your flags or files are wrong:

`code`	Typical meaning
`missing_required`	Required argument or option omitted.
`invalid_config`	A profile’s `config.json` failed validation (wrong fields for the role, public bind without a key, missing `api_url`/`api_key` on a client profile, etc.). The error names the offending field and profile path. See Profiles → Validation rules.
`invalid_value`	Bad number, port, id, or similar.
`mutually_exclusive_options`	Conflicting flags (for example `--color` and `--clear-color`).
`conflicting_input_sources`	More than one of flag / file / stdin for the same input.
`conflicting_clear_with_input`	`--clear-*` combined with a value for the same field.
`invalid_json`	File or stdin was not valid JSON where JSON was expected.
`invalid_input_shape`	JSON was valid but not the expected array/object shape.
`no_update_fields`	An update command had nothing to change.
`release_not_found_by_name`	`--release` name does not exist on that board.
`emoji_validation_failed`	`--emoji` value was rejected.

Connection and server process

`code`	Typical meaning
`server_unreachable`	Could not open an HTTP connection; check that Task Manager is running.
`request_timeout`	A request over the network exceeded the CLI timeout.
`server_start_timeout`	`server start` waited for health but the API did not respond in time.
`server_exited`	Foreground server child exited with an error.
`no_managed_server`	`server stop` had no pid file for this profile.
`stale_pid`	Recorded background pid was dead; file was cleared.
`signal_failed`	Could not send stop signal to the recorded process.

Other

`code`	Typical meaning
`file_not_found`	A `--body-file`, `--description-file`, or similar path does not exist.
`response_inconsistent`	Rare: the server response did not contain an entity the CLI expected after a mutation.
`internal_error`	Unexpected failure inside the CLI (including unknown errors).
`confirmation_required`	Add `--yes`.
`confirmation_declined`	Declined at prompt.

Example (stderr only)

{
  "error": "Board not found",
  "code": "not_found",
  "status": 404,
  "url": "http://127.0.0.1:3001/api/boards/missing-slug"
}

hirotm CLI — global options and command index
Concepts — boards, lists, tasks, Trash
CLI access policy — why forbidden may appear

Get Started

CLI

Hiro Developers

Exit codes

Fields on stderr

Common `code` values (from the API)

Common `code` values (before the API)

Connection and server process

Other

Example (stderr only)

​Exit codes

​Fields on stderr

​Common code values (from the API)

​Common code values (before the API)

​Connection and server process

​Other

​Example (stderr only)

​Related

Exit codes

Fields on stderr

Common `code` values (from the API)

Common `code` values (before the API)

Connection and server process

Other

Example (stderr only)

Related