docs: add the gt guides

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

.gitea/workflows/update_cli_reference.yaml

@@ -0,0 +1,114 @@
+name: update cli reference
+
+on:
+  schedule:
+    - cron: '45 3 * * 1' # every Monday at 03:45
+  workflow_dispatch:
+
+env:
+  # main is protected, so the update is proposed as a pull request from this branch
+  BOT_BRANCH: bot/update-cli-reference
+  BASE_BRANCH: main
+  # the develop cli docs follow the main branch of gitea/cli, every documented
+  # release series follows its newest stable tag. The value is used unquoted, so
+  # the glob is expanded by the shell of each step, which drops it with nullglob
+  # as long as no series is documented.
+  TARGET_DIRS: cli-docs/reference cli-docs_versioned_docs/version-*/reference
+
+jobs:
+  update-cli-reference:
+    if: github.repository == 'gitea/docs'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          ref: main
+          # pushing uses DEPLOY_TOKEN, keep the ephemeral job token out of .git/config
+          persist-credentials: false
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
+        with:
+          go-version: 'stable'
+          cache: false
+      - name: regenerate the cli reference pages
+        run: |
+          set -euo pipefail
+          ./update_cli_docs.sh main cli-docs/reference
+          ./update_cli_docs.sh --released
+      - name: verify the generated files
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+          # the pages are generated from gt's command tree, so a broken
+          # generator would silently drop pages or leave them almost empty
+          for dir in $TARGET_DIRS; do
+            echo "checking $dir"
+            grep -q '^gt \[flags\]' "$dir/index.md"
+            grep -q '^gt issue create \[flags\]' "$dir/issue/create.md"
+            grep -q -- '--no-input' "$dir/help/environment.md"
+            test "$(find "$dir" -name '*.md' | wc -l)" -gt 100
+          done
+      - name: push bot branch
+        id: bot_branch
+        env:
+          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+
+          # git status also sees the pages of a new command, which git diff does not
+          if [ -z "$(git status --porcelain -- $TARGET_DIRS)" ]; then
+            echo "the cli reference is already up to date"
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          if [ -z "$DEPLOY_TOKEN" ]; then
+            echo "secrets.DEPLOY_TOKEN is missing, cannot push the update"
+            exit 1
+          fi
+          remote="https://x-access-token:$DEPLOY_TOKEN@${GITHUB_SERVER_URL#*://}/$GITHUB_REPOSITORY.git"
+
+          # skip if an open bot branch already carries exactly these files
+          if git fetch --quiet --depth=1 "$remote" "refs/heads/$BOT_BRANCH" 2>/dev/null; then
+            if git diff --quiet FETCH_HEAD -- $TARGET_DIRS; then
+              echo "$BOT_BRANCH already proposes this cli reference"
+              echo "changed=false" >> "$GITHUB_OUTPUT"
+              exit 0
+            fi
+          fi
+
+          git config user.name "Gitea Bot"
+          git config user.email "[email protected]"
+          git switch --create "$BOT_BRANCH"
+          git add --all -- $TARGET_DIRS
+          git commit -m "Update the cli reference pages"
+          # force push: the branch is always rebuilt on top of the current main
+          git push --force "$remote" "HEAD:refs/heads/$BOT_BRANCH"
+          echo "changed=true" >> "$GITHUB_OUTPUT"
+      - name: create pull request
+        if: steps.bot_branch.outputs.changed == 'true'
+        env:
+          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          cat > pull.json <<EOF
+          {
+            "base": "$BASE_BRANCH",
+            "head": "$BOT_BRANCH",
+            "title": "Update the cli reference pages",
+            "body": "Automated update of the generated gt reference pages from gitea/cli (main for the develop docs, the newest stable tag for every documented series), opened by the \"update cli reference\" scheduled workflow."
+          }
+          EOF
+
+          code="$(curl --silent --show-error --output pull-response.json --write-out '%{http_code}' \
+            -X POST "${GITHUB_API_URL:-$GITHUB_SERVER_URL/api/v1}/repos/$GITHUB_REPOSITORY/pulls" \
+            -H "Authorization: token $DEPLOY_TOKEN" \
+            -H 'Content-Type: application/json' \
+            --data @pull.json)"
+
+          case "$code" in
+            201) echo "pull request created" ;;
+            409) echo "an open pull request for $BOT_BRANCH already exists, it now points at the new commit" ;;
+            *) echo "unexpected response $code:"; cat pull-response.json; exit 1 ;;
+          esac

Makefile

@@ -92,7 +92,18 @@ update-runner-docs:
 update-runner-docs-released:
 	./update_runner_docs.sh --released
 
-# freezes the current docs or runner tree as a new version, see
+# regenerate the generated gt reference pages of the develop docs from the main
+# branch of gitea/cli (used by the update cli reference cron job)
+.PHONY: update-cli-docs
+update-cli-docs:
+	./update_cli_docs.sh main cli-docs/reference
+
+# same, for every documented release series; succeeds without any
+.PHONY: update-cli-docs-released
+update-cli-docs-released:
+	./update_cli_docs.sh --released
+
+# freezes the current docs, runner or cli tree as a new version, see
 # scripts/cut-version.mjs
 .PHONY: cut-version
 cut-version:

README.md

