nprasad2077/docs
1
1 Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-11-05 17:45:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: shorten the gt guides

Browse Source 
Cover what users need to get going and leave the details to
gt <command> --help and gt help.

Signed-off-by: bircni <[email protected]>
This commit is contained in:
bircni committed 2026-10-22 18:34:04 +02:00
1 parent 540757fe56
commit 31cd47a65c
5 files changed
+72 -450
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

cli-docs/authentication.md
+27 -152
View File
@@ -4,179 +4,54 @@ sidebar_position: 3
# Logging in
`gt auth login` logs in to a Gitea instance. gt can authenticate in three ways:
On a terminal, `gt auth login` asks for the instance and how to log in. gt never asks for
your password.
| 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
## OAuth in a browser
```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`.
gt opens the instance's authorization page, so single sign-on and two-factor
authentication work as on the web. The browser has to run on the same machine as gt.
`--scopes` limits the token to fewer [scopes](/development/oauth2-provider#scopes); gt
refreshes OAuth tokens on its own.
By default the token has write access to everything but administration. `--scopes`
requests fewer, using the [token scope](/development/oauth2-provider#scopes) names:
## Access token
Create a token under **Settings > Applications** on the instance and pass it on stdin:
```bash
gt auth login --host https://gitea.example.com --oauth --scopes read:repository,read:user
gt auth login --host https://gitea.example.com --with-token < token.txt
```
gt refreshes an expiring OAuth token on its own. `gt auth refresh` refreshes it now.
The token needs `read:user`, and the scopes of what you do with gt, such as
`write:repository` and `write:issue` for working on pull requests.
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.
## SSH key
## 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:
gt can sign its requests with an SSH key registered for your account instead of using a
token:
```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.
## Where credentials are kept
Tokens go to the system keyring by default. `--credential-store file` keeps them in gt's
configuration directory instead, for machines without a keyring. `gt auth status` lists
your accounts and `gt auth logout` removes one.
## 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.
`gt auth setup-git` lets `git push` and `git fetch` over HTTPS use gt's login. gt's own
clone and checkout commands need no setup.
## 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.
Run `gt auth login` for each instance and account. gt picks the instance from the
repository's remote or `--host`, and the account with `gt auth switch` or `--user`.
For instances behind an access proxy, `--header` and `--client-cert` add headers and a
client certificate; see `gt auth login --help`.
cli-docs/ci.md
+11 -67
View File
@@ -4,48 +4,21 @@ 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
Give gt a token and an instance through the environment, and turn prompts off:
| 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 |
| `GITEA_TOKEN` | Access token; gt never stores it |
| `GITEA_CLI_HOST` or `GITEA_INSTANCE_URL` | URL of the instance |
| `GITEA_CLI_REPO` | Repository, like `--repo` |
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
```
`--no-input` makes a command fail instead of prompting, and `--yes` confirms changes in
advance.
## 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`:
Gitea does not allow secret names that start with `GITEA_`, so store the token as, for
example, `GT_TOKEN`:
```yaml
jobs:
@@ -56,37 +29,8 @@ jobs:
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
- run: curl -fsSL https://gitea.com/gitea/cli/raw/branch/main/scripts/install.sh | sh
- run: gt workflow run deploy.yml --ref main --field env=staging --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.
`gt run watch` and `gt pr checks --watch` wait for runs and checks and fail when they do.
cli-docs/index.md
+11 -34
View File
@@ -5,58 +5,35 @@ 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.
[gt](https://gitea.com/gitea/cli) is the official command line client for Gitea. It works
with repositories, issues, pull requests, releases, Actions and the other resources of a
Gitea instance, from a terminal or a script.
:::info Development version
These pages describe builds from the `main` branch of gitea/cli, published as `nightly`
binaries and images.
These pages describe builds from the `main` branch of gitea/cli.
:::
## 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`.
gt needs Gitea 28 or later, and Git for the commands that clone, check out or push.
## Getting started
1. [Install gt](installation.md).
2. [Log in](authentication.md) to your Gitea instance:
2. [Log in](authentication.md):
```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:
3. Run commands in a clone of a repository on that instance, or select one with `--repo`:
```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.
`gt doctor` checks your setup and suggests a fix for each problem it finds.
## 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).
Every command documents itself with `--help`. `gt help environment`, `gt help formatting`
and `gt help exit-codes` cover global flags and environment variables, JSON output, and
exit codes.
cli-docs/installation.md
+15 -109
View File
@@ -4,128 +4,34 @@ sidebar_position: 2
# Installation
gt is a single binary, built for Linux, macOS, Windows, and FreeBSD.
gt is a single binary 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:
The install script downloads gt from [dl.gitea.com](https://dl.gitea.com/gitea-cli/),
verifies its checksum and installs it.
```bash
# Linux, macOS, FreeBSD
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
# Windows
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`.
Set `GITEA_CLI_VERSION` to install a specific version, or `nightly` for the latest build
of `main`.
Both scripts read these environment variables:
## Other ways
| 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. |
- **Binaries:** download them from [dl.gitea.com/gitea-cli](https://dl.gitea.com/gitea-cli/).
- **Docker:** the [`gitea/gitea-cli`](https://hub.docker.com/r/gitea/gitea-cli) image runs
`gt` as its entry point.
- **Go:** `go install gitea.dev/cli/cmd/gt@latest`
`install.sh` also accepts `--nightly` and `--version VERSION`:
## Shell completion and man pages
```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.
`gt completion <shell>` prints the completion script for bash, zsh, fish or PowerShell;
`gt completion <shell> --help` shows how to load it. `gt man` prints the manual.
cli-docs/scripting.md
+8 -88
View File
@@ -4,99 +4,19 @@ sidebar_position: 5
# Output and scripting
gt prints text for people by default. Scripts should read JSON instead: the columns and
wording of the text output may change between releases.
## JSON
`--json` prints every field of the result, `--json FIELDS` only the comma-separated
fields you list:
Scripts should read JSON: the text output is meant for people and may change.
```bash
gt issue list --json
gt pr view 123 --json number,title,state
```
The **JSON FIELDS** section of a command's `--help` lists its fields, and shell completion
offers them after `--json`. An unknown field reports the available ones. Commands that
return no resource, such as deletes, reject `--json`.
`--jq` (`-q`) filters the JSON with a [jq](https://jqlang.org) expression and implies
`--json`. It runs inside gt, so jq does not need to be installed. String results print
without quotes:
```bash
gt issue list --json number,title --jq '.[] | "\(.number)\t\(.title)"'
```
Some fields cost extra requests, such as the reviewers of `gt pr list`. gt makes them only
when the output includes the field: `--json` names it, or `--json` selects every field and
the `--jq` expression names it. An expression that reaches such a field without naming it,
as `to_entries` does, sees it empty; name the field in `--json` instead.
`--json` prints all fields or the ones you list; the **JSON FIELDS** section of a command's
`--help` names them. `--jq` filters the result without needing jq installed. Piped lists
print as tab-separated values.
On a terminal, JSON is indented and colored; otherwise each value prints on one line. gt
does not prompt while it prints JSON; `--interactive` allows prompts anyway.
`gt help formatting` describes all of this.
gt exits with 0 on success, 1 when a command fails, 2 on a usage error and 4 when
authentication is missing or rejected; `gt help exit-codes` lists all codes.
## Piped output
JSON and other results go to stdout. Diagnostics, prompts and the messages that confirm a
change go to stderr, so they never end up in the data a script reads.
Piped or redirected, lists print as tab-separated values without a header row, ready for
`cut` or `awk`:
```bash
gt issue list --kind all --milestone v1.0 | cut -f1,2
```
Color settings never color piped output. Only a command's own `--color always` does, such
as `gt pr diff --color always`.
## Exit codes
| Code | Meaning |
| --- | --- |
| 0 | Success, including an empty list |
| 1 | The command failed |
| 2 | Usage error: an unknown command or flag, or a missing or invalid argument |
| 3 | Canceled: a declined confirmation, a prompt left with Esc or Ctrl-D, or a timeout |
| 4 | Authentication is missing or was rejected |
| 8 | `gt pr checks`: some checks are still pending |
| 130 | Interrupted with Ctrl-C, also at a prompt |
A command may document further codes in its help. `gt auth status`, for example, exits
with 4 when there is no account or a credential is missing or rejected; with `--json` it
exits with 0 either way and reports the problem in its output.
## The API
`gt api` sends an authenticated request to the instance's API, for what no command covers
yet. The endpoint is a path under `/api/v1`, and `{owner}` and `{repo}` take the current
repository:
```bash
gt api user --jq .login
gt api repos/{owner}/{repo}/issues -f title="Crash on start" -F labels='[3]'
gt api user/repos --paginate --jq '.[].full_name'
```
A response outside 2xx prints its body, then fails. `gt auth token` prints the token gt
uses, for tools that call the API themselves.
## Aliases
An alias is a shortcut that expands to a gt command with its arguments:
```bash
# gt il runs gt issue list --label bug
gt alias set il "issue list --label bug"
# $1 takes the first argument: gt review 13 runs gt pr review 13 --approve
gt alias set review 'pr review $1 --approve'
```
`$1`, `$2` and so on take the arguments in that position; other arguments follow the
expansion, so `gt il --state all` runs `gt issue list --label bug --state all`. Aliases never
run a shell, and a built-in command always wins over an alias of the same name.
`--clobber` replaces an existing alias, `gt alias list` lists them and `gt alias delete`
removes one. They are kept in `config.yml`.
`gt api` calls any API endpoint with gt's login, and `gt alias set` defines shortcuts for
commands you use often.