docs: describe the gh-style output, aliases and flags in the 1.0 guide

Update the migration guide for the output on terminals and in pipes,
markdown and hyperlink preferences, verb aliases and gh short flags, -q
and -y, exit codes, the inbox default of notifications, config get, auth
status and token, pr checkout branch names, pr review types, comment
commands, name addressing, and setup-git replacing old helpers. Fix the
merge example, which now needs --yes, and the contributor guide's output
and layering notes.

Signed-off-by: bircni <bircni@icloud.com>

CONTRIBUTING.md

@@ -105,13 +105,17 @@ Use explicit singular noun/verb commands, such as `tea issue list` and
 missing fields when the shared prompting policy permits it, invoke services, and
 render results through injected streams. Destructive commands require confirmation
 or `--yes`; `--no-input` disables implicit interaction. JSON results go to stdout;
-diagnostics and prompts go to stderr. Lists register `--limit`/`--page` with
+diagnostics, prompts and the `✓`/`!` mutation messages (`done`/`warn`) go to stderr.
-`pageFlags` and print through `writeList`, which renders one `terminal.Table`
+Lists register `-L/--limit` and `--page` with `pageFlags` and print through
-(ID or number first, then title or name, then state) through the pager.
+`writeTable` with a `listSpec`: on a terminal an uppercase header row, a "Showing N of
+M …" line, relative times and links in the first column; piped, tab-separated values
+without header. Single items print through `writeView`. Every command has an
+`Example`, and every command group a `Long` text.
 
 ### Internal Package Structure
 
-- `internal/app`: Cobra commands and application dependency construction.
+- `internal/app`: Cobra commands and application dependency construction. It never
+  calls the API directly: every request goes through `internal/services`.
 - `internal/services`: typed workflows over `gitea.dev/sdk`, independent of CLI flags
   and terminal I/O, including pagination policy. Services map SDK types to tea's
   output types; requests the SDK cannot make yet go through the raw helpers in

docs/example-workflows.md

@@ -21,7 +21,7 @@ a nonzero exit code.
 For an explicitly authorized merge in CI:
 
 ```sh
-tea pr merge 123 --repo owner/repository --method rebase --no-input
+tea pr merge 123 --repo owner/repository --rebase --yes --no-input
 ```
 
 Keep credentials in the secret environment or credential store. Never write a token

docs/migration-1.0.md

@@ -1,10 +1,10 @@
 # Migrating to tea 1.0
 
-tea 1.0 rebuilds the CLI around explicit, singular `noun verb` commands (similar
+tea 1.0 rebuilds the CLI around explicit, singular `noun verb` commands modeled
-to GitHub's `gh`), a split configuration, and per-instance accounts. There are no
+on GitHub's `gh` (including its verb aliases and short flags), a split
-compatibility aliases: old command names, plural groups and most short flags are
+configuration, and per-instance accounts. Old command names, plural groups and
-gone, and scripts need updating. This guide lists what changed and what to use
+many old short flags are gone, and scripts need updating. This guide lists what
-instead.
+changed and what to use instead.
 
 Quick checklist:
 
@@ -13,8 +13,8 @@ Quick checklist:
 2. Move the old configuration away, or point tea 1.0 at a new directory
    ([Configuration](#old-configuration-file)).
 3. Log in again ([Logging in](#logging-in-again)).
-4. Replace the old `!tea login helper` Git credential entries
+4. Run `tea auth setup-git` to replace the old `!tea login helper` Git
-   ([Git credential helper](#git-credential-helper)).
+   credential entries ([Git credential helper](#git-credential-helper)).
 5. Regenerate shell completions ([Shell completion](#shell-completion)).
 6. Update scripts: [global flags](#global-flags), [commands](#renamed-commands),
    [arguments](#changed-positional-arguments) and [output](#output-formats).
@@ -118,16 +118,20 @@ never written to disk.
 `tea login helper setup` and `tea login add --git-credentials` wrote two entries
 to `~/.gitconfig` for each instance: an empty `credential.<url>.helper` and
 `!tea login helper`. tea 1.0 has no `login` command, so Git now gets an error
-from that helper and falls back to prompting. Remove both entries, then register
+from that helper and falls back to prompting. Register the new helper:
-the new helper:
 
 ```sh
-git config --global --get-all credential.https://gitea.example.org.helper
-git config --global --unset-all credential.https://gitea.example.org.helper '^!tea login helper$'
-git config --global --unset-all credential.https://gitea.example.org.helper '^$'
 tea auth setup-git --host https://gitea.example.org
 ```
 
+`tea auth setup-git` replaces every credential helper configured for the
+instance URL, the old `!tea login helper` entry included, so that other helpers
+neither answer for tea nor keep a copy of its token. Pass `--keep-helpers` to
+add tea's helper after the existing ones instead; then remove the old entry
+yourself with
+`git config --global --unset-all credential.https://gitea.example.org.helper '^!tea login helper$'`.
+`tea auth status` reports whether the helper is configured.
+
 `tea repo clone`, `tea pr checkout`, `tea pr clean`, `tea repo sync` and
 `tea pr create --agit` authenticate Git without any helper; `tea auth setup-git`
 is only needed for plain `git` commands. Add `--local` to configure only the
@@ -140,24 +144,28 @@ current repository.
 | `--repo` / `-r` | `--repo` / `-R` |
 | `--remote` / `-R` | `--remote` (no shorthand) |
 | `--login` / `-l` | `--host URL`, plus `--user NAME` when the instance has several accounts |
-| `--output` / `-o`, `--fields` / `-f` | `--json [fields]` and `--jq <expression>` |
+| `--output` / `-o`, `--fields` / `-f` | `--json [fields]` and `--jq` / `-q <expression>` |
 | `--debug` / `--vvv` | `--debug` |
-| `--confirm` / `-y`, `--force` / `-f` on destructive commands | `--yes` |
+| `--confirm` / `-y`, `--force` / `-f` on destructive commands | `--yes` / `-y` |
 
 `-R` now means `--repo`: `tea issue list -R origin` fails with
 `invalid repository URL` instead of selecting the `origin` remote. Use
 `--remote origin`.
 
 New global flags: `--no-input` disables prompts, editors and browsers, `--yes`
-accepts confirmations, `--cwd` selects the directory used for repository
+(`-y`) accepts confirmations, `--cwd` selects the directory used for repository
 discovery, and `--sudo USER` acts as another user (administrators only).
 
 ## Renamed commands
 
-All command groups are singular, and the built-in aliases (`ls`, `rm`, `c`, `e`,
+All command groups are singular, and the old built-in aliases (`c`, `e`, `i`,
-`i`, `ms`, `co`, `lgtm`, …) are gone. `tea alias set NAME EXPANSION` defines your
+`ms`, `lgtm`, …) are gone. Subcommands take gh's verb aliases instead: `ls` for
-own top-level shortcuts, for example `tea alias set co 'pr checkout'`; aliases
+`list`, `rm` for `delete`, `new` for `create`, `add` for `issue comment create`,
-for subcommands such as `issue ls` are not possible.
+`pr comment create`, `ssh-key create` and `time create`, `co` for
+`pr checkout`, and `search issues` / `search prs` for `search issue` /
+`search pr`. `tea <command> --help` lists the aliases of each command.
+`tea alias set NAME EXPANSION` defines your own top-level shortcuts, for example
+`tea alias set prs 'pr list --author @me'`.
 
 Top-level groups:
 
@@ -194,16 +202,16 @@ Subcommands:
 | Old | tea 1.0 |
 |---|---|
 | `issues reopen`, `pulls reopen` (alias `open`) | `issue reopen`, `pr reopen` |
-| `pulls approve <n> [comment]` | `pr review <n> --event APPROVED [--body TEXT]` |
+| `pulls approve <n> [comment]` | `pr review <n> --approve [--body TEXT]` (`-a`) |
-| `pulls reject <n> <comment>` | `pr review <n> --event REQUEST_CHANGES --body TEXT` |
+| `pulls reject <n> <comment>` | `pr review <n> --request-changes --body TEXT` (`-r`) |
-| `pulls review <n>` | `pr review <n>` |
+| `pulls review <n>` | `pr review <n>` (`--comment` / `-c` for a plain review comment) |
 | `pulls review-comments` | `pr review comments` |
 | `pulls reply`, `resolve`, `unresolve` | `pr review reply`, `pr review resolve`, `pr review unresolve` |
-| `labels update --id ID` | `label edit ID` |
+| `labels update --id ID` | `label edit <name-or-id>` |
-| `labels delete --id ID` | `label delete ID` |
+| `labels delete --id ID` | `label delete <name-or-id>...` |
 | `labels list --save` | `label export` |
-| `milestones issues <name>` | `milestone issue list <milestone-id>`, or `milestone issue list --by-name <name>` |
+| `milestones issues <name>` | `milestone issue list <milestone>` (title or ID) |
-| `milestones issues add\|remove` | `milestone issue add\|remove <milestone-id> <number>...` (`--by-name` selects by title) |
+| `milestones issues add\|remove` | `milestone issue add\|remove <milestone> <number>...` |
 | `releases assets create` | `release asset upload` |
 | `times add` | `time create` |
 | `times list [user\|#issue]` | `time list [--username USER\|--issue N]` |
@@ -214,7 +222,7 @@ Subcommands:
 | `actions runs delete` (alias `cancel`) | `run delete`; `run cancel` cancels without deleting |
 | `actions workflows dispatch` | `workflow run` |
 | `webhooks update` | `webhook edit` |
-| `comments add <n> [body]` | `issue comment create <n> --body TEXT` (also `pr comment create`) |
+| `comments add <n> [body]` | `issue comment <n> --body TEXT` (also `pr comment`); `--edit-last` and `--delete-last` change your last comment |
 | `notifications read\|unread [all\|id]` | `notification mark-read\|mark-unread [id]...`; use `--all` for every filtered notification |
 | `ssh-keys add` | `ssh-key create` |
 | `login helper setup` | `auth setup-git` |
@@ -225,76 +233,105 @@ Renamed flags that appear on many commands:
 | Old | tea 1.0 |
 |---|---|
 | `--description` / `-d`, `--description-file` (issues, pulls, comments) | `--body`, `--body-file` |
-| `--note` / `-n`, `--note-file` / `-f` (releases) | `--body`, `--body-file` |
+| `--note` / `-n`, `--note-file` / `-f` (releases) | `--notes` / `-n`, `--notes-file` / `-F` (`--body` and `--body-file` are accepted too) |
 | `--content` / `-c` (wiki) | `--body`, `--body-file` |
-| `--labels` / `-L`, `--assignees` / `-a`, `--milestones` / `-m` | `--label`, `--assignee`, `--milestone` |
+| `--labels` / `-L`, `--assignees` / `-a`, `--milestones` / `-m` | `--label` / `-l`, `--assignee` / `-a`, `--milestone` / `-m` |
 | `--referenced-version` / `-v` | `--ref` |
-| `--keyword` / `-k` | `--search` |
+| `--keyword` / `-k` | `--search` / `-S` |
 | `--from` / `-F` (issue list) | `--since` |
 | `--states` / `-s`, `--types` / `-t` (notifications) | `--status`, `--type` |
-| `--page` / `-p`, `--limit` / `--lm` | `--page`, `--limit` |
+| `--page` / `-p`, `--limit` / `--lm` | `--page`, `--limit` / `-L` |
-| `--style` / `-s` (pr merge) | `--method` / `-s` |
+| `--style` / `-s` (pr merge) | `--merge`, `--squash` or `--rebase`, or `--method` / `-s`; without one, the repository's default merge style |
 | `--owner` / `-O`, `--init`, `--labels`, `--trustmodel`, `--branch`, `--template` (repo create) | `--org`, `--auto-init`, `--label-template`, `--trust-model`, `--default-branch`, `--as-template` |
 | `--inactive` (webhook) | `--active=false` |
 | `--out` (man) | `--output-file` / `-o` |
 
-Most other short flags were dropped; the long names are unchanged unless listed
+The long names are unchanged unless listed here. The short flags follow gh
-here. Two flags kept their name but changed meaning:
+instead of old tea: `-L` limit, `-s` state, `-l` label, `-a` assignee, `-A`
+author, `-m` milestone, `-t` title, `-b` body, `-F` body file, `-e` editor, `-w`
+web, `-S` search, plus the global `-R`, `-q` and `-y`. Some old shorthands now
+mean something else: `-L` is `--limit` (was `--labels`), and `-d` on `pr create`
+and `pr list` is `--draft` (was `--description`). Two flags kept their name but
+changed meaning:
 
 - `workflow run`: `-f` was `--follow` and now means `--field KEY=VALUE`;
   `--follow` has no shorthand. `-r` (`--ref`) and `-i` (`--input`) are unchanged.
 - `api`: `--field` (`-f`) sent a string and `--Field` (`-F`) a typed value. Now
   `--raw-field` / `-f` sends a string and `--field` / `-F` a typed value, so the
   shorthands behave as before. `--data` / `-d` became `--input FILE` (or `-` for
-  stdin), `--include` lost `-i`, and `--output` / `-o` became `--output-file`.
+  stdin), and `--output` / `-o` became `--output-file`.
 
 ## Changed positional arguments
 
 | Command | Old | tea 1.0 |
 |---|---|---|
-| `milestone close\|reopen\|delete\|edit\|view` | milestone name | milestone ID; add `--by-name` to select by exact title |
+| `milestone close\|reopen\|delete\|edit\|view` | milestone name | milestone title or ID |
-| `milestone issue list\|add\|remove` | milestone name | milestone ID; add `--by-name` to select by exact title |
+| `milestone issue list\|add\|remove` | milestone name | milestone title or ID |
-| `release asset delete <tag>` | attachment name | asset ID; add `--by-name` to select by exact name |
+| `release asset delete <tag>` | attachment name | asset name or ID |
-| `label edit\|delete` | `--id ID` | `ID` |
+| `label edit\|delete` | `--id ID` | label name or ID |
+| `team view\|edit\|delete`, `team member\|repo ...` | team ID | `ORG/TEAM` or team ID |
 | `repo delete` | `--name NAME --owner OWNER` | optional `OWNER/REPO` argument (or `--repo`) |
-| `issue comment create` | optional body argument | `--body`, `--body-file` or `--editor` |
+| `issue comment` | optional body argument | `--body`, `--body-file` or `--editor` |
 
-A milestone whose title is a number is now read as an ID unless you pass
+A number is read as an ID; pass `--by-name` to match a milestone, label or asset
-`--by-name`. Destructive commands still ask for confirmation unless `--yes` is
+whose name is a number. Destructive commands still ask for confirmation unless
-given.
+`--yes` is given.
 
 ## Output formats
 
 `--output` / `-o` (`table`, `simple`, `csv`, `tsv`, `yaml`, `json`) and `--fields`
-are gone. Human output is plain text; scripts should use JSON:
+are gone. Human output is text for people; scripts should use JSON:
 
 ```sh
 # old: tea issues list --fields index,title -o csv
 tea issue list --json number,title --jq '.[] | "\(.number),\(.title)"'
 
 # old: tea notifications --mine -o simple | xargs notify-send
-tea notification list --mine --json title --jq '.[].title' | xargs -n1 notify-send
+tea notification list -q '.[].title' | xargs -n1 notify-send
 ```
 
 `--json` alone prints every field; `--json a,b` selects fields and rejects unknown
-names; `--jq` filters the result. Commands that produce no resource, such as
+names; `--jq` / `-q` filters the result and implies `--json`. Commands that
-deletes, reject `--json` with a usage error instead of printing nothing.
+produce no resource, such as deletes, reject `--json` with a usage error instead
+of printing nothing. See `tea help formatting`.
 
-Lists print aligned columns without a header row and with fewer columns than
+Lists follow gh. On a terminal they print a "Showing 30 of 112 open issues in
-before: the ID or number first, then the title or name, then the state and a few
+alice/project" line, an uppercase header row and columns fitted to the terminal
-details (`issue list` and `pr list` show number, title, state and author). Do not
+width, with times relative ("about 3 hours ago"), states colored and the first
-parse them; the columns may change. On a color terminal the first column links to
+column linked to the web page (`tea config set hyperlinks never` turns the links
-the resource. Tabs and line breaks in list cells become spaces, and control
+off). An empty list prints a message on stderr and exits 0. When stdout is not a
-characters such as escape sequences are dropped from all human output, bodies
+terminal, lists print tab-separated values without header, color or links, with
-included. Commands that change several resources at once, such as
+times in RFC 3339 UTC and stable columns, so `cut -f1` works; a `--page` hint
-`issue close 1 2`, `issue edit`, `milestone close`, `release edit` or
+goes to stderr when more results follow. Still prefer `--json` in scripts: the
-`notification mark-read`, print one table of the changed items in the matching
+columns may change. Tabs and line breaks in list cells become spaces, and
-list's columns. When a list continues past the requested page, tea prints a
+control characters such as escape sequences are dropped from all human output,
-`--page` hint on stderr.
+bodies included.
 
-Issue, pull request and other bodies are printed as raw Markdown instead of being
+Commands that change resources report each change on stderr, such as
-rendered. Long output on a terminal goes through a pager (`TEA_PAGER`, the
+`✓ Closed issue alice/project#5 (Fix login)` or `! … is already closed`, only
-`pager` preference or `PAGER`). Each command starts the pager at most once.
+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.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | success, including an empty list |
+| 1 | the command failed |
+| 2 | usage error: an unknown command or flag, or a missing or invalid argument |
+| 3 | canceled: a declined confirmation, an aborted prompt or a timeout |
+| 4 | authentication is missing or was rejected |
+| 8 | `tea pr checks`: some checks are still pending |
+| 130 | interrupted with Ctrl-C |
+
+`tea help exit-codes` prints this table.
 
 ## Removed features
 
@@ -304,7 +341,6 @@ rendered. Long output on a terminal goes through a pager (`TEA_PAGER`, the
 | Basic-auth token creation (`login add --user/--password/--otp/--scopes`) | create a token in the web UI, or `tea auth login --oauth` |
 | `login edit` | `tea config set --host URL <key> <value>` |
 | Output formats and `--fields` | `--json` and `--jq` |
-| Markdown rendering of bodies | raw Markdown, optionally paged |
 | `contrib/autocomplete.*` scripts and the `--generate-shell-completion` protocol | `tea completion <shell>` |
 | `GH_TOKEN`, `GITEA_SERVER_*`, `GITEA_SCOPES` | `GITEA_TOKEN`, `tea auth login` |
 | `--vvv` | `--debug` |
@@ -316,22 +352,37 @@ Completion scripts saved from an older `tea completion` (or the removed
 tea 1.0 rejects, so completion silently stops working. Regenerate them:
 
 ```sh
-source <(tea completion bash)          # ~/.bashrc
+eval "$(tea completion bash)"                                  # ~/.bashrc
-source <(tea completion zsh)           # ~/.zshrc
+autoload -U compinit && compinit; source <(tea completion zsh)  # ~/.zshrc
 tea completion fish > ~/.config/fish/completions/tea.fish
-tea completion powershell | Out-String | Invoke-Expression   # PowerShell profile
+tea completion powershell | Out-String | Invoke-Expression      # PowerShell profile
 ```
 
+`tea completion <shell> --help` explains the requirements of each shell and how
+to install the script system-wide.
+
 Packagers can ship the pre-generated scripts and man pages from the release docs
 archive, or run `make docs`.
 
 ## Behavior changes
 
-- `pr checkout N` creates or reuses the local branch `pr/N`; it no longer
+- `pr checkout N` (alias `co`) checks out a local branch named after the PR's
-  switches to another local branch that already points at the PR head. Use
+  head branch when that name is free or already points at the head; otherwise
-  `--branch NAME` to check out into a branch you choose (it must point at the PR
+  it uses `OWNER/BRANCH` for a fork or `pr/N`. The branch tracks the head
-  head; `--update` fast-forwards it) or `--detach` for a detached checkout.
+  branch, so `git push` updates the pull request. Use `--branch NAME` (`-b`) to
-  `-b` now takes the branch name.
+  choose the name, `--update` to fast-forward an existing branch, or `--detach`
+  for a detached checkout.
+- `pr review` takes the review type as `--approve` / `-a`, `--request-changes` /
+  `-r` or `--comment` / `-c`; on a terminal, leaving it out starts an
+  interactive review.
+- `notification` commands act on your whole inbox by default (the old
+  `--mine`). `-R OWNER/REPO` or `--this-repo` limits them to one repository.
+- `config get KEY` prints only the value; `--show-source` adds where it comes
+  from.
+- `auth status` groups accounts by instance, marks each as usable or not, and
+  reports whether the Git credential helper is configured. It exits with 4 when
+  there is no account or a credential is missing or rejected. `auth token`
+  prints the token of the active account for scripts.
 - `webhook edit` must be told what to do with the delivery authorization header
   on every call, because Gitea replaces it: pass `--authorization-header`,
   `--authorization-header-file` or `--clear-authorization`. The signing secret
@@ -340,9 +391,11 @@ archive, or run `make docs`.
   pass `--all` to apply them to every notification matching the filters.
 - `--no-input` disables prompts, editors and browsers. With `--json`, tea never
   prompts unless `--interactive` is given; required values must come from flags.
-- Destructive commands confirm on a terminal and need `--yes` elsewhere.
+- Destructive commands and `pr merge` confirm on a terminal and need `--yes`
-- `--limit` accepts 1 to 100 and `--page` a positive number; other values are
+  (`-y`) elsewhere; the help of each such command lists `--yes`.
-  usage errors instead of being passed to the server.
+- `--limit` (`-L`) accepts 1 to 1000 and `--page` a positive number; other
+  values are usage errors instead of being passed to the server. tea pages
+  through the server's smaller pages to reach the limit.
 - In `--json` output, timestamps the server leaves unset print as `""`, or as
   `null` for optional fields such as deadlines, instead of
   `0001-01-01T00:00:00Z`.