The CLI contract

Everything on this page holds for every command. The per-command pages cover only what is specific to each.

Global flags #

Every command accepts all of these, and they work in either position, so hiiu --json doctor and hiiu doctor --json are the same command.

Flag	What it does
--cwd <path>	Run as if hiiu was started in <path>
--json	Emit one JSON document on stdout; all chatter goes to stderr
-v, --verbose	More detail on stderr; a stack trace only for an internal error
-q, --quiet	Suppress progress; errors still print
--no-color	Disable ANSI colour
-y, --yes	Accept every default; never prompt
-h, --help	Show help

--version is on hiiu itself and prints the version with the git sha it was built from.

Exit codes #

Extended, never reassigned. Branch on these.

Code	Meaning
0	Success
1	Internal error. Anything reaching the top level uncaught is a bug
2	Usage error: a bad flag or argument
3	Unmet precondition: a missing tool, a dirty tree, an answer hiiu cannot prompt for
4	The app failed to build
5	Verification failed: a route did not render, or requests went unmatched
10	Not implemented

One document, two shapes #

Under --json, stdout carries exactly one JSON document and nothing else. It is one of two shapes, and ok is the discriminator present in both:

{ "ok": true, "hiiu": "0.1.0", "checks": [] }

{
  "ok": false,
  "error": { "code": "NO_SUPPORTED_APP", "message": "...", "exitCode": 3, "hint": "..." }
}

A command that models its own failure returns its own document with a non-zero exit code rather than throwing, so a non-zero exit does not imply an error envelope. doctor is the example: it emits its report with ok: false and exits 3.

The rule holds on every exit path. --help and --version are captured and re-emitted as JSON, and running hiiu with no command at all is a usage error rather than a help dump with exit 0.

Prompting #

hiiu prompts only when stdout is a TTY, and --yes was not passed, and --json was not passed, and CI is unset. Otherwise a missing required answer is exit 3 immediately, and never a hang.

Errors print no stack #

An error hiiu chose prints its message and its hint and never a stack trace, not even under --verbose: the throw site tells you nothing about a chosen outcome carrying a chosen exit code. Anything else reaching the boundary is treated as a bug, and gets a short message normally, a stack under --verbose, and exit 1.

Where state lives #

Nothing is ever written to your repository. See bases and the cache for the two roots and what is in them.

Credentials #

There are none. No account, no login, and no environment variable read anywhere for authentication.

That is deliberate rather than unfinished. Auth arrives with the first write to hiiu's own infrastructure, and nothing the CLI does today writes anywhere but your own machine. Analysis, building, forking, running and serving all work with no account at all.

Nothing is written back. Nothing is written to your repository.