@@ -3,13 +3,14 @@
 The sources of [docs.gitea.com](https://docs.gitea.com), built with
 [Astro](https://astro.build) and [Starlight](https://starlight.astro.build).
 
-The site covers three products, all served from this repository:
+The site covers four products, all served from this repository:
 
 | Product | Content | Versions | Languages |
 | --- | --- | --- | --- |
 | Docs | `docs/`, `versioned_docs/`, `i18n/` | next, 28, 1.27 … 1.22 | English, 简体中文, 繁體中文 |
 | API | `static/swagger-*.json`, `static/openapi3-*.json` | next, 28, 1.27 … 1.22 | English |
 | Runner | `runner-docs/`, `runner-docs_versioned_docs/` | develop, 5 … 0 | English |
+| CLI | `cli-docs/`, `cli-docs_versioned_docs/` | develop | English |
 
 The enterprise documentation is built and deployed from its own repository and
 reached through `/enterprise/`, which a Cloudflare worker maintained elsewhere
@@ -53,6 +54,7 @@ group from the `_category_.json` of its directory.
 ```shell
 make cut-version PRODUCT=docs VERSION=1.28
 make cut-version PRODUCT=runner VERSION=6
+make cut-version PRODUCT=cli VERSION=0.1
 ```
 
 This freezes the current tree, its translations and its sidebar. The label of
@@ -115,6 +117,37 @@ workflow runs weekly and opens a pull request whenever the runner's CLI or
 example configuration changed. Generating them needs Go, since the script builds
 the runner binary.
 
+## CLI docs
+
+The documentation of `gt`, the Gitea CLI from
+[gitea/cli](https://gitea.com/gitea/cli), is laid out like the runner docs:
+
+| Version | Content | URL |
+| --- | --- | --- |
+| develop | `cli-docs/` | `/cli/` until the first release, then `/cli/develop/` |
+| current series | `cli-docs_versioned_docs/version-<series>/` | `/cli/` |
+| older series | `cli-docs_versioned_docs/version-<series>/` | `/cli/<series>/` |
+
+No series is documented yet. Once a release exists, cut its series with
+`make cut-version PRODUCT=cli VERSION=0.1`, then list it in `cliSeries` in
+`packages/content-loader/src/products.ts`; the develop docs then move to
+`/cli/develop/`. Its sidebar is written by hand in `cli-sidebars.js`, apart from
+the reference, which is laid out from its directory tree.
+
+The pages under `reference/` are generated with gt's own generator
+(`go run ./tools/cli-docs`), one page per command and help topic, with a command
+that has subcommands turned into a directory:
+
+```shell
+make update-cli-docs           # develop docs, from the main branch of gitea/cli
+make update-cli-docs-released  # every series, from its newest stable tag
+./update_cli_docs.sh v0.1.0 cli-docs_versioned_docs/version-0.1/reference
+```
+
+`CLI_REMOTE` points the script at another clone, such as a local checkout. The
+`update cli reference` workflow refreshes the pages weekly, like the runner's.
+Generating them needs Go.
+
 ## Deployment
 
 `main` is built and published by the `Build and Publish Docs site` workflow, to

cli-docs/authentication.md

@@ -0,0 +1,182 @@
+---
+sidebar_position: 3
+---
+
+# Logging in
+
+`gt auth login` logs in to a Gitea instance. gt can authenticate in three ways:
+
+| Method | Flag | Best for |
+| --- | --- | --- |
+| OAuth in a web browser | `--oauth` | Interactive use, instances with single sign-on or two-factor authentication |
+| Access token | `--with-token` | Any instance, machines without a browser |
+| SSH key signing | `--ssh-key`, `--ssh-agent-key`, `--ssh-agent-principal` | Using an SSH key you already have instead of a token |
+
+gt never asks for your password. On a terminal, `gt auth login` without a method flag asks
+for the instance, how to log in, where to keep the token, and whether Git should use gt
+for the instance:
+
+```bash
+gt auth login
+```
+
+## OAuth
+
+```bash
+gt auth login --host https://gitea.example.com --oauth
+```
+
+gt opens the instance's authorization page in your browser, or prints its URL when no
+browser opens. You sign in there as you do on the web, so single sign-on through an
+external identity provider and two-factor authentication work unchanged. gt listens on
+`127.0.0.1` for the answer, so the browser has to run on the same machine as gt. OAuth
+needs this interaction and is refused with `--no-input`.
+
+By default the token has write access to everything but administration. `--scopes`
+requests fewer, using the [token scope](/development/oauth2-provider#scopes) names:
+
+```bash
+gt auth login --host https://gitea.example.com --oauth --scopes read:repository,read:user
+```
+
+gt refreshes an expiring OAuth token on its own. `gt auth refresh` refreshes it now.
+
+gt uses the OAuth application that Gitea registers by default for its command line
+client, listed as `tea` in [`DEFAULT_APPLICATIONS`](/administration/config-cheat-sheet#oauth2-oauth2).
+If an administrator turned it off, register an OAuth2 application that is not a
+confidential client, with the redirect URI `http://127.0.0.1`, and pass its client ID with
+`--client-id`. gt remembers the ID for the instance.
+
+## Access tokens
+
+1. Sign in to the instance in a web browser, with single sign-on or two-factor
+   authentication if the instance uses them.
+2. Under **Settings > Applications**, create an access token with the scopes you need.
+3. Save the token in a private file and log in with it:
+
+   ```bash
+   gt auth login --host https://gitea.example.com --with-token < token.txt
+   ```
+
+   On a terminal, `--with-token` without input asks for the token instead.
+
+gt needs `read:user` to find out which account a token belongs to. Add the scopes of the
+commands you use:
+
+| Scope | Commands |
+| --- | --- |
+| `repository` | `repo`, `pr`, `release`, `branch`, `run`, `workflow`, `secret` and `variable` of a repository, `webhook`, `wiki` |
+| `issue` | `issue`, `label`, `milestone`, `time`, and comments on pull requests |
+| `organization` | `org`, `team`, and `secret`, `variable` and `webhook` with `--org` |
+| `notification` | `notification` |
+| `package` | `package` |
+| `user` | `ssh-key`, and `secret` and `variable` with `--account` |
+| `admin` | `admin` |
+
+Choose `write:` for the commands that change something, `read:` for the ones that only
+read. Gitea counts pull request comments, labels and milestones as issue operations, so
+working with pull requests usually needs both `write:repository` and `write:issue`. The
+[scopes table](/development/oauth2-provider#scopes) describes each scope.
+
+A token pasted with `--with-token` cannot be refreshed. When it expires or is revoked, log
+in again.
+
+## Where credentials are kept
+
+gt keeps the instances and accounts in `hosts.yml` and its preferences in `config.yml`, in
+its configuration directory. `gt config path` prints both files; `GITEA_CLI_CONFIG_DIR`
+moves the directory.
+
+Tokens are not written to these files. `--credential-store` chooses where they go:
+
+- `keyring` (default): the system keyring, such as the macOS Keychain, the Windows
+  Credential Manager, or the Secret Service on Linux. When no keyring is available, the
+  login fails rather than falling back to a file.
+- `file`: a `credentials` directory in the configuration directory that only your user
+  can read. Use it where no keyring exists, such as in a container or over SSH.
+
+A token given in `GITEA_TOKEN` is never stored. See [Using gt in CI](ci.md).
+
+`gt auth status` shows the accounts on each instance, the active one, and how each
+authenticates; `gt auth status --verify` checks every credential against its instance.
+`gt auth token` prints the token of the active account, for scripts that call the API
+themselves. `gt auth logout` forgets an account and deletes its stored credential.
+
+## SSH keys
+
+Instead of a token, gt can sign each API request with an SSH key that is registered for
+your account on the instance:
+
+```bash
+gt auth login --host https://gitea.example.com --ssh-key ~/.ssh/id_ed25519
+```
+
+When a certificate (`id_ed25519-cert.pub`) is next to the key, gt signs with the
+certificate. gt asks for the passphrase of an encrypted key. To sign with a key held by
+`ssh-agent`, pass its fingerprint with `--ssh-agent-key`; to sign with an agent
+certificate, pass its principal with `--ssh-agent-principal`. Accounts that sign requests
+have no token, so `gt auth token` has nothing to print for them.
+
+## Git over HTTPS
+
+gt's own clone and checkout commands authenticate without any setup. For `git push` and
+`git fetch` over HTTPS, let Git ask gt for credentials:
+
+```bash
+gt auth setup-git
+gt auth setup-git --host gitea.example.com
+# only for the current repository, always as alice
+gt auth setup-git --local --user alice
+```
+
+Git then uses the active account of the instance, or the account of `--user`. Other
+credential helpers, such as a system keychain, are turned off for the instance, since they
+would answer first and keep a copy of gt's token; `--keep-helpers` keeps them.
+`gt auth login` on a terminal offers to do this for you.
+
+## Several instances and accounts
+
+Run `gt auth login` once per instance and account. Commands pick the instance from the
+repository's Git remote, `--host`, `GITEA_CLI_HOST`, the `default_host` setting, or the only
+instance you are logged in to; `gt help environment` gives the full order.
+
+Each instance has one active account. `gt auth switch` changes it: with two accounts it
+toggles between them, with more it asks which one. `--user`, or `GITEA_CLI_USER`, uses
+another account for a single command:
+
+```bash
+gt auth switch bob --host gitea.example.com
+gt issue list --user alice
+```
+
+To use another instance by default outside a clone:
+
+```bash
+gt config set default_host https://gitea.example.com
+```
+
+## Access proxies and client certificates
+
+An instance behind an access proxy may need extra headers or a TLS client certificate.
+`--header` sends a header with every request to the instance; a value of `$NAME` or
+`${NAME}` is read from that environment variable each time, so the secret stays out of
+gt's files:
+
+```bash
+gt auth login --host https://gitea.example.com --with-token \
+  --header 'CF-Access-Client-Id: $CF_ID' \
+  --header 'CF-Access-Client-Secret: $CF_SECRET' < token.txt
+```
+
+`--client-cert` presents a PEM client certificate, and `--client-key` names its
+unencrypted PEM key when the key is not in the certificate file. Convert a PKCS#12 file
+with:
+
+```bash
+openssl pkcs12 -in cert.p12 -clcerts -nokeys -out cert.pem
+openssl pkcs12 -in cert.p12 -nocerts -nodes -out key.pem
+```
+
+gt keeps these per instance; `gt config set headers`, `client_cert` and `client_key` with
+`--host` change them later. `--insecure` skips TLS certificate verification for an
+instance, for testing only.

cli-docs/ci.md

@@ -0,0 +1,92 @@
+---
+sidebar_position: 4
+---
+
+# Using gt in CI
+
+In CI there is nobody to log in, answer a prompt or confirm a deletion. Give gt a token and
+an instance through the environment, select the repository explicitly, and turn prompts off.
+
+## Environment
+
+| Variable | Description |
+| --- | --- |
+| `GITEA_TOKEN` | Access token, used instead of stored credentials |
+| `GITEA_CLI_HOST` or `GITEA_INSTANCE_URL` | URL of the instance the token belongs to |
+| `GITEA_CLI_REPO` | Repository as `OWNER/REPO` or URL, like `--repo` |
+| `GITEA_INSTANCE_INSECURE` | With `GITEA_TOKEN`, skip TLS verification when `true` |
+| `GITEA_INSTANCE_SSH_HOST` | With `GITEA_TOKEN`, the SSH host that identifies the instance's remotes |
+
+gt never stores a token it reads from `GITEA_TOKEN`, so nothing has to be cleaned up after
+the job. Keep the token in your CI system's secrets; never write it into `config.yml` or
+`hosts.yml`. Create it as described in [Logging in](authentication.md#access-tokens), with
+only the scopes the job needs.
+
+`gt help environment` lists every variable gt reads.
+
+## Prompts and confirmations
+
+`--no-input` disables prompts and the editor and browser that some commands open on their
+own. A command that would need to ask for something fails instead, with exit code 2.
+Commands that change or delete something ask for confirmation; `--yes` (`-y`) gives it in
+advance:
+
+```bash
+gt pr merge 123 --repo owner/repository --rebase --yes --no-input
+```
+
+`gt auth login --oauth` needs a browser and does not work in CI. To store a token on a
+machine that runs jobs, pipe it in instead:
+
+```bash
+gt auth login --host https://gitea.example.com --with-token --credential-store file < token.txt
+```
+
+## Gitea Actions
+
+Gitea does not allow secret names starting with `GITEA_`, so store the token under
+another name, such as `GT_TOKEN`, and pass it to gt as `GITEA_TOKEN`:
+
+```yaml
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    env:
+      GITEA_TOKEN: ${{ secrets.GT_TOKEN }}
+      GITEA_CLI_HOST: ${{ gitea.server_url }}
+      GITEA_CLI_REPO: ${{ gitea.repository }}
+    steps:
+      - name: install gt
+        run: curl -fsSL https://gitea.com/gitea/cli/raw/branch/main/scripts/install.sh | sh
+      - name: deploy to staging
+        run: gt workflow run deploy.yml --ref main --field env=staging --field version=1.2.3 --no-input
+```
+
+## Workflows and runs
+
+```bash
+gt workflow list --no-input --json
+gt workflow view deploy.yml --no-input --json
+gt workflow run deploy.yml --ref main --field env=staging --field version=1.2.3 --no-input
+gt workflow disable deploy.yml --yes --no-input
+gt workflow enable deploy.yml --no-input
+```
+
+`gt workflow run` dispatches a workflow, which needs a `workflow_dispatch` trigger. To wait
+for the run, add `--follow`, or find it with `gt run list` and watch it:
+
+```bash
+gt run watch RUN_ID --timeout 10m --no-input
+```
+
+Both fail when the run completes without success, so the job fails with it.
+
+`gt pr checks` waits for the checks of a pull request with `--watch`, and exits with 8
+while checks are still pending:
+
+```bash
+gt pr checks 13 --watch && gt pr merge 13 --yes --no-input
+```
+
+See [Output and scripting](scripting.md) for reading the results of a command, and for the
+exit codes.

cli-docs/index.md

@@ -0,0 +1,62 @@
+---
+sidebar_position: 1
+slug: /
+---
+
+# Gitea CLI
+
+[gt](https://gitea.com/gitea/cli) is the official command line client for Gitea.
+It works with repositories, issues, pull requests, releases, Actions workflows and runs,
+packages, and the other resources of a Gitea instance, from a terminal or from a script.
+
+:::info Development version
+These pages describe builds from the `main` branch of gitea/cli, published as `nightly`
+binaries and images.
+:::
+
+## Requirements
+
+- Gitea 28 or later. gt does not support older instances.
+- Git on the `PATH`, for the commands that clone, check out or push, such as
+  `gt repo clone` and `gt pr checkout`.
+
+## Getting started
+
+1. [Install gt](installation.md).
+2. [Log in](authentication.md) to your Gitea instance:
+
+   ```bash
+   gt auth login
+   ```
+
+3. Run commands from a clone of a repository on that instance. gt finds the repository
+   and the instance from the Git remotes:
+
+   ```bash
+   gt issue list --label bug
+   gt pr checkout 13
+   gt pr checks --watch
+   ```
+
+   Outside a clone, select the repository with `--repo` (`-R`), as `OWNER/REPO` or as a URL:
+
+   ```bash
+   gt issue view 42 --repo gitea.com/gitea/cli
+   ```
+
+`gt doctor` checks the setup that commands in the current directory use: the settings
+files, the instance, the account and its credential, the repository, and Git. Each
+problem it reports comes with the command that fixes it.
+
+## Commands
+
+Commands are a noun followed by a verb, such as `gt issue list` or `gt pr create`.
+Every command has a `--help` page, which is also part of the
+[command reference](reference/index.md). Besides the commands, gt has three help topics:
+
+- `gt help environment`: global flags, environment variables, and how gt selects the
+  instance and the repository
+- `gt help formatting`: JSON output with `--json` and `--jq`
+- `gt help exit-codes`: the exit codes
+
+For scripts and CI, read [Using gt in CI](ci.md) and [Output and scripting](scripting.md).

cli-docs/installation.md

@@ -0,0 +1,131 @@
+---
+sidebar_position: 2
+---
+
+# Installation
+
+gt is a single binary, built for Linux, macOS, Windows, and FreeBSD.
+
+## Install script
+
+The install script downloads the binary for your system from
+[dl.gitea.com](https://dl.gitea.com/gitea-cli/), verifies its SHA-256 checksum and installs
+it as `gt`.
+
+On Linux, macOS or FreeBSD:
+
+```bash
+curl -fsSL https://gitea.com/gitea/cli/raw/branch/main/scripts/install.sh | sh
+```
+
+It installs into `/usr/local/bin` when that directory is writable, else into `~/.local/bin`.
+
+On Windows, in PowerShell:
+
+```powershell
+irm https://gitea.com/gitea/cli/raw/branch/main/scripts/install.ps1 | iex
+```
+
+It installs `gt.exe` into `%LOCALAPPDATA%\Programs\gitea-cli` and adds that directory to
+your `PATH`.
+
+Both scripts read these environment variables:
+
+| Variable | Description |
+| --- | --- |
+| `GITEA_CLI_VERSION` | Version to install, such as `1.0.0`, or `nightly` for the latest build of the `main` branch. Default: the latest release. |
+| `GITEA_CLI_INSTALL_DIR` | Directory to install gt into. |
+
+`install.sh` also accepts `--nightly` and `--version VERSION`:
+
+```bash
+curl -fsSL https://gitea.com/gitea/cli/raw/branch/main/scripts/install.sh | sh -s -- --nightly
+```
+
+## Binaries
+
+Download releases from [dl.gitea.com/gitea-cli](https://dl.gitea.com/gitea-cli/). Builds of
+the `main` branch are in its [`main`](https://dl.gitea.com/gitea-cli/main/) directory. Each
+binary is available as is and compressed with xz, and has a matching `.sha256` checksum
+file:
+
+```bash
+VERSION=main
+curl -sSLO "https://dl.gitea.com/gitea-cli/$VERSION/gitea-cli-$VERSION-linux-amd64"
+curl -sSLO "https://dl.gitea.com/gitea-cli/$VERSION/gitea-cli-$VERSION-linux-amd64.sha256"
+sha256sum -c "gitea-cli-$VERSION-linux-amd64.sha256"
+sudo install -m 0755 "gitea-cli-$VERSION-linux-amd64" /usr/local/bin/gt
+```
+
+Each version also has a `gitea-cli-<version>-docs.tar.xz` archive with the command
+reference, the man pages and the shell completion scripts.
+
+## Docker
+
+The [`gitea/gitea-cli`](https://hub.docker.com/r/gitea/gitea-cli) image runs `gt` as its
+entry point. Releases are tagged with their version and `latest`, builds of the `main`
+branch with `nightly`.
+
+```bash
+docker run --rm -e GITEA_TOKEN -e GITEA_CLI_HOST=https://gitea.example.com \
+  gitea/gitea-cli issue list --repo owner/repo
+```
+
+A container has no system keyring, so pass a token in the environment as above (see
+[Using gt in CI](ci.md)). To keep the settings and a login between runs, mount a volume at
+`/app`, the home directory of the image, and log in with `--credential-store file`.
+
+## Go
+
+With Go 1.27 or later:
+
+```bash
+go install gitea.dev/cli/cmd/gt@latest
+```
+
+To build gt from a clone of [gitea/cli](https://gitea.com/gitea/cli), run `make`; it needs
+GNU Make.
+
+## Shell completion
+
+`gt completion <shell>` prints the completion script for bash, zsh, fish or PowerShell.
+Completion includes your aliases and, after `--json`, the JSON fields of a command. Add
+the line for your shell to its startup file:
+
+```bash
+# ~/.bashrc (on macOS, ~/.bash_profile); needs the bash-completion package
+eval "$(gt completion bash)"
+
+# ~/.zshrc, after compinit
+source <(gt completion zsh)
+
+# fish, once
+gt completion fish > ~/.config/fish/completions/gt.fish
+```
+
+In PowerShell, add this line to your profile:
+
+```powershell
+gt completion powershell | Out-String | Invoke-Expression
+```
+
+`gt completion <shell> --help` shows the details for each shell.
+
+## Man pages
+
+`gt man` prints gt's full manual, and `gt man <command>` the man page of one command, such
+as `gt man pr create`; `gt man` is not listed in `gt --help`. The man pages are also in the
+docs archive of each version.
+
+```bash
+# bash or zsh
+man <(gt man)
+
+# write it to a file
+gt man --output-file gt.1
+```
+
+## Upgrading
+
+Run the install script again, download the new binary, or pull the new image.
+`gt version` prints the version you run.

cli-docs/reference/admin/index.md

@@ -0,0 +1,48 @@
+---
+sidebar_position: 1
+description: "Manage instance administration"
+---
+
+# gt admin
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Manage instance administration
+
+## Synopsis
+
+```text
+Administer the Gitea instance. These commands need an administrator account.
+```
+
+```
+gt admin [flags]
+```
+
+## Options
+
+```
+  -h, --help   help for admin
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt](../index.md): Work with Gitea from your terminal
+* [gt admin user](../admin/user/index.md): Manage registered accounts

cli-docs/reference/admin/user/create.md

@@ -0,0 +1,67 @@
+---
+sidebar_position: 1
+description: "Create an account"
+---
+
+# gt admin user create
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Create an account
+
+## Synopsis
+
+```text
+Create an account. On a terminal, gt asks for a missing username, email address and
+password; the new account must change its password on its first sign-in unless
+--must-change-password=false is passed.
+```
+
+```
+gt admin user create [<username>] [flags]
+```
+
+## Examples
+
+```
+$ gt admin user create carol --email [email protected]
+# read the password from a file instead of a prompt
+$ gt admin user create ci-bot --email [email protected] --password-file pw.txt --must-change-password=false
+```
+
+## Options
+
+```
+      --admin                  Administrator privileges (use =false to revoke)
+      --email string           Email address
+      --full-name string       Display name
+  -h, --help                   help for create
+      --must-change-password   Require password change on next sign-in (use =false to disable) (default true)
+      --password string        Password (prefer --password-file)
+      --password-file string   Read password from file or - for stdin; remove one trailing line ending
+      --prohibit-login         Prohibit signing in (use =false to revoke)
+      --restricted             Restrict account access (use =false to revoke)
+      --username string        Account username
+      --visibility string      Profile visibility, by default the instance's default {public|limited|private}
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt admin user](../../admin/user/index.md): Manage registered accounts

cli-docs/reference/admin/user/delete.md

@@ -0,0 +1,57 @@
+---
+sidebar_position: 2
+description: "Delete an account"
+---
+
+# gt admin user delete
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Delete an account
+
+## Synopsis
+
+```text
+Delete an account. Gitea refuses while the user owns repositories or organizations, unless
+--purge deletes the account with everything it owns.
+```
+
+```
+gt admin user delete <username> [flags]
+```
+
+## Examples
+
+```
+$ gt admin user delete spammer
+# also delete the user's repositories, packages and organization memberships (and organizations they solely own)
+$ gt admin user delete spammer --purge
+```
+
+## Options
+
+```
+  -h, --help    help for delete
+      --purge   Also delete the user's repositories, packages, organization memberships and the organizations they solely own
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt admin user](../../admin/user/index.md): Manage registered accounts

cli-docs/reference/admin/user/edit.md

@@ -0,0 +1,68 @@
+---
+sidebar_position: 3
+description: "Edit an account"
+---
+
+# gt admin user edit
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Edit an account
+
+```
+gt admin user edit <username> [flags]
+```
+
+## Examples
+
+```
+$ gt admin user edit bob --full-name "Bob Builder" --restricted
+# reset a password and require a new one on the next sign-in
+$ gt admin user edit bob --password-file pw.txt --must-change-password
+# revoke administrator privileges
+$ gt admin user edit bob --admin=false
+```
+
+## Options
+
+```
+      --active                      Activate account (use =false to revoke)
+      --admin                       Administrator privileges (use =false to revoke)
+      --allow-create-organization   Allow creating organizations (use =false to revoke)
+      --allow-git-hook              Allow Git hooks (use =false to revoke)
+      --allow-import-local          Allow local repository imports (use =false to revoke)
+      --description string          Profile description
+      --email string                Email address
+      --full-name string            Display name
+  -h, --help                        help for edit
+      --location string             Location
+      --max-repo-creation int       Repository creation limit (-1 uses the instance default)
+      --must-change-password        Require password change on next sign-in (use =false to disable)
+      --password string             Password (prefer --password-file)
+      --password-file string        Read password from file or - for stdin; remove one trailing line ending
+      --prohibit-login              Prohibit signing in (use =false to revoke)
+      --restricted                  Restrict account access (use =false to revoke)
+      --visibility string           Profile visibility {public|limited|private}
+      --website string              Website URL
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt admin user](../../admin/user/index.md): Manage registered accounts

cli-docs/reference/admin/user/index.md

@@ -0,0 +1,53 @@
+---
+sidebar_position: 1
+description: "Manage registered accounts"
+---
+
+# gt admin user
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Manage registered accounts
+
+## Synopsis
+
+```text
+List, view, create, edit and delete the accounts of the instance. These commands need an
+administrator account.
+```
+
+```
+gt admin user [flags]
+```
+
+## Options
+
+```
+  -h, --help   help for user
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt admin](../../admin/index.md): Manage instance administration
+* [gt admin user create](../../admin/user/create.md): Create an account
+* [gt admin user delete](../../admin/user/delete.md): Delete an account
+* [gt admin user edit](../../admin/user/edit.md): Edit an account
+* [gt admin user list](../../admin/user/list.md): List registered accounts
+* [gt admin user view](../../admin/user/view.md): View an account

cli-docs/reference/admin/user/list.md

@@ -0,0 +1,54 @@
+---
+sidebar_position: 4
+description: "List registered accounts"
+---
+
+# gt admin user list
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+List registered accounts
+
+```
+gt admin user list [flags]
+```
+
+## Examples
+
+```
+$ gt admin user list
+# find accounts by username, name or email
+$ gt admin user list --query bob
+# print the email addresses
+$ gt admin user list --jq '.[].email'
+```
+
+## Options
+
+```
+  -h, --help           help for list
+  -L, --limit int      Maximum number of results (1..1000) (default 30)
+      --page int       Result page (default 1)
+      --query string   Only list accounts whose username, name or email contains this text
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt admin user](../../admin/user/index.md): Manage registered accounts

cli-docs/reference/admin/user/view.md

@@ -0,0 +1,48 @@
+---
+sidebar_position: 5
+description: "View an account"
+---
+
+# gt admin user view
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+View an account
+
+```
+gt admin user view <username> [flags]
+```
+
+## Examples
+
+```
+$ gt admin user view bob
+$ gt admin user view bob --json email,admin
+```
+
+## Options
+
+```
+  -h, --help   help for view
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt admin user](../../admin/user/index.md): Manage registered accounts

cli-docs/reference/alias/delete.md

@@ -0,0 +1,50 @@
+---
+sidebar_position: 1
+description: "Delete shortcuts"
+---
+
+# gt alias delete
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Delete shortcuts
+
+```
+gt alias delete [<name>...] [flags]
+```
+
+## Examples
+
+```
+$ gt alias delete il
+$ gt alias delete il review
+$ gt alias delete --all
+```
+
+## Options
+
+```
+      --all    Delete every alias
+  -h, --help   help for delete
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt alias](../alias/index.md): Create shortcuts for gt commands

cli-docs/reference/alias/index.md

@@ -0,0 +1,56 @@
+---
+sidebar_position: 2
+description: "Create shortcuts for gt commands"
+---
+
+# gt alias
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Create shortcuts for gt commands
+
+## Synopsis
+
+```text
+Create shortcuts for gt commands.
+
+An alias expands to a gt command with its arguments before gt runs it: after
+gt alias set il "issue list --label bug", gt il --state all runs
+gt issue list --label bug --state all. $1, $2 and so on in the expansion take the
+arguments in that position; other arguments follow the expansion. Aliases never run a
+shell, and built-in commands always win over an alias of the same name.
+```
+
+```
+gt alias [flags]
+```
+
+## Options
+
+```
+  -h, --help   help for alias
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt](../index.md): Work with Gitea from your terminal
+* [gt alias delete](../alias/delete.md): Delete shortcuts
+* [gt alias list](../alias/list.md): List shortcuts
+* [gt alias set](../alias/set.md): Create a shortcut for a gt command

cli-docs/reference/alias/list.md

@@ -0,0 +1,49 @@
+---
+sidebar_position: 2
+description: "List shortcuts"
+---
+
+# gt alias list
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+List shortcuts
+
+```
+gt alias list [flags]
+```
+
+## Examples
+
+```
+$ gt alias list
+# Print the expansion of one alias
+$ gt alias list --jq .il
+```
+
+## Options
+
+```
+  -h, --help   help for list
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt alias](../alias/index.md): Create shortcuts for gt commands

cli-docs/reference/alias/set.md

@@ -0,0 +1,53 @@
+---
+sidebar_position: 3
+description: "Create a shortcut for a gt command"
+---
+
+# gt alias set
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Create a shortcut for a gt command
+
+```
+gt alias set <name> <expansion> [flags]
+```
+
+## Examples
+
+```
+# 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'
+# Replace an existing alias
+$ gt alias set il "issue list --assignee @me" --clobber
+```
+
+## Options
+
+```
+      --clobber   Replace an existing alias of the same name
+  -h, --help      help for set
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt alias](../alias/index.md): Create shortcuts for gt commands

cli-docs/reference/api.md

@@ -0,0 +1,88 @@
+---
+sidebar_position: 3
+description: "Make an authenticated Gitea API request"
+---
+
+# gt api
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Make an authenticated Gitea API request
+
+## Synopsis
+
+```text
+Make an authenticated request to the Gitea API of the selected instance and print
+the response.
+
+The endpoint is a path under /api/v1, such as repos/{owner}/{repo}/issues, or a URL of
+the instance's API. The placeholders {owner} and {repo} take the repository of the
+current directory or --repo, and {branch} the checked-out Git branch.
+
+The method is GET, or POST when fields or --input supply a request body; -X selects
+another. Fields become query parameters of GET and HEAD requests and a JSON body
+otherwise:
+
+  -f, --raw-field name=value   a string value
+  -F, --field name=value       a typed value: true, false, null, numbers, arrays and
+                               objects are JSON, @FILE reads a file and @- stdin
+
+--paginate follows the next-page links of a GET request, or asks for the next page of
+a list that Gitea counts in X-Total-Count without links, and prints every page on its
+own line. --jq filters each JSON response with a jq expression and prints strings
+without quotes; jq does not need to be installed.
+
+On a terminal, JSON responses are indented and colored. A response outside 2xx prints
+its body, then fails with the HTTP status.
+```
+
+```
+gt api <endpoint> [flags]
+```
+
+## Examples
+
+```
+$ gt api user --jq .login
+# Create an issue: -f sends strings, -F typed values
+$ gt api repos/{owner}/{repo}/issues -f title="Crash on start" -F labels='[3]'
+$ gt api user/repos --paginate --jq '.[].full_name'
+```
+
+## Options
+
+```
+  -F, --field key=value       Add a typed parameter in key=value format; @FILE or @- reads a file or stdin
+  -H, --header name:value     Add an HTTP request header in name:value format
+  -h, --help                  help for api
+  -i, --include               Print the response status and headers to stderr
+      --input file            Read the request body from a file, or stdin with -
+      --max-pages int         Stop --paginate after this many pages; reaching the default fails (default 1000)
+  -X, --method method         HTTP method (default "GET")
+      --output-file file      Write the complete response to a new file
+      --paginate              Follow next-page links and print every page
+  -f, --raw-field key=value   Add a string parameter in key=value format
+      --silent                Do not print the response body
+      --verbose               Print the request and the response status and headers to stderr
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt](index.md): Work with Gitea from your terminal

cli-docs/reference/auth/index.md

@@ -0,0 +1,61 @@
+---
+sidebar_position: 4
+description: "Authenticate gt and git with Gitea"
+---
+
+# gt auth
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Authenticate gt and git with Gitea
+
+## Synopsis
+
+```text
+Authenticate gt and git with Gitea.
+
+gt keeps the accounts of each instance in hosts.yml and their tokens in the system
+keyring, or in a private file when you choose so. One account per instance is active;
+--user or GITEA_CLI_USER selects another for a single command. GITEA_TOKEN, together with
+GITEA_CLI_HOST or GITEA_INSTANCE_URL, replaces the stored credentials of its instance for the
+active account too; it must belong to the account that --user or GITEA_CLI_USER names. See
+gt help environment for how commands select the instance.
+```
+
+```
+gt auth [flags]
+```
+
+## Options
+
+```
+  -h, --help   help for auth
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt](../index.md): Work with Gitea from your terminal
+* [gt auth login](../auth/login.md): Log in to a Gitea instance
+* [gt auth logout](../auth/logout.md): Log out of an account
+* [gt auth refresh](../auth/refresh.md): Refresh an OAuth token
+* [gt auth setup-git](../auth/setup-git.md): Configure git to use gt for credentials
+* [gt auth status](../auth/status.md): Show the accounts gt can use
+* [gt auth switch](../auth/switch.md): Switch the active account of an instance
+* [gt auth token](../auth/token.md): Print the access token of an account

cli-docs/reference/auth/login.md

@@ -0,0 +1,72 @@
+---
+sidebar_position: 1
+description: "Log in to a Gitea instance"
+---
+
+# gt auth login
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Log in to a Gitea instance
+
+## Synopsis
+
+```text
+Log in to a Gitea instance. On a terminal without a method flag, gt asks for the instance,
+how to log in, where to keep the token and whether git should use gt for the instance.
+
+Create a token on the instance under Settings > Applications. Logging in to an account
+that gt already has replaces its stored credential after a confirmation (or with --yes).
+```
+
+```
+gt auth login [flags]
+```
+
+## Examples
+
+```
+$ gt auth login
+$ gt auth login --host gitea.com --with-token < token.txt
+$ gt auth login --host gitea.com --oauth --scopes read:repository,read:user
+$ gt auth login --host gitea.example.com --with-token --header 'CF-Access-Client-Id: $CF_ID' --header 'CF-Access-Client-Secret: $CF_SECRET'
+```
+
+## Options
+
+```
+      --client-cert file                Present the PEM TLS client certificate in file to an instance that requires one; convert a PKCS#12 file with: openssl pkcs12 -in cert.p12 -clcerts -nokeys -out cert.pem
+      --client-id ID                    OAuth application ID registered on the instance (default: the instance's stored ID, then gt's); implies --oauth
+      --client-key file                 Unencrypted PEM private key file of --client-cert (default: the key in the --client-cert file); convert a PKCS#12 file with: openssl pkcs12 -in cert.p12 -nocerts -nodes -out key.pem
+      --credential-store string         Where to keep the token {keyring|file} (default "keyring")
+      --header "Name: value"            Send the "Name: value" header with every request to this instance, such as an access proxy needs; a value of $NAME or ${NAME} is read from that environment variable (repeatable)
+  -h, --help                            help for login
+      --insecure                        Skip TLS certificate verification for this instance
+      --oauth                           Authorize in a web browser with OAuth
+      --scopes scopes                   OAuth token scopes, such as read:repository (default: write access to everything but administration); implies --oauth
+      --ssh-agent-key fingerprint       Sign requests with the ssh-agent key of fingerprint
+      --ssh-agent-principal principal   Sign requests with the ssh-agent certificate of principal
+      --ssh-key file                    Sign requests with the SSH private key in file
+      --with-token                      Read an access token from stdin, or ask for it on a terminal
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt auth](../auth/index.md): Authenticate gt and git with Gitea

cli-docs/reference/auth/logout.md

@@ -0,0 +1,58 @@
+---
+sidebar_position: 2
+description: "Log out of an account"
+---
+
+# gt auth logout
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Log out of an account
+
+## Synopsis
+
+```text
+Log out of an account: gt forgets the account and deletes its stored credential. Git's
+other credential helpers are asked to forget what they stored for the account on the
+instance, such as a copy of its token that a keychain kept after a push.
+```
+
+```
+gt auth logout [<user>] [flags]
+```
+
+## Examples
+
+```
+$ gt auth logout
+$ gt auth logout bob --host gitea.com
+# Without confirmation
+$ gt auth logout alice --yes
+```
+
+## Options
+
+```
+  -h, --help   help for logout
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt auth](../auth/index.md): Authenticate gt and git with Gitea

cli-docs/reference/auth/refresh.md

@@ -0,0 +1,56 @@
+---
+sidebar_position: 3
+description: "Refresh an OAuth token"
+---
+
+# gt auth refresh
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Refresh an OAuth token
+
+## Synopsis
+
+```text
+Refresh the OAuth token of the active account, or of --user, now. gt refreshes expiring
+OAuth tokens on its own; tokens pasted with --with-token cannot be refreshed and are
+replaced by logging in again.
+```
+
+```
+gt auth refresh [flags]
+```
+
+## Examples
+
+```
+$ gt auth refresh
+$ gt auth refresh --host gitea.com --user alice
+```
+
+## Options
+
+```
+  -h, --help   help for refresh
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt auth](../auth/index.md): Authenticate gt and git with Gitea

cli-docs/reference/auth/setup-git.md

@@ -0,0 +1,63 @@
+---
+sidebar_position: 4
+description: "Configure git to use gt for credentials"
+---
+
+# gt auth setup-git
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Configure git to use gt for credentials
+
+## Synopsis
+
+```text
+Configure git to ask gt for the credentials of an instance, so that git push and fetch
+over HTTPS use the active account, or the account of --user. gt's own clone and checkout
+commands do not need this.
+
+Other credential helpers, such as a system keychain, are turned off for the instance:
+otherwise they answer first and keep a copy of gt's token. --keep-helpers keeps them.
+```
+
+```
+gt auth setup-git [flags]
+```
+
+## Examples
+
+```
+$ gt auth setup-git
+$ gt auth setup-git --host gitea.com
+# Only for the current repository, always as alice
+$ gt auth setup-git --local --user alice
+```
+
+## Options
+
+```
+  -h, --help           help for setup-git
+      --keep-helpers   Keep other credential helpers for the instance; they are asked first and store gt's token
+      --local          Configure only the current Git repository instead of global Git configuration
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt auth](../auth/index.md): Authenticate gt and git with Gitea

cli-docs/reference/auth/status.md

@@ -0,0 +1,59 @@
+---
+sidebar_position: 5
+description: "Show the accounts gt can use"
+---
+
+# gt auth status
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Show the accounts gt can use
+
+## Synopsis
+
+```text
+Show the accounts gt can use on each instance, the active one, and how they
+authenticate. Fails with exit code 4 when there is no account, or when a credential is
+missing or rejected. With --json it exits 0 either way; read credential_available, verified and error.
+```
+
+```
+gt auth status [flags]
+```
+
+## Examples
+
+```
+$ gt auth status
+# Check the credentials against their instances
+$ gt auth status --verify
+$ gt auth status --host gitea.com --json
+```
+
+## Options
+
+```
+  -h, --help     help for status
+      --verify   Check each credential against its instance
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt auth](../auth/index.md): Authenticate gt and git with Gitea

cli-docs/reference/auth/switch.md

@@ -0,0 +1,57 @@
+---
+sidebar_position: 6
+description: "Switch the active account of an instance"
+---
+
+# gt auth switch
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Switch the active account of an instance
+
+## Synopsis
+
+```text
+Switch the active account of an instance, which commands use unless --user or GITEA_CLI_USER
+selects another. With two accounts, gt auth switch toggles between them; with more, it
+asks which one on a terminal.
+```
+
+```
+gt auth switch [<user>] [flags]
+```
+
+## Examples
+
+```
+$ gt auth switch
+$ gt auth switch bob
+$ gt auth switch bob --host gitea.com
+```
+
+## Options
+
+```
+  -h, --help   help for switch
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt auth](../auth/index.md): Authenticate gt and git with Gitea

cli-docs/reference/auth/token.md

@@ -0,0 +1,58 @@
+---
+sidebar_position: 7
+description: "Print the access token of an account"
+---
+
+# gt auth token
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Print the access token of an account
+
+## Synopsis
+
+```text
+Print the access token that gt uses for the active account, or for --user, so that
+scripts can call the API themselves. The GITEA_TOKEN of the instance takes precedence, as
+it does for other commands, and an expiring OAuth token is refreshed first. Accounts that
+sign requests with an SSH key have no token.
+```
+
+```
+gt auth token [flags]
+```
+
+## Examples
+
+```
+$ gt auth token
+$ curl -H "Authorization: token $(gt auth token)" https://gitea.com/api/v1/user
+$ gt auth token --host gitea.com --user alice
+```
+
+## Options
+
+```
+  -h, --help   help for token
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt auth](../auth/index.md): Authenticate gt and git with Gitea

cli-docs/reference/branch/create.md

@@ -0,0 +1,59 @@
+---
+sidebar_position: 1
+description: "Create a branch"
+---
+
+# gt branch create
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Create a branch
+
+## Synopsis
+
+```text
+Create a branch on the server from another branch, a tag or a commit; the default branch unless --source names one.
+```
+
+```
+gt branch create <branch> [flags]
+```
+
+## Examples
+
+```
+# Branch off the default branch
+$ gt branch create feature/login
+
+# Branch off a tag or a commit
+$ gt branch create hotfix/1.0.1 --source v1.0.0
+$ gt branch create bisect --source 3f2a9c1
+```
+
+## Options
+
+```
+  -h, --help            help for create
+  -s, --source string   Branch, tag or commit to start from (default: the default branch)
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt branch](../branch/index.md): Manage remote branches and protection rules

cli-docs/reference/branch/delete.md

@@ -0,0 +1,48 @@
+---
+sidebar_position: 2
+description: "Delete branches"
+---
+
+# gt branch delete
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Delete branches
+
+```
+gt branch delete <branch>... [flags]
+```
+
+## Examples
+
+```
+$ gt branch delete feature/login
+$ gt branch delete old-a old-b --yes
+```
+
+## Options
+
+```
+  -h, --help   help for delete
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt branch](../branch/index.md): Manage remote branches and protection rules

cli-docs/reference/branch/index.md

@@ -0,0 +1,55 @@
+---
+sidebar_position: 5
+description: "Manage remote branches and protection rules"
+---
+
+# gt branch
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Manage remote branches and protection rules
+
+## Synopsis
+
+```text
+Work with the branches of a repository on the server: list and view them, create, rename and
+delete them, and protect them from direct pushes. To work with local branches, use git.
+```
+
+```
+gt branch [flags]
+```
+
+## Options
+
+```
+  -h, --help   help for branch
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt](../index.md): Work with Gitea from your terminal
+* [gt branch create](../branch/create.md): Create a branch
+* [gt branch delete](../branch/delete.md): Delete branches
+* [gt branch list](../branch/list.md): List branches
+* [gt branch protect](../branch/protect.md): Protect branches
+* [gt branch rename](../branch/rename.md): Rename a branch
+* [gt branch unprotect](../branch/unprotect.md): Remove branch protection
+* [gt branch view](../branch/view.md): View a branch

cli-docs/reference/branch/list.md

@@ -0,0 +1,50 @@
+---
+sidebar_position: 3
+description: "List branches"
+---
+
+# gt branch list
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+List branches
+
+```
+gt branch list [flags]
+```
+
+## Examples
+
+```
+$ gt branch list
+$ gt branch list -R alice/project --limit 100 --json name,sha
+```
+
+## Options
+
+```
+  -h, --help        help for list
+  -L, --limit int   Maximum number of results (1..1000) (default 30)
+      --page int    Result page (default 1)
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt branch](../branch/index.md): Manage remote branches and protection rules

cli-docs/reference/branch/protect.md

@@ -0,0 +1,67 @@
+---
+sidebar_position: 4
+description: "Protect branches"
+---
+
+# gt branch protect
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Protect branches
+
+## Synopsis
+
+```text
+Add a protection rule for each existing branch, or with --pattern for every branch matching a
+glob. By default nobody can push directly and pull requests need one approving review.
+
+When a branch or pattern has a rule already, change only the settings the flags name and keep
+the others; --allow-push replaces those who may push directly.
+```
+
+```
+gt branch protect <branch>... [flags]
+```
+
+## Examples
+
+```
+# Require two approvals and passing CI on main
+$ gt branch protect main --required-approvals 2 --status-check ci/build
+
+# Let the release team push to every release branch
+$ gt branch protect --pattern 'release/*' --allow-push acme/release
+```
+
+## Options
+
+```
+      --allow-push strings          Users, or teams as ORG/TEAM, that may push directly
+      --block-on-rejected-reviews   Block merging while changes are requested
+      --dismiss-stale-approvals     Dismiss approvals when new commits are pushed
+  -h, --help                        help for protect
+      --pattern string              Protect the branches matching this glob, such as release/*
+      --required-approvals int      Approving reviews that pull requests need (default 1)
+      --status-check strings        Status checks that must pass (repeatable)
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt branch](../branch/index.md): Manage remote branches and protection rules

cli-docs/reference/branch/rename.md

@@ -0,0 +1,47 @@
+---
+sidebar_position: 5
+description: "Rename a branch"
+---
+
+# gt branch rename
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Rename a branch
+
+```
+gt branch rename <branch> <new-name> [flags]
+```
+
+## Examples
+
+```
+$ gt branch rename feature/logn feature/login
+```
+
+## Options
+
+```
+  -h, --help   help for rename
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt branch](../branch/index.md): Manage remote branches and protection rules

cli-docs/reference/branch/unprotect.md

@@ -0,0 +1,54 @@
+---
+sidebar_position: 6
+description: "Remove branch protection"
+---
+
+# gt branch unprotect
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Remove branch protection
+
+## Synopsis
+
+```text
+Remove the protection rules of branches, or of glob patterns such as release/*.
+```
+
+```
+gt branch unprotect <branch>... [flags]
+```
+
+## Examples
+
+```
+$ gt branch unprotect main
+$ gt branch unprotect 'release/*' --yes
+```
+
+## Options
+
+```
+  -h, --help   help for unprotect
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt branch](../branch/index.md): Manage remote branches and protection rules

cli-docs/reference/branch/view.md

@@ -0,0 +1,49 @@
+---
+sidebar_position: 7
+description: "View a branch"
+---
+
+# gt branch view
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+View a branch
+
+```
+gt branch view <branch> [flags]
+```
+
+## Examples
+
+```
+$ gt branch view main
+$ gt branch view feature/login --web
+```
+
+## Options
+
+```
+  -h, --help   help for view
+  -w, --web    Open the branch in the browser
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt branch](../branch/index.md): Manage remote branches and protection rules

cli-docs/reference/completion/bash.md

@@ -0,0 +1,57 @@
+---
+sidebar_position: 1
+description: "Generate the autocompletion script for bash"
+---
+
+# gt completion bash
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Generate the autocompletion script for bash
+
+## Synopsis
+
+```text
+Generate the completion script for bash. It needs the bash-completion package.
+
+To load completions in every new shell, add the eval line below to ~/.bashrc (on macOS,
+~/.bash_profile); bash 3.2, the default on macOS, cannot source <(gt completion bash).
+```
+
+```
+gt completion bash
+```
+
+## Examples
+
+```
+$ eval "$(gt completion bash)"
+```
+
+## Options
+
+```
+  -h, --help              help for bash
+      --no-descriptions   Disable completion descriptions
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt completion](../completion/index.md): Generate shell completion scripts

cli-docs/reference/completion/fish.md

@@ -0,0 +1,64 @@
+---
+sidebar_position: 2
+description: "Generate the autocompletion script for fish"
+---
+
+# gt completion fish
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Generate the autocompletion script for fish
+
+## Synopsis
+
+```text
+Generate the autocompletion script for the fish shell.
+
+To load completions in your current shell session:
+
+	gt completion fish | source
+
+To load completions for every new session, execute once:
+
+	gt completion fish > ~/.config/fish/completions/gt.fish
+
+You will need to start a new shell for this setup to take effect.
+```
+
+```
+gt completion fish [flags]
+```
+
+## Examples
+
+```
+$ gt completion fish > ~/.config/fish/completions/gt.fish
+```
+
+## Options
+
+```
+  -h, --help              help for fish
+      --no-descriptions   Disable completion descriptions
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt completion](../completion/index.md): Generate shell completion scripts

cli-docs/reference/completion/index.md

@@ -0,0 +1,52 @@
+---
+sidebar_position: 6
+description: "Generate shell completion scripts"
+---
+
+# gt completion
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Generate shell completion scripts
+
+## Synopsis
+
+```text
+Generate the autocompletion script for gt for the specified shell.
+See each sub-command's help for details on how to use the generated script.
+```
+
+```
+gt completion [flags]
+```
+
+## Options
+
+```
+  -h, --help   help for completion
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt](../index.md): Work with Gitea from your terminal
+* [gt completion bash](../completion/bash.md): Generate the autocompletion script for bash
+* [gt completion fish](../completion/fish.md): Generate the autocompletion script for fish
+* [gt completion powershell](../completion/powershell.md): Generate the autocompletion script for powershell
+* [gt completion zsh](../completion/zsh.md): Generate the autocompletion script for zsh

cli-docs/reference/completion/powershell.md

@@ -0,0 +1,61 @@
+---
+sidebar_position: 3
+description: "Generate the autocompletion script for powershell"
+---
+
+# gt completion powershell
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Generate the autocompletion script for powershell
+
+## Synopsis
+
+```text
+Generate the autocompletion script for powershell.
+
+To load completions in your current shell session:
+
+	gt completion powershell | Out-String | Invoke-Expression
+
+To load completions for every new session, add the output of the above command
+to your powershell profile.
+```
+
+```
+gt completion powershell [flags]
+```
+
+## Examples
+
+```
+$ gt completion powershell | Out-String | Invoke-Expression
+```
+
+## Options
+
+```
+  -h, --help              help for powershell
+      --no-descriptions   Disable completion descriptions
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt completion](../completion/index.md): Generate shell completion scripts

