CLI reference

Exit codes

Heddle follows BSD sysexits.h. Classification is keyed on typed error kinds — never on message text — and each pairing is pinned by a regression test in the binary. If you are driving the CLI unattended, this page is the shortest thing on the site worth reading in full.

The table

Exit codes
Code	Symbol	Meaning
`0`	`Ok`	Success.
`64`	`Usage`	Invalid CLI args, unknown subcommand, malformed flag (EX_USAGE).
`65`	`DataErr`	Well-formed input, semantically rejected (EX_DATAERR). Includes corrupted or undecodable repository state.
`73`	`CantCreat`	Output file refused — exists, unwritable, or state dir uncreatable.
`74`	`IoErr`	Generic IO failure during read/write (EX_IOERR). The default fallback.
`75`	`TempFail`	Transient failure; safe to retry with the same args (EX_TEMPFAIL).
`76`	`Protocol`	Remote rejected the payload; retrying without changing inputs will fail the same way (EX_PROTOCOL).
`77`	`NoPerm`	Operation refused for permission reasons (EX_NOPERM).
`78`	`Config`	Configuration or a required precondition is missing, ambiguous, or invalid — not just config-file errors. Covers unconfigured remotes and upstreams, a missing repository, and conflicting identity.

2 is reserved for set -e and unhandled panics. Heddle never emits it intentionally — it surfaces naturally.

The retry rule

75 TempFail — retry with the same args. This is the only one. A hosted rate limit arrives here too, so backoff belongs in your agent.
76 Protocol — the inputs are the problem, not the network. Don't loop.
78 Config — a precondition is missing. Print the missing setting rather than retrying.
65 DataErr — semantic rejection of well-formed input. No retry with the same inputs will help.
74 IoErr — the catch-all.
64 Usage — you spelled something wrong. An unknown subcommand or a flag the command does not have lands here, which is what every fabricated command in a doc produces.

Commands that declare their codes

Most commands have not been swept yet. Those implicitly contract to 0 on success and an unspecified non-zero on failure — treat them as “may return any code above” until their contract entry declares otherwise. These 12 do declare, and the declarations are rendered here straight from the command catalog:

heddle init: 0 ok
73 cannot create state directory
78 workspace config invalid
heddle import url: 0 ok
75 server or source unreachable; safe to retry
76 source import rejected
77 not authorized
78 configuration missing
heddle status: 0 ok
74 io reading workspace state
heddle verify: 0 verified clean
65 verification reports blocked state
74 io reading state
heddle sync git: 0 ok
75 remote unreachable; safe to retry
76 remote rejected payload
heddle bridge git import: 0 ok
65 malformed git repo or unimportable refs
74 io reading git refs
heddle push: 0 ok
75 remote unreachable; safe to retry
76 remote rejected payload; do not retry without changing inputs
78 no upstream configured
heddle pull: 0 ok
75 remote unreachable; safe to retry
76 upstream protocol error
78 no upstream configured
heddle grant create: 0 ok
75 server unreachable; safe to retry
76 server rejected the grant; do not retry without changing inputs
77 not permitted to grant on this spool, or agent cannot grant maintainer/admin/owner
78 not authenticated or spool path missing
heddle grant list: 0 ok
75 server unreachable; safe to retry
77 not permitted to list grants on this spool
78 not authenticated or spool path missing
heddle grant delete: 0 ok
75 server unreachable; safe to retry
76 server rejected the delete; do not retry without changing inputs
77 not permitted to delete grants on this spool
78 not authenticated or spool path missing
heddle promote: 0 ok
75 server unreachable; safe to retry
76 target slug taken or request rejected; do not retry without changing inputs
77 not the owner, or account is not claimed/verified
78 not authenticated or spool path missing

Contract stability

The CLI's cargo version is the JSON contract version. Pin a heddle-cli version constraint and the catalogued output shapes — output_kind, declared discriminators, exit_codes — hold for that minor. Breaking changes to any catalogued output bump the minor pre-1.0 and the major after; additive changes, including a new optional exit code, bump the patch.

Ground truth: heddle 0.26.0. See also the JSON output contract, where the error envelope that carries the code lives.