skills/gitea-tea/SKILL.md

name, description, version

name	description	version
gitea-tea	Manage Gitea via CLI using `tea`. Use when user mentions "tea", "gitea cli", or needs terminal-based Gitea operations. Use instead of GitHub CLI when agent reaches for "gh". (Child skill of `gitea` parent skill.)	1.1.0

Gitea CLI (tea)

Official command-line tool for Gitea. Verified against tea v0.14.1.

Decision flow

1. Prefer the gitea MCP server (configured in .mcp.json) for repos, issues, PRs, releases, branches, files, commits, tags, packages, search, notifications, actions config/runs, time tracking, wiki, and labels/milestones. See ../gitea/references/mcp-tools.md.
2. Reach for tea when MCP doesn't cover the op cleanly:
   • tea clone <repo-slug> — local checkout without git
   • tea pulls checkout / clean — local-branch lifecycle for a PR
   • tea ssh-keys add/delete — current user's SSH keys
   • tea webhooks — webhook CRUD (MCP doesn't expose webhooks)
   • tea admin users … — user admin (MCP doesn't expose admin)
   • tea times add/delete — time-tracking entries (MCP exposes most; tea is the easier write path)
   • tea actions secrets/variables — quick stdin/file ingestion of secret values
   • tea api … — one-off arbitrary endpoint with auth handled
3. Avoid: tea open (browser, hangs in headless), tea pulls review (interactive prompt), tea logins add --oauth/--ssh-agent-* (interactive).

Non-interactive rules

tea will prompt for missing values when stdout is a TTY. In agent contexts:

• Pass --output simple or --output json to disable interactive output.
• Provide every required value upfront — title, description, etc.
• Destructive ops require --confirm/-y for most commands, but tea repos delete uses --force/-f, and tea labels/milestones/organizations delete have no confirm flag (they just delete).
• Outside a git repo, always pass --repo owner/name and (if multiple logins) --login <login-name>.

Auth check

tea whoami                                   # confirm login works
tea logins list                              # see configured logins

Set up a token-based login non-interactively:

tea logins add --name farh --url https://gitea.example.com --token "$GITEA_TOKEN"
tea logins default farh

Env vars read on first use: GITEA_SERVER_URL, GITEA_SERVER_TOKEN.

Common flags

Flag	Purpose
--login/-l <name>	Pick a configured login
--repo/-r <owner/name>	Operate on a specific repo (required outside git repos)
--remote/-R <name>	Discover login from a git remote
--output/-o <fmt>	simple, table, csv, tsv, yaml, json
--page/-p --limit/--lm	Pagination (note: short form is --lm, two dashes)
--confirm/-y	Confirm destructive ops (most commands)

Quick examples

# Issues — note: --description (not --body), --assignees & --labels (plural)
tea issues create --title "Bug" --description "..." --labels bug --assignees alice

# PRs — review comments are POSITIONAL, not via --comment
tea pulls create --title "Add X" --base main --head feature/x --description "$(cat pr.md)"
tea pulls approve 20 "LGTM"
tea pulls merge 20 --style squash

# Releases — tag positional, --note OR --note-file (only on create)
tea releases create v1.0.0 --title "v1.0.0" --note-file CHANGELOG.md \
  --asset dist/linux --asset dist/darwin

# Labels — name via --name, identification by --id
tea labels create --name bug --color "#ff0000"
tea labels update --id 7 --name regression

# Repos — delete uses --owner + --name + --force
tea repos delete --owner myorg --name myrepo --force

# Clone — top-level helper, NOT `tea repos clone`
tea clone owner/repo ./dir

# Actions — secret/variable values are POSITIONAL, not --value
tea actions secrets create DEPLOY_TOKEN "$(cat ~/.token)"
tea actions variables set BUILD_VERSION "1.2.3"
tea actions runs logs 12345 --job 7              # --job flag, not positional

# Time tracking — both args POSITIONAL: <issue> <duration>
tea times add 42 1h30m

# Generic API
tea api /repos/{owner}/{repo}/issues -X POST -f title="..." -f body="..."

Full command reference

See references/commands.md for the full verified surface — every common subcommand, with flag corrections vs. older docs.

Known doc pitfalls (corrected in references/)

Documentation found in older copies of this skill (or from other sources) often contained these errors:

• tea issues create --body "..." — there is no --body; use --description/-d.
• tea pulls approve 20 --comment "LGTM" — comment is positional: tea pulls approve 20 "LGTM".
• tea pulls review 20 --state comment — tea pulls review is interactive only; no --state/--comment flags.
• tea repos delete owner/repo --yes — uses --owner/--name/--force.
• tea repos clone … — doesn't exist; use tea clone ….
• tea labels delete bug — tea labels delete --id <int>, no positional name.
• tea milestones create "v2.0.0" — title is via --title flag.
• tea actions secrets create FOO --value "bar" — value is positional.
• tea actions runs logs 12345 1 — second arg is --job 1.
• tea actions runs rerun 12345 — no such subcommand (use MCP actions_run_write method rerun_run).
• tea attachments … — no such top-level command (use tea releases assets …).
• tea times add 42 --time 2h --message … — tea times add <issue> <duration>, both positional, no flags.
• tea logins env / tea login env — does not exist.
• tea open <issue-number> / tea open pulls — tea open accepts no positional args per its --help; will also hang in headless environments.

Installation

If tea isn't already on PATH:

# macOS
brew install tea

# Linux
curl -sL https://dl.gitea.io/tea/main/tea-main-linux-amd64 -o /usr/local/bin/tea
chmod +x /usr/local/bin/tea

# From source
go install code.gitea.io/tea@latest