cli-docs/reference/completion/zsh.md

@@ -0,0 +1,75 @@
+---
+sidebar_position: 4
+description: "Generate the autocompletion script for zsh"
+---
+
+# gt completion zsh
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Generate the autocompletion script for zsh
+
+## Synopsis
+
+```text
+Generate the autocompletion script for the zsh shell.
+
+If shell completion is not already enabled in your environment you will need
+to enable it.  You can execute the following once:
+
+	echo "autoload -U compinit; compinit" >> ~/.zshrc
+
+To load completions in your current shell session:
+
+	source <(gt completion zsh)
+
+To load completions for every new session, execute once:
+
+#### Linux:
+
+	gt completion zsh > "${fpath[1]}/_gt"
+
+#### macOS:
+
+	gt completion zsh > $(brew --prefix)/share/zsh/site-functions/_gt
+
+You will need to start a new shell for this setup to take effect.
+```
+
+```
+gt completion zsh [flags]
+```
+
+## Examples
+
+```
+$ source <(gt completion zsh)
+```
+
+## Options
+
+```
+  -h, --help              help for zsh
+      --no-descriptions   Disable completion descriptions
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt completion](../completion/index.md): Generate shell completion scripts

cli-docs/reference/config/get.md

@@ -0,0 +1,50 @@
+---
+sidebar_position: 1
+description: "Print the value of a setting"
+---
+
+# gt config get
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Print the value of a setting
+
+```
+gt config get <key> [flags]
+```
+
+## Examples
+
+```
+$ gt config get editor
+$ gt config get default_host --show-source
+$ gt config get ssh_key --host https://gitea.com --user alice
+```
+
+## Options
+
+```
+  -h, --help          help for get
+      --show-source   Also print where the value comes from
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt config](../config/index.md): Manage settings

