Commit 0e343a88e5

0e343a88e574820153278399655f960504632baa

parent: dbc19527c5

Verified · cmc

cmc <hello@cleberg.net> · 2026-09-12 05:58 UTC

wiki: the plain-output rules

Ref #183

Layout: unified · split

.gitbay/wiki/Users.org +28
@@ -656,6 +656,34 @@ someone else.
656You are never mailed about your own actions, and only verified primary 656You are never mailed about your own actions, and only verified primary
657addresses receive anything. Delivery retries on relay failure. 657addresses receive anything. Delivery retries on relay failure.
658 658
659* Output rules
660
661=--json= is the contract; the plain output is for a person at a
662terminal, and follows these rules so every noun reads the same way.
663
664- A list command prints one row per item, tab-separated, no header.
665 Columns run identifier, state, then description; a trailing column
666 may carry a word (=due 2027-01-01=, =via team=). The =gitbay= CLI pads
667 the tabs into aligned columns when stdout is a terminal and leaves
668 them as tabs when piped, so =cut -f= sees the same bytes stock ssh
669 prints. Under =--json= nothing is touched.
670- An empty list prints nothing on stdout and one line on stderr saying
671 what was empty (=no open issues in krz/gitbay=).
672- A mutation prints one line: verb, object, identifier
673 (=created krz/gitbay#7=). A second line appears only for something
674 to copy: a URL, a token shown once.
675- A bad invocation prints =usage:= and the command's registered usage,
676 the same text =help <noun>= shows. Exit 2.
677- A refusal says who may and what to do instead: =only admins of acme
678 can manage teams; ask one to add you=. Exit 4. A thing that does not
679 exist, or that you may not know exists, is exit 3.
680- stdout is the result; stderr is everything else: progress, a note
681 that output was truncated, errors.
682- Verbs: =create= and =delete= for things with their own identity
683 (repository, issue, release, team), =add= and =remove= for attaching
684 something to them (a key, a member, a label on an issue), =set= for
685 a value, =revoke= for a credential, =show= and =list= for reads.
686
659* Scripting 687* Scripting
660 688
661Every read command takes =--json= and emits one envelope: 689Every read command takes =--json= and emits one envelope: