tangledgroup tea 0.14.0
Overview
tea is the official command-line tool for interacting with Gitea servers. Written in Go and built on code.gitea.io/sdk/gitea, it provides a productivity helper for managing most entities on one or multiple Gitea instances. It also offers local git helpers like tea pr checkout that work in an upstream/fork workflow.
tea automatically detects context from the repository in $PWD when available, and works best when the local main branch tracks the upstream repo. Configuration is persisted in $XDG_CONFIG_HOME/tea.
Key capabilities:
- Multi-instance support — log in to multiple Gitea servers simultaneously
- Authentication — application tokens, OAuth2 flow, basic auth, SSH keys
- Machine-readable output — JSON, YAML, CSV, TSV, table, and simple formats
- Interactive mode — commands without arguments enter interactive prompts
- Shell completion — bash, zsh, fish, PowerShell
- Docker image — available at
docker.io/gitea/tea
When to Use
- Managing Gitea issues, pull requests, releases, or milestones from the terminal
- Automating Gitea workflows in CI/CD pipelines (dispatching actions, merging PRs)
- Working across multiple Gitea instances without switching browsers
- Scripting bulk operations (closing issues, updating labels, managing webhooks)
- Integrating with AI-driven development flows (auto-merge on approval, re-trigger CI)
- Generating machine-readable output for data analysis or reporting
Installation / Setup
Install via package manager:
# macOS (official Homebrew)
brew install tea
# Arch Linux (thirdparty)
pacman -S tea
# Alpine Linux (thirdparty)
apk add tea
Or use prebuilt binaries from dl.gitea.com/tea/ or Docker:
docker run --rm docker.io/gitea/tea --version
Install from source (requires Go 1.26+):
go install code.gitea.io/tea@latest
Logging In
The most compatible authentication method across Gitea deployments:
- Generate an application token in your Gitea user settings (at least user read scope)
- Run
tea login add, select application token, and paste the token
Since v0.10, OAuth2 interactive flow is also supported:
tea login add --oauth
SSH authentication is also available:
tea login add --ssh-agent-key <fingerprint>
Shell Completion
# bash
source <(tea completion bash)
# zsh
source <(tea completion zsh)
# fish
tea completion fish > ~/.config/fish/completions/tea.fish
Man Page
man <(tea man)
Core Concepts
Repository Context: tea auto-detects the Gitea login and repository from git remotes in $PWD. Override with --repo, --login, or --remote flags.
Command Structure: Subcommands follow tea <noun> <verb> [<args>] [<flags>]. The default verb is list.
Output Formats: All commands support --output (-o) with values: simple, table, csv, tsv, yaml, json.
Field Selection: List commands support --fields (-f) for comma-separated field selection.
Pagination: Use --limit / --lm and --page / -p for paginated results.
Login Management: Multiple Gitea logins are stored in $XDG_CONFIG_HOME/tea/config.yml. OAuth tokens can be stored in the OS keyring via credstore (v0.13+).
Advanced Topics
Command Reference: Complete CLI reference for all subcommands and flags → Command Reference
Authentication and Configuration: Login methods, config structure, OAuth2, SSH auth → Authentication
CI/CD and Automation Workflows: Workflow dispatch, PR auto-merge, action secrets, webhooks → Automation Workflows