cli-docs/reference/config/index.md

@@ -0,0 +1,63 @@
+---
+sidebar_position: 7
+description: "Manage settings"
+---
+
+# gt config
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Manage settings
+
+## Synopsis
+
+```text
+Manage gt's settings.
+
+Preferences live in config.yml and instance settings in hosts.yml, in the configuration
+directory ($GITEA_CLI_CONFIG_DIR, or gitea-cli under the XDG config directory); gt config path prints
+both files. Environment variables that override settings are listed in gt help environment.
+
+Preferences: default_host, git_protocol, editor, prompt (enabled or disabled), pager,
+browser (never disables opening), color, hyperlinks and markdown (auto or raw), remote,
+http_timeout and aliases (see gt alias).
+Instance settings (--host <url>): user, ssh_host, insecure, git_protocol, oauth_client_id,
+headers, client_cert and client_key.
+Account settings (--host <url> --user <name>): ssh_key, ssh_agent,
+ssh_certificate_principal, ssh_key_fingerprint.
+```
+
+```
+gt config [flags]
+```
+
+## Options
+
+```
+  -h, --help   help for config
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt](../index.md): Work with Gitea from your terminal
+* [gt config get](../config/get.md): Print the value of a setting
+* [gt config list](../config/list.md): List settings and their values
+* [gt config path](../config/path.md): Print the paths of the settings files
+* [gt config set](../config/set.md): Change a setting

cli-docs/reference/config/list.md

@@ -0,0 +1,49 @@
+---
+sidebar_position: 2
+description: "List settings and their values"
+---
+
+# gt config list
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+List settings and their values
+
+```
+gt config list [flags]
+```
+
+## Examples
+
+```
+$ gt config list
+# Include the settings of an instance
+$ gt config list --host https://gitea.com
+```
+
+## Options
+
+```
+  -h, --help   help for list
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt config](../config/index.md): Manage settings

