| @@ -727,10 +727,9 @@ terminal, and follows these rules so every noun reads the same way. |
| 727 | 727 | |
| 728 | 728 | - A list command prints one row per item, tab-separated, no header. |
| 729 | 729 | Columns run identifier, state, then description; a trailing column |
| 730 | | may carry a word (=due 2027-01-01=, =via team=). The =gitbay= CLI pads |
| 731 | | the tabs into aligned columns when stdout is a terminal and leaves |
| 732 | | them as tabs when piped, so =cut -f= sees the same bytes stock ssh |
| 733 | | prints. Under =--json= nothing is touched. |
| 730 | may carry a word (=due 2027-01-01=, =via team=). Piped, a timestamp in |
| 731 | a row is RFC3339 to the second, UTC. Under =--json= nothing is |
| 732 | touched. |
| 734 | 733 | - An empty list prints nothing on stdout and =nothing to list= on |
| 735 | 734 | stderr. |
| 736 | 735 | - A mutation prints one line: verb, object, identifier |
| @@ -748,6 +747,43 @@ terminal, and follows these rules so every noun reads the same way. |
| 748 | 747 | something to them (a key, a member, a label on an issue), =set= for |
| 749 | 748 | a value, =revoke= for a credential, =show= and =list= for reads. |
| 750 | 749 | |
| 750 | ** At a terminal |
| 751 | |
| 752 | The =gitbay= CLI sends a leading =--term=<cols>[,color]= argument on |
| 753 | the SSH command line when stdout is a terminal (OpenSSH's multiplexed |
| 754 | sessions, which the CLI uses, do not forward a session's =SetEnv=). |
| 755 | The server strips =--term=<v>= wherever it appears in the argument |
| 756 | list. The server then prints: |
| 757 | |
| 758 | - lists under a header, padded, fitted to the width (the title or |
| 759 | description column is cut with =…= first), states in colour, ages as |
| 760 | =2h ago=, and the next page as a command on stderr (piped output |
| 761 | keeps a =next\t<cursor>= row instead); |
| 762 | - =show= views with a title line, aligned fields, the body rendered |
| 763 | from markdown or org, one line per event, and comments under a rule; |
| 764 | a sub-table (labels, revisions, and the like) carries a section label |
| 765 | line in both terminal and piped output; timestamps as |
| 766 | =2026-09-23 23:26 UTC=. =wiki show= piped prints the page source |
| 767 | verbatim; the rendered page is terminal-only; |
| 768 | - help with flag descriptions, defaults, and examples; =gitbay --help= |
| 769 | groups commands under WORK, REPOSITORIES, YOU and INSTANCE; |
| 770 | =help --json= adds =flags= and =examples=. |
| 771 | |
| 772 | =NO_COLOR=, =TERM=dumb= and =--no-color= drop the colour. =show=, |
| 773 | =diff= and =log= at a terminal go through =$GITBAY_PAGER=, else |
| 774 | =$PAGER=, else =less= (with =LESS=FRX= when =LESS= is unset); an empty |
| 775 | =GITBAY_PAGER= turns paging off. Paging never applies to =--follow=, |
| 776 | =--json=, or piped output. |
| 777 | |
| 778 | Stock ssh without the CLI's multiplexing gets the plain output unless |
| 779 | it passes the same leading argument or sets the environment variable |
| 780 | sshd is told to accept: |
| 781 | |
| 782 | #+begin_src sh |
| 783 | ssh git@gitbay.org --term=120,color issue list krz/gitbay |
| 784 | ssh -o SetEnv=GITBAY_TERM=120,color git@gitbay.org issue list krz/gitbay |
| 785 | #+end_src |
| 786 | |
| 751 | 787 | * Scripting |
| 752 | 788 | |
| 753 | 789 | Every read command takes =--json= and emits one envelope: |