Cheatsheets:Tea

Quick reference for smart people — part of our dev cheatsheets collection.

tea is the official command-line client built for Gitea. Speaking the Gitea API, it works against any compatible forge — Gitea itself, Forgejo, and Codeberg (which runs Forgejo) — one tool for all.

New to tea? The official tea page and the README are good starts.

Basic example: clone, open a PR, merge

tea login add                        # one-time: register a forge (interactive)
tea clone alice/widgets              # clone owner/repo from your default login
cd widgets
git switch -c fix-header             # ordinary git work
git push -u origin fix-header
tea pr create -b main -t "Fix header" -d "Make the header sticky"
tea pr checkout 42                   # pull PR #42 into a local branch
tea pr merge 42 --style squash       # merge it

Run tea inside a clone and it reads owner/repo from the git remote — no flags needed. Otherwise point it at the target with --repo owner/name (or a local path), --remote name, and --login name.

Installing tea

On Linux,MacOS, the easiest installation is via Homebrew:

brew install tea

For more details on installation, see the official instructions.

Do NOT install the "tea" in Debian repository. It is not the same cup of tea: it is a text editor porting the same name.

Logging in

Generate an application token in the forge's web UI (Settings → Applications), then:

tea login add                                        # interactive: "application token", paste token
tea login add -n work -u https://git.example.com -t $TOKEN   # non-interactive
tea login add -n codeberg -u https://codeberg.org --oauth     # browser OAuth2 flow
tea login ls                                          # list your forges
tea login default                                    # show the default login
tea whoami                                           # who is the current login
tea logout                                           # forget the current login

Keep one login per forge — tea stores them all in $XDG_CONFIG_HOME/tea/config.yml (usually ~/.config/tea/config.yml):

tea login add -n gitea    -u https://gitea.com       -t $TOKEN_A
tea login add -n forgejo  -u https://git.example.com -t $TOKEN_B
tea login add -n codeberg -u https://codeberg.org    -t $TOKEN_C

tea pr list -l codeberg --repo alice/widgets         # act on another forge

Authenticate plain git too: register a login with --git-credentials, and git push / git clone over HTTPS use the stored token without prompting.

Everyday: issues

tea issues                            # open issues of the current repo
tea issues --state all                # closed ones too
tea issues --assignee alice           # only alice's
tea issues --keyword sticky           # search
tea issue 42                          # view issue #42
tea issue 42 --comments               # ... with the comment thread
tea issue create -t "Header not sticky" -d "Steps…" -L bug -a alice
tea issue close 42                    # close
tea issue reopen 42                   # reopen
tea labels list                       # pick label names for -L
tea comment add 42 "Fixed in 0.9.1"   # comment on an issue or PR

Everyday: pull requests

tea pr list                           # open PRs of the current repo
tea pr list --state all -o table      # everything, as a table
tea pr 42                             # view PR #42
tea pr checkout 42                    # local branch with the PR's commits
tea pr create -b main -t "Fix header" -d "Body" --draft
tea pr approve 42                     # approve
tea pr reject 42                      # request changes
tea pr merge 42                       # merge (default: merge commit)
tea pr merge 42 --style squash        # or: rebase, rebase-merge
tea pr close 42                       # close without merging
tea pr clean 42                       # drop the PR's local & remote branches

tea assumes your commits are already pushed. Push the branch before tea pr create or tea pr merge.

Releases

tea releases                            # list releases
tea release create --tag v1.0.0 --title "v1.0.0" --note-file CHANGELOG.md
tea release create --tag v0.9.0 --prerelease -a app.tar.gz -a app.sha256
tea release delete v1.0.0 -y --delete-tag

Repos

tea repo search witches # search the whole instance for "witches"
tea repo create --name witchhub --init --private --gitignores go,node
tea clone alice/witchub # = git clone
tea repo fork alice/witchhub # fork to your account
tea repo create-from-template -t alice/witchhub-template -n my-new-witchhub

Notifications

tea notifications                       # unread, current repo
tea notifications --mine                # unread across all your repos
tea notifications read                  # mark as read

CI: Actions

tea actions runs list                                    # recent workflow runs
tea actions runs logs 1234 --follow                      # stream logs of a run
tea actions workflows dispatch deploy.yml --ref main --input env=staging
tea actions secrets create API_KEY                       # prompts for the value
tea actions variables set API_URL https://api.example.com

Scripting & output

tea pr list -o json                     # formats: json | yaml | table | csv | tsv | simple
tea issues --state open --limit 100 -o csv
tea api /repos/alice/widgets/issues     # any authenticated API call (-X, -d, -H, -f)

For more

• README — install options (brew, dl.gitea.com, go install) and quickstart
• CLI reference — auto-generated docs for every command and flag
• Official tea page
• Shell completion: source <(tea completion bash) (zsh, fish, PowerShell also supported); tea man prints the man page
• Cheatsheets:Git — the git that does the heavy lifting