cli-docs/reference/config/path.md

@@ -0,0 +1,49 @@
+---
+sidebar_position: 3
+description: "Print the paths of the settings files"
+---
+
+# gt config path
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Print the paths of the settings files
+
+```
+gt config path [flags]
+```
+
+## Examples
+
+```
+$ gt config path
+# Settings of another configuration directory
+$ GITEA_CLI_CONFIG_DIR=~/work/gt gt config path
+```
+
+## Options
+
+```
+  -h, --help   help for path
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt config](../config/index.md): Manage settings

cli-docs/reference/config/set.md

@@ -0,0 +1,80 @@
+---
+sidebar_position: 4
+description: "Change a setting"
+---
+
+# gt config set
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Change a setting
+
+## Synopsis
+
+```text
+Change a preference, an instance setting (--host) or an account setting (--host and --user).
+
+Preferences:
+  default_host    instance to use when no flag or repository selects one
+  git_protocol    https or ssh, for clones and remotes
+  editor          command that edits bodies and messages, such as "code --wait"
+  prompt          enabled or disabled; disabled turns prompts off
+  pager           command that pages long output on a terminal; GITEA_CLI_PAGER overrides it
+  browser         command that opens URLs; never disables opening
+  color           auto, always or never
+  hyperlinks      auto, always or never, for clickable links in terminals
+  markdown        auto renders Markdown on a terminal, raw prints the source
+  remote          Git remote used to find the repository of a clone
+  http_timeout    longest wait for the instance to answer a request, such as 30s, or for more
+                  data while a transfer stalls; 0 waits as long as it takes; a transfer that
+                  keeps moving and migrations are not cut off. The wait for an answer starts
+                  once an upload has reached the instance's machine, so an instance that reads
+                  uploads slowly from its connection needs a longer timeout
+
+Instance settings: user (active account), ssh_host, insecure, git_protocol, oauth_client_id,
+and headers: "Name: value" adds a header to every API request to the instance, such as an
+access proxy needs, "Name:" removes it, and a value of $NAME or ${NAME} is read from that
+environment variable when sent; client_cert and client_key name the PEM files of a TLS client
+certificate for an instance that requires one; without client_key, the key is read from
+client_cert.
+Account settings: ssh_key, ssh_agent, ssh_certificate_principal, ssh_key_fingerprint.
+```
+
+```
+gt config set <key> <value> [flags]
+```
+
+## Examples
+
+```
+$ gt config set editor "code --wait"
+$ gt config set ssh_host git.example.com:2222 --host https://example.com
+$ gt config set ssh_key ~/.ssh/id_ed25519 --host https://example.com --user alice
+```
+
+## Options
+
+```
+  -h, --help   help for set
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt config](../config/index.md): Manage settings

