From 31cd47a65c26a262d77f7f5106d903e5496573bc Mon Sep 17 00:00:00 2001 From: bircni Date: Thu, 22 Oct 2026 18:34:04 +0200 Subject: [PATCH] docs: shorten the gt guides Cover what users need to get going and leave the details to gt --help and gt help. Signed-off-by: bircni --- cli-docs/authentication.md | 179 ++++++------------------------------- cli-docs/ci.md | 78 +++------------- cli-docs/index.md | 45 +++------- cli-docs/installation.md | 124 ++++--------------------- cli-docs/scripting.md | 96 ++------------------ 5 files changed, 72 insertions(+), 450 deletions(-) diff --git a/cli-docs/authentication.md b/cli-docs/authentication.md index 02b29ca2..fef78fbb 100644 --- a/cli-docs/authentication.md +++ b/cli-docs/authentication.md @@ -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`. diff --git a/cli-docs/ci.md b/cli-docs/ci.md index 02c0f4c0..97436605 100644 --- a/cli-docs/ci.md +++ b/cli-docs/ci.md @@ -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. diff --git a/cli-docs/index.md b/cli-docs/index.md index 4b369d89..de9bb963 100644 --- a/cli-docs/index.md +++ b/cli-docs/index.md @@ -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. diff --git a/cli-docs/installation.md b/cli-docs/installation.md index fa2d7a6f..7266e8e9 100644 --- a/cli-docs/installation.md +++ b/cli-docs/installation.md @@ -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--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 ` 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 --help` shows the details for each shell. - -## Man pages - -`gt man` prints gt's full manual, and `gt man ` 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 ` prints the completion script for bash, zsh, fish or PowerShell; +`gt completion --help` shows how to load it. `gt man` prints the manual. diff --git a/cli-docs/scripting.md b/cli-docs/scripting.md index ae940808..74ec4966 100644 --- a/cli-docs/scripting.md +++ b/cli-docs/scripting.md @@ -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.