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

---
name: tea
description: 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

```bash
tea whoami
```

### Login to a Gitea instance

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

Or use interactive OAuth:
```bash
tea login add --url https://git.ajet.fyi --oauth
```

### List configured logins

```bash
tea login ls
```

## Common Operations

### Pull Requests

**List PRs:**
```bash
tea pr ls
tea pr ls --state open
tea pr ls --state closed
```

**Create a PR:**
```bash
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:**
```bash
tea pr <number>
tea pr 42 --comments
```

**Checkout a PR locally:**
```bash
tea pr checkout 42
tea pr co 42 --branch  # Create local branch
```

**Review a PR:**
```bash
tea pr review 42
tea pr approve 42
tea pr reject 42
```

**Merge a PR:**
```bash
tea pr merge 42
tea pr merge 42 --style squash
tea pr merge 42 --style rebase
```

**Close a PR:**
```bash
tea pr close 42
```

### Issues

**List issues:**
```bash
tea issues ls
tea issues ls --state open
tea issues ls --labels bug,urgent
tea issues ls --milestone v1.0
```

**Create an issue:**
```bash
tea issues create --title "Bug: Something broken" --description "Details here"
tea issues create -t "Title" -d "Description" --labels bug,priority
```

**Edit an issue:**
```bash
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:**
```bash
tea issues close 42
tea issues reopen 42
```

### Comments

**Add a comment to an issue or PR:**
```bash
tea comment 42 "This is my comment"
```

### Releases

**List releases:**
```bash
tea releases ls
```

**Create a release:**
```bash
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:**
```bash
tea releases delete v1.0.0 --confirm
```

### Labels

**List labels:**
```bash
tea labels ls
```

**Create a label:**
```bash
tea labels create --name bug --color "#ff0000" --description "Bug reports"
```

### Milestones

**List milestones:**
```bash
tea milestones ls
tea milestones ls --state open
```

**Create a milestone:**
```bash
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:**
```bash
tea milestones issues add v1.0 42
```

### Repositories

**Show repo details:**
```bash
tea repo
```

**Clone a repository:**
```bash
tea clone owner/repo
tea clone owner/repo --depth 1
```

### Branches

**List branches:**
```bash
tea branches ls
```

### Notifications

**Check notifications:**
```bash
tea notifications
tea notifications --mine
```

### Open in Browser

**Open repo in browser:**
```bash
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:**
```bash
git remote -v
# Should show a remote pointing to your Gitea instance (e.g., git.ajet.fyi)
```

**If no Gitea remote exists, add one:**
```bash
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:

```bash
tea pr ls --login my-gitea
```

### Output Formats

Control output format:

```bash
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:**
```bash
tea pr ls --author username
```

**Search issues by keyword:**
```bash
tea issues ls --keyword "search term"
```

**Filter by labels:**
```bash
tea issues ls --labels bug,urgent
```

**Filter by milestone:**
```bash
tea issues ls --milestone v1.0
```

**Filter by assignee:**
```bash
tea issues ls --assignee username
```

### Pagination

```bash
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:**

```bash
# 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:
   ```bash
   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:
   ```bash
   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

```bash
tea --help
tea <command> --help
tea man
```