cli-docs/reference/doctor.md

@@ -0,0 +1,59 @@
+---
+sidebar_position: 8
+description: "Check gt's setup for this directory"
+---
+
+# gt doctor
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Check gt's setup for this directory
+
+## Synopsis
+
+```text
+Check the setup that commands in this directory use: the settings files, the instance,
+its configured headers and whether it answers, the account and its credential, the
+repository, and Git. Each problem comes with the command that fixes it. gt doctor fails
+when a check fails.
+```
+
+```
+gt doctor [flags]
+```
+
+## Examples
+
+```
+$ gt doctor
+# Check another repository and instance
+$ gt doctor -R gitea.com/gitea/cli
+$ gt doctor --jq '.checks[] | select(.status == "failed")'
+```
+
+## Options
+
+```
+  -h, --help   help for doctor
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt](index.md): Work with Gitea from your terminal

cli-docs/reference/help/environment.md

@@ -0,0 +1,91 @@
+---
+sidebar_position: 1
+description: "Environment variables and global flags"
+---
+
+# gt help environment
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Environment variables and global flags
+
+## Synopsis
+
+```text
+Global flags work with every command, before or after the command name:
+
+      --cwd directory     Working directory for repository discovery
+      --debug             Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL          Gitea instance URL, including any base path
+      --interactive       Allow prompts with machine output
+  -q, --jq expression     Filter JSON output using a jq expression; implies --json
+      --json fields       Output JSON with the specified comma-separated fields, or all fields
+      --no-input          Disable prompts and implicit editor/browser interactions
+      --remote remote     Git remote used for repository discovery
+  -R, --repo OWNER/REPO   Select a repository as OWNER/REPO or URL
+      --sudo user         Perform API requests as this user (requires an administrator account)
+      --user name         Account name on the selected instance
+  -y, --yes               Accept confirmations without prompting
+
+gt selects the repository from --repo, GITEA_CLI_REPO, git config gt.repository (gt repo
+set-default) or a Git remote (--remote, else the base remote pr checkout recorded, the
+current branch's remote, upstream or origin, skipping remotes on instances without an
+account, or not on --host or the GITEA_TOKEN instance). Like gh, a clone with upstream
+and origin targets upstream: a branch tracking origin does not select the fork,
+and the instance from the repository URL, --host, GITEA_CLI_HOST or GITEA_INSTANCE_URL,
+default_host, the only configured instance, or, among several, the instance of the clone's
+repository.
+
+Environment variables:
+
+  GITEA_CLI_CONFIG_DIR                configuration directory; gt config path prints the files
+  GITEA_CLI_HOST, GITEA_INSTANCE_URL  instance URL, overriding default_host
+  GITEA_TOKEN                         access token for that instance instead of stored credentials
+  GITEA_INSTANCE_INSECURE             with GITEA_TOKEN, skip TLS verification when true
+  GITEA_INSTANCE_SSH_HOST             with GITEA_TOKEN, SSH host that identifies the instance's remotes
+  GITEA_CLI_USER                      account on the selected instance, like --user
+  GITEA_CLI_REPO                      repository as OWNER/REPO or URL, like --repo
+  GITEA_CLI_EDITOR                    editor, overriding config.yml
+  GITEA_CLI_PAGER                     pager, overriding config.yml
+  GITEA_CLI_COLOR                     color preference: auto, always or never
+  GITEA_CLI_HTTP_TIMEOUT              longest wait for an answer, overriding config.yml
+  NO_COLOR                            disables automatic color when set, even with CLICOLOR_FORCE
+  CLICOLOR_FORCE                      unless empty or 0, colors stderr, even when redirected, and
+                                      a terminal stdout despite CLICOLOR=0 or TERM=dumb
+  CLICOLOR                            disables automatic color on a terminal when 0
+  VISUAL, EDITOR, PAGER, BROWSER      editor (VISUAL first), pager and browser when config.yml sets none
+  TERM                                dumb asks each prompt as a line of text, for screen readers,
+                                      and turns off automatic color
+
+Piped or redirected stdout is data: the color settings never color it. Only a
+command's own --color always does, such as gt pr diff --color always.
+
+Preferences in config.yml are described in gt config --help.
+```
+
+## Options
+
+```
+  -h, --help   help for environment
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt](): Work with Gitea from your terminal

cli-docs/reference/help/exit-codes.md

@@ -0,0 +1,53 @@
+---
+sidebar_position: 2
+description: "Exit codes used by gt"
+---
+
+# gt help exit-codes
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Exit codes used by gt
+
+## Synopsis
+
+```text
+gt exits with one of these codes:
+
+  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.
+```
+
+## Options
+
+```
+  -h, --help   help for exit-codes
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt](): Work with Gitea from your terminal

cli-docs/reference/help/formatting.md

@@ -0,0 +1,65 @@
+---
+sidebar_position: 3
+description: "JSON output with --json and --jq"
+---
+
+# gt help formatting
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+JSON output with --json and --jq
+
+## Synopsis
+
+```text
+gt prints text for people by default. Scripts should use JSON: the columns and
+wording of text output may change between releases.
+
+  --json             print every field
+  --json FIELDS      print only the comma-separated FIELDS, such as --json number,title
+  -q, --jq EXPR      filter the JSON with a jq expression; implies --json
+
+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.
+
+--jq runs inside gt, so jq does not need to be installed. String results print
+without quotes:
+
+  $ gt issue list --json number,title --jq '.[] | "\(.number)\t\(.title)"'
+
+Some fields cost extra requests, such as the reviewers of pr list, the blocked_by and blocks
+of issue view and issue edit, and the visibility of org member 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.
+Commands that return no resource, such as deletes, reject --json.
+```
+
+## Options
+
+```
+  -h, --help   help for formatting
+```
+
+## Options inherited from parent commands
+
+```
+      --cwd directory       Working directory for repository discovery
+      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
+      --host URL            Gitea instance URL, including any base path
+      --interactive         Allow prompts with machine output
+  -q, --jq expression       Filter JSON output using a jq expression; implies --json
+      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
+      --no-input            Disable prompts and implicit editor/browser interactions
+      --remote remote       Git remote used for repository discovery
+  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
+      --sudo user           Perform API requests as this user (requires an administrator account)
+      --user name           Account name on the selected instance
+  -y, --yes                 Accept confirmations without prompting
+```
+
+## SEE ALSO
+
+* [gt](): Work with Gitea from your terminal

cli-docs/reference/help/index.md

@@ -0,0 +1,14 @@
+---
+sidebar_position: 30
+description: "Guides built into gt, read with gt help <topic>."
+---
+
+# Help topics
+
+<!-- Generated by update_cli_docs.sh from the gitea/cli sources, do not edit. -->
+
+Guides built into gt, read with `gt help <topic>`:
+
+- [gt help environment](environment.md): Environment variables and global flags
+- [gt help exit-codes](exit-codes.md): Exit codes used by gt
+- [gt help formatting](formatting.md): JSON output with --json and --jq