tea-skill/tea/SKILL.md

name, description

name

description

tea

Full operability with the `tea` CLI — the official command-line tool for Gitea. Use this skill whenever the user wants to interact with a Gitea instance: managing issues, pull requests, repos, releases, branches, labels, milestones, notifications, actions (CI/CD), webhooks, organizations, time tracking, or making raw API calls. Trigger on any mention of tea CLI, Gitea operations, or self-hosted git workflows even if the user doesn't explicitly say "tea" — e.g., "open a PR on my Gitea", "list issues on my self-hosted git", "create a release", "check CI runs".

tea — Gitea CLI

tea is the official CLI for Gitea. It handles everything: issues, PRs, repos, releases, CI actions, webhooks, and more. It can also make raw authenticated API calls for anything not covered by a dedicated subcommand.

Quick reference of all commands: see references/commands.md

---

How tea finds context

When run inside a git repo directory, tea automatically detects:

• Which Gitea instance to talk to (from the git remote URL)
• Which repo to operate on (owner/name from the remote)

This means most commands just work in-context. Flags to override when needed:

• --repo owner/name or -r — target a different repo
• --login name or -l — use a specific saved login
• --remote name or -R — pick which git remote to use for login discovery

---

Authentication

Logins are stored in ~/.config/tea/config.yml.

tea logins list                          # show saved logins
tea logins add                           # add a new Gitea server (interactive)
tea logins add --url https://git.example.com --token TOKEN --name myserver
tea logins default --name myserver       # set default login
tea logins edit --name myserver          # update an existing login
tea logins delete --name myserver        # remove a login
tea whoami                               # show current logged-in user

---

Issues

tea issues                               # list open issues (current repo)
tea issues list --state all              # all states: open, closed, all
tea issues list --assignee me --label bug
tea issues 42                            # show issue #42 with details
tea issues create                        # interactive create
tea issues create --title "Bug" --body "Description" --label bug --assignee alice
tea issues edit 42 --title "New title" --assignee bob
tea issues close 42
tea issues reopen 42
tea comment 42 "This is a comment"       # add a comment

Fields printable with --fields: index,title,state,author,milestone,labels,body,comments,created,updated

---

Pull Requests

tea pulls                                # list open PRs
tea pulls 7                              # show PR #7 in detail
tea pulls create --title "feat: X" --head feature-branch --base main
tea pulls checkout 7                     # check out PR #7 locally
tea pulls review 7                       # interactive review
tea pulls approve 7                      # approve
tea pulls reject 7                       # request changes
tea pulls merge 7                        # merge
tea pulls edit 7 --assignee alice --milestone v2
tea pulls close 7
tea pulls reopen 7
tea pulls clean 7                        # delete local + remote branch after close

---

Repositories

tea repos                                # list your repos
tea repos list --owner myorg            # list org repos
tea repos list --starred                # your starred repos
tea repos search "keyword"              # search across the instance
tea repos create --name myrepo --private
tea repos fork owner/repo               # fork a repo
tea repos migrate --url https://github.com/owner/repo --name localname
tea repos edit --private=false          # make current repo public
tea repos delete owner/repo             # delete (irreversible — confirm with user)
tea clone owner/repo                    # clone without needing local git

---

Branches

tea branches                            # list branches
tea branches main                       # show branch detail
tea branches protect main               # protect a branch
tea branches unprotect main

---

Labels

tea labels                              # list labels
tea labels create --name "bug" --color "#ee0701" --description "Something broken"
tea labels update --name "bug" --color "#cc0000"
tea labels delete --name "bug"
tea labels --save                       # save label set to file (for reuse)

---

Milestones

tea milestones                          # list open milestones
tea milestones create --title "v2.0" --due "2025-12-31"
tea milestones close "v1.0"
tea milestones reopen "v1.0"
tea milestones delete "v1.0"
tea milestones issues "v2.0"            # list issues/PRs in a milestone

---

Releases

tea releases                            # list releases
tea releases create --tag v1.0.0 --title "v1.0.0" --note "Release notes"
tea releases create --tag v1.0.0 --draft --prerelease
tea releases edit v1.0.0 --note "Updated notes"
tea releases delete v1.0.0

# Release assets
tea releases assets list --tag v1.0.0
tea releases assets create --tag v1.0.0 --asset ./build/app.tar.gz
tea releases assets delete --tag v1.0.0 --asset app.tar.gz

---

Actions (CI/CD)

# Workflow runs
tea actions runs                        # list recent runs
tea actions runs view 123               # view run details
tea actions runs logs 123               # view run logs
tea actions runs cancel 123             # cancel a run

# Secrets
tea actions secrets list
tea actions secrets set SECRET_NAME --value "secret-value"
tea actions secrets delete SECRET_NAME

# Variables
tea actions variables list
tea actions variables set VAR_NAME --value "value"
tea actions variables delete VAR_NAME

# Workflows
tea actions workflows list

---

Notifications

tea notifications                       # unread + pinned notifications (current repo)
tea notifications --mine                # all repos
tea notifications read                  # mark all as read
tea notifications read 42               # mark specific notification as read
tea notifications pin 42
tea notifications unpin 42

---

Organizations

tea orgs                                # list your orgs
tea orgs create --name myorg
tea orgs delete myorg

---

Webhooks

tea webhooks list
tea webhooks list --org myorg           # org webhooks
tea webhooks create --url https://hook.example.com --events push,pull_request
tea webhooks update <id> --active=false
tea webhooks delete <id>

---

Time Tracking

tea times                               # list times on current repo
tea times --mine                        # all your tracked time across repos
tea times add 42 "1h30m"               # track time on issue #42
tea times delete <time-id>
tea times reset 42                      # reset all tracked time on issue #42
tea times list --total                  # show total at end

---

Raw API Access

For anything not covered by a subcommand, tea api makes authenticated calls:

tea api /repos/{owner}/{repo}/topics                          # GET (default)
tea api -X POST /repos/{owner}/{repo}/topics -f topic=golang  # POST with field
tea api -X DELETE /repos/{owner}/{repo}/releases/123
tea api -d '{"body":"hello"}' /repos/{owner}/{repo}/issues/1/comments
tea api '/repos/{owner}/{repo}/issues?state=open&type=pulls'  # quote URLs with ?
tea api --include /user                                        # include response headers

Placeholders {owner} and {repo} are filled from the current git context.

---

Helpers

tea open                                # open current repo in browser
tea clone owner/repo ./dest             # clone a repo (no local git needed)

---

Output formats

All list commands support --output / -o:

• table (default) — formatted table
• simple — minimal whitespace output
• csv / tsv — for scripts/pipes
• json / yaml — for programmatic use

---

Tips

• Run tea <command> --help at any time for full flag details
• Use --debug / --vvv on any command to see API calls being made
• tea api is your escape hatch — any Gitea API endpoint is reachable
• For multi-instance setups, set --login explicitly or configure a default with tea logins default