CLI reference
heddle status
Shippedheddle status [OPTIONS] Show what needs attention and the next safe Heddle action. Observe-only: it creates nothing, so it is the safe first command in any directory, including one that has never seen Heddle.
Output text (default) · json · json-compact
status is the CLI's own recommended entry point, and the one command an agent should run before anything else. It reports the repository capability (plain Git, Git Overlay, Native Heddle), the current thread and state, what is dirty, and a Next block naming the exact command to run. In a plain Git checkout with no .heddle, it exits 0, prints command: heddle init, and writes nothing.
The JSON form is the one to script against. --output json carries repository_capability, storage_model, heddle_initialized, git_branch and a verification block, which together are enough for an agent to branch without parsing prose. --output json-compact trims to the decision surface — output_kind, next_action, changed_paths — for fewer tokens.
--watch refreshes in place; --short prints the one-line form shell prompts use.
Flags
--short, -s- Short format.
--watch- Continuously refresh status.
Exit codes
Declared by this command's contract, verbatim. Anything not listed
contracts only to 0 on success and an unspecified
non-zero on failure. The full table
and the retry rule — in short, 75 is the only code that
is safe to retry.
0- ok
74- io reading workspace state
Examples
The safe probe: a Git checkout Heddle has never seen
bash$ heddle statusHeddle statusRepository: Git repo (setup needed)Git branch: mainHealth: setup neededSetup needed: Git repo detected; initialize Heddle with heddle initNext command: heddle init# no .heddle was created — status never writesThe machine form
bash$ heddle status --output json{"output_kind":"status","repository_capability":"plain-git","heddle_initialized":false,…}