tea (Gitea/Forgejo CLI)

What it is

tea is the official CLI for Gitea and Forgejo instances — repos, pull requests, issues, releases, notifications. Since Forgejo is our default forge, tea is the primary forge CLI on this fleet.

Install

Debian/Ubuntu:

sudo apt install tea          # may lag upstream; fine for basics

Latest stable binary (x86_64; use linux-arm64 on arm64):

curl -fsSL -o ~/.local/bin/tea \
  https://dl.gitea.com/tea/$(curl -fsSL https://dl.gitea.com/tea/version.json | grep -oP '"Version":\s*"\K[^"]+')/tea-linux-amd64
chmod +x ~/.local/bin/tea

Or build/pin via the Gitea releases page if you need a specific version.

Authenticate

Create an access token first: in Forgejo → Settings → Applications → Generate New Token (scopes: repo, issue, read:org). Store it in Vaultwarden (https://vault.portugalfuturista.org).

tea login add \
  --name portugalfuturista \
  --url https://code.portugalfuturista.org \
  --token <token-from-vaultwarden>
tea login default portugalfuturista

Logins live in ~/.config/tea/config.yml (keep it mode 600 — it holds tokens).

Configure for this environment

# inside a clone
git remote -v
# origin  https://code.portugalfuturista.org/portugalfuturista/<repo>.git

tea auto-detects the login from the git remote. On the LAN the same instance is reachable at http://192.168.0.9:3001 — prefer the TLS name so certs and tokens stay consistent.

tea repos ls --limit 5
tea issues ls
tea pr create --title "..." --description "..."

Self-hosted equivalent

tea is the self-hosted equivalent — Forgejo at https://code.portugalfuturista.org is the self-hosted GitHub. For public github.com mirrors only, see gh.md.

Aurélio integration

The cli-forge skill uses tea for PR/issue automation against Forgejo. Connector registry id: forgejo (github.com mirrors: github).

Verify

tea --version
# Version: 0.x.x ...
tea logins ls
# NAME              URL                                  DEFAULT
# portugalfuturista https://code.portugalfuturista.org   true
tea whoami
# <your-forgejo-username>

Troubleshooting

401 Unauthorized — token missing the needed scope; regenerate in Forgejo with repo/issue and re-run tea login add (or edit ~/.config/tea/config.yml).
Wrong login picked up — tea matches by remote URL; set the default with tea login default <name> or pass --login.
TLS error on the LAN IP — the cert is for code.portugalfuturista.org; use the name, not 192.168.0.9:3001, with HTTPS.
unknown command — distro package is old; install the latest binary.

2.7 KiB Raw Blame History