From cc649a7fe27d0f2bc3b1790d0fa91931b35d0a02 Mon Sep 17 00:00:00 2001 From: zhi Date: Sat, 21 Mar 2026 17:39:26 +0000 Subject: [PATCH] Document CLI output and exit conventions --- README.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/README.md b/README.md index 9c944be..b2531d8 100644 --- a/README.md +++ b/README.md @@ -58,6 +58,37 @@ internal/ - **Padded-cell mode**: When `pass_mgr` is available, auth tokens are resolved automatically. Manual `--token` flags are rejected. - **Manual mode**: When `pass_mgr` is not available, `--token` must be provided explicitly to authenticated commands. +## Output / Error Contract + +### Human-readable mode + +Default output is human-readable: +- list commands render simple tables +- get/detail commands render key-value output +- empty lists render `(no results)` + +### JSON mode + +`--json` can be supplied globally and produces structured JSON on stdout. + +Current contract: +- success payloads go to **stdout** as JSON +- errors go to **stderr** as plain text +- the CLI does **not** wrap successful payloads in a universal envelope yet +- list/get payloads preserve canonical code-bearing fields whenever the backend already returns them + +This is intentionally simple so agents can pipe `hf ... --json` into other tooling without first stripping banners or mixed text. + +### Exit / stderr conventions + +Current CLI convention is: +- exit `0` on success +- exit `1` on command/validation/runtime errors +- user-facing errors are written to **stderr** +- success output is written to **stdout** + +There is not yet a finer-grained exit-code taxonomy; callers should currently treat any non-zero exit as failure. + ## Current Status ### Implemented