gong-fu-cha/skills/tea/SKILL.md

name	description
tea	Use Gitea's tea CLI to manage issues, PRs, releases, and other repository operations. Works with git.ajet.fyi and other Gitea instances.

Gitea Tea CLI

When to Use This Skill

Use this skill when you need to:

• Create or manage pull requests without leaving the terminal
• Create, update, or close issues
• Review pull requests and approve/reject changes
• Create releases and manage release assets
• Manage labels and milestones
• Check notifications from Gitea
• Clone repositories from Gitea instances

How It Works

The tea CLI tool interacts directly with Gitea instances via their API. It automatically detects repository context from your current directory and uses stored login credentials.

⚠️ Critical Requirements

BEFORE running any tea commands, you MUST:

1. Be inside a git repository directory - Navigate to a repository with cd /path/to/repo
2. Have a Gitea remote configured - The repository must have a remote pointing to your Gitea instance (e.g., git.ajet.fyi)
3. Be authenticated - Run tea whoami to verify you're logged in

Most tea commands will FAIL if you're not in a repository directory with a Gitea remote. The --repo flag exists but is unreliable for many operations.

Setup

Check if logged in

tea whoami

Login to a Gitea instance

tea login add --url https://git.ajet.fyi --token YOUR_TOKEN

Or use interactive OAuth:

tea login add --url https://git.ajet.fyi --oauth

List configured logins

tea login ls

Common Operations

Pull Requests

List PRs:

tea pr ls
tea pr ls --state open
tea pr ls --state closed

Create a PR:

tea pr create --title "Feature: Add new capability" --description "Detailed description"
tea pr create -t "Title" -d "Description" --base main --head feature-branch

View PR details:

tea pr <number>
tea pr 42 --comments

Checkout a PR locally:

tea pr checkout 42
tea pr co 42 --branch  # Create local branch

Review a PR:

tea pr review 42
tea pr approve 42
tea pr reject 42

Merge a PR:

tea pr merge 42
tea pr merge 42 --style squash
tea pr merge 42 --style rebase

Close a PR:

tea pr close 42

Issues

List issues:

tea issues ls
tea issues ls --state open
tea issues ls --labels bug,urgent
tea issues ls --milestone v1.0

Create an issue:

tea issues create --title "Bug: Something broken" --description "Details here"
tea issues create -t "Title" -d "Description" --labels bug,priority

Edit an issue:

tea issues edit 42 --title "New title"
tea issues edit 42 --add-labels bug,urgent
tea issues edit 42 --milestone v1.0

Close/Reopen issues:

tea issues close 42
tea issues reopen 42

Comments

Add a comment to an issue or PR:

tea comment 42 "This is my comment"

Releases

List releases:

tea releases ls

Create a release:

tea releases create --tag v1.0.0 --title "Version 1.0.0" --note "Release notes here"
tea releases create --tag v1.0.0 -t "v1.0.0" -n "Notes" --asset ./binary

Delete a release:

tea releases delete v1.0.0 --confirm

Labels

List labels:

tea labels ls

Create a label:

tea labels create --name bug --color "#ff0000" --description "Bug reports"

Milestones

List milestones:

tea milestones ls
tea milestones ls --state open

Create a milestone:

tea milestones create --title "v1.0" --description "First release"
tea milestones create -t "v1.0" -d "Description" --deadline 2026-12-31

Add issue to milestone:

tea milestones issues add v1.0 42

Repositories

Show repo details:

tea repo

Clone a repository:

tea clone owner/repo
tea clone owner/repo --depth 1

Branches

List branches:

tea branches ls

Notifications

Check notifications:

tea notifications
tea notifications --mine

Open in Browser

Open repo in browser:

tea open
tea open 42  # Open issue/PR #42

Context and Options

Repository Context

REQUIREMENT: Tea requires you to be in a git repository directory with a Gitea remote configured. It reads .git/config to determine the repository context.

Verify your repository has a Gitea remote:

git remote -v
# Should show a remote pointing to your Gitea instance (e.g., git.ajet.fyi)

If no Gitea remote exists, add one:

git remote add origin https://git.ajet.fyi/owner/repo.git

The --repo flag is unreliable - While tea provides a --repo owner/repo flag, many commands don't work correctly with it. Always run tea from within the repository directory.

Login Selection

Use a specific Gitea login:

tea pr ls --login my-gitea

Output Formats

Control output format:

tea pr ls --output json
tea pr ls --output yaml
tea pr ls --output csv
tea issues ls -o table  # Default

Advanced Usage

Filtering and Searching

Filter PRs by author:

tea pr ls --author username

Search issues by keyword:

tea issues ls --keyword "search term"

Filter by labels:

tea issues ls --labels bug,urgent

Filter by milestone:

tea issues ls --milestone v1.0

Filter by assignee:

tea issues ls --assignee username

Pagination

tea pr ls --page 2
tea pr ls --limit 50

Important Notes

• Repository context REQUIRED: You MUST run tea from within a git repository directory that has a Gitea remote configured. Commands will fail otherwise.
• Verify before running: Always check git remote -v to ensure you have a Gitea remote before running tea commands
• Navigate to repo first: Use cd /path/to/repo to change to your repository directory before running tea
• Multiple logins: You can configure multiple Gitea instances with tea login add
• Default login: Set a default login with tea login default
• Token permissions: Ensure your access token has appropriate scopes for the operations you need
• Help available: Run tea <command> --help for detailed options
• Manual pages: Use tea man for comprehensive documentation

Typical Workflows

Pre-flight Checklist

BEFORE running any tea workflow, verify:

# 1. Check you're in a git repository
pwd  # Should show your repo directory
ls .git  # Should exist

# 2. Verify Gitea remote is configured
git remote -v  # Should show git.ajet.fyi or your Gitea instance

# 3. Check authentication
tea whoami  # Should show your username

If any of these fail, fix them before proceeding with tea commands.

Creating a PR from a feature branch

1. Verify you're in the correct repository directory
2. Make changes and commit
3. Push to remote
4. Create PR:

   tea pr create -t "Feature: New capability" -d "Description of changes"
   

5. Wait for review or review yourself

Reviewing and merging a PR

1. Navigate to repository directory: cd /path/to/repo
2. List PRs: tea pr ls
3. Checkout locally: tea pr checkout 42
4. Test the changes
5. Approve: tea pr approve 42
6. Merge: tea pr merge 42 --style squash

Creating a release

1. Navigate to repository directory: cd /path/to/repo
2. Ensure you're on the right branch/commit
3. Create release:

   tea releases create --tag v1.0.0 --title "Version 1.0.0" \
     --note "Release notes" --asset ./binary
   

Managing issues

1. Navigate to repository directory: cd /path/to/repo
2. List open issues: tea issues ls --state open
3. View specific issue: tea issues 42
4. Add comment: tea comment 42 "Working on this"
5. Close when done: tea issues close 42

Getting Help

tea --help
tea <command> --help
tea man