docs: shorten help and migration texts to gh-like brevity

Long texts no longer restate the flag list, the instance selection
of tea help environment, the config keys with descriptions or the
team argument rules shown under ARGUMENTS; webhook events come from
services.WebhookEvents; the migration guide refers to tea help
formatting for the terminal layout.

Signed-off-by: bircni <bircni@icloud.com>
This commit is contained in:
bircni committed 2026-10-12 20:14:09 +02:00
1 parent 8bf979099b
commit ab8ba6df4f
9 files changed
+31 -101

No files matched your search

+7 -23
View File
@@ -295,29 +295,13 @@ names; `--jq` / `-q` filters the result and implies `--json`. Commands that
produce no resource, such as deletes, reject `--json` with a usage error instead
of printing nothing. See `tea help formatting`.
Lists follow gh. On a terminal they print a "Showing 30 of 112 open issues in
alice/project" line, an uppercase header row and columns fitted to the terminal
width, with times relative ("about 3 hours ago"), states colored and the first
column linked to the web page (`tea config set hyperlinks never` turns the links
off). An empty list prints a message on stderr and exits 0. When stdout is not a
terminal, lists print tab-separated values without header, color or links, with
times in RFC 3339 UTC and stable columns, so `cut -f1` works; a `--page` hint
goes to stderr when more results follow. Still prefer `--json` in scripts: the
columns may change. Tabs and line breaks in list cells become spaces, and
control characters such as escape sequences are dropped from all human output,
bodies included.
Commands that change resources report each change on stderr, such as
`✓ Closed issue alice/project#5 (Fix login)` or `! … is already closed`, only
when stdout is a terminal. Create commands print the URL of the new resource
on stdout, so `url=$(tea issue create …)` works; other changes print nothing
when piped. With `--json` they print the changed resource instead.
Issue, pull request, release and comment bodies are rendered as Markdown on a
terminal and printed as written when piped; `tea config set markdown raw` always
prints them as written. Long output on a terminal goes through a pager
(`TEA_PAGER`, the `pager` preference or `PAGER`). Each command starts the pager
at most once.
When stdout is not a terminal, lists print tab-separated values without header,
color or links, with times in RFC 3339 UTC, and a `--page` hint goes to stderr;
prefer `--json` in scripts. Commands that change resources report each change on
stderr only on a terminal. Create commands print the URL of the new resource on
stdout, so `url=$(tea issue create …)` works; other changes print nothing when
piped. Bodies are rendered as Markdown only on a terminal (`tea config set
markdown raw` turns this off). See `tea help formatting` for the terminal layout.
## Exit codes