docs: add the gt guides

Signed-off-by: bircni <[email protected]>

cli-docs/scripting.md

@@ -0,0 +1,102 @@
+---
+sidebar_position: 5
+---
+
+# Output and scripting
+
+gt prints text for people by default. Scripts should read JSON instead: the columns and
+wording of the text output may change between releases.
+
+## JSON
+
+`--json` prints every field of the result, `--json FIELDS` only the comma-separated
+fields you list:
+
+```bash
+gt issue list --json
+gt pr view 123 --json number,title,state
+```
+
+The **JSON FIELDS** section of a command's `--help` lists its fields, and shell completion
+offers them after `--json`. An unknown field reports the available ones. Commands that
+return no resource, such as deletes, reject `--json`.
+
+`--jq` (`-q`) filters the JSON with a [jq](https://jqlang.org) expression and implies
+`--json`. It runs inside gt, so jq does not need to be installed. String results print
+without quotes:
+
+```bash
+gt issue list --json number,title --jq '.[] | "\(.number)\t\(.title)"'
+```
+
+Some fields cost extra requests, such as the reviewers of `gt pr list`. gt makes them only
+when the output includes the field: `--json` names it, or `--json` selects every field and
+the `--jq` expression names it. An expression that reaches such a field without naming it,
+as `to_entries` does, sees it empty; name the field in `--json` instead.
+
+On a terminal, JSON is indented and colored; otherwise each value prints on one line. gt
+does not prompt while it prints JSON; `--interactive` allows prompts anyway.
+`gt help formatting` describes all of this.
+
+## Piped output
+
+JSON and other results go to stdout. Diagnostics, prompts and the messages that confirm a
+change go to stderr, so they never end up in the data a script reads.
+
+Piped or redirected, lists print as tab-separated values without a header row, ready for
+`cut` or `awk`:
+
+```bash
+gt issue list --kind all --milestone v1.0 | cut -f1,2
+```
+
+Color settings never color piped output. Only a command's own `--color always` does, such
+as `gt pr diff --color always`.
+
+## 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, a prompt left with Esc or Ctrl-D, or a timeout |
+| 4 | Authentication is missing or was rejected |
+| 8 | `gt pr checks`: some checks are still pending |
+| 130 | Interrupted with Ctrl-C, also at a prompt |
+
+A command may document further codes in its help. `gt auth status`, for example, exits
+with 4 when there is no account or a credential is missing or rejected; with `--json` it
+exits with 0 either way and reports the problem in its output.
+
+## The API
+
+`gt api` sends an authenticated request to the instance's API, for what no command covers
+yet. The endpoint is a path under `/api/v1`, and `{owner}` and `{repo}` take the current
+repository:
+
+```bash
+gt api user --jq .login
+gt api repos/{owner}/{repo}/issues -f title="Crash on start" -F labels='[3]'
+gt api user/repos --paginate --jq '.[].full_name'
+```
+
+A response outside 2xx prints its body, then fails. `gt auth token` prints the token gt
+uses, for tools that call the API themselves.
+
+## Aliases
+
+An alias is a shortcut that expands to a gt command with its arguments:
+
+```bash
+# gt il runs gt issue list --label bug
+gt alias set il "issue list --label bug"
+# $1 takes the first argument: gt review 13 runs gt pr review 13 --approve
+gt alias set review 'pr review $1 --approve'
+```
+
+`$1`, `$2` and so on take the arguments in that position; other arguments follow the
+expansion, so `gt il --state all` runs `gt issue list --label bug --state all`. Aliases never
+run a shell, and a built-in command always wins over an alias of the same name.
+`--clobber` replaces an existing alias, `gt alias list` lists them and `gt alias delete`
+removes one. They are kept in `config.yml`.