skills/gitea-tea/SKILL.md

---
name: gitea-tea
description: 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.)
version: 1.0.0
---

# Gitea CLI (tea)

## Overview

Official command-line interface for Gitea. Manage issues, PRs, releases, repos, Actions, webhooks, and more from terminal.

## Instructions

1. **Verify authentication**: Run `tea whoami` to confirm login
2. **Check context**: Run in git repo for auto-detection, or use `--repo owner/repo` or `--login <host>`
3. **Use non-interactive mode**: Always use `--output` flag and provide all arguments
4. **Choose operation**: See command reference sections below

## Installation

```bash
# macOS
brew install tea

# Linux (binary)
curl -sL https://dl.gitea.io/tea/main/tea-main-linux-amd64 -o tea
chmod +x tea && sudo mv tea /usr/local/bin/

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

## Common Flags

These flags are available on most commands:

| Flag | Alias | Description |
|------|-------|-------------|
| `--login` | `-l` | Use a specific Gitea login/instance |
| `--repo` | `-r` | Specify repository (`owner/repo`) |
| `--remote` | `-R` | Discover login from git remote |
| `--output` | `-o` | Output format: `simple`, `table`, `csv`, `tsv`, `yaml`, `json` |
| `--page` | `-p` | Page number for list commands (default: 1) |
| `--limit` | `-lm` | Items per page (default: 30) |

## Authentication

```bash
# Token-based login (recommended for CI/AI agents)
tea login add \
  --name mygitea \
  --url https://gitea.example.com \
  --token <your-token>

# Or use environment variables
export GITEA_SERVER_URL=https://gitea.example.com
export GITEA_SERVER_TOKEN=<your-token>

# OAuth2 interactive login
tea login add --oauth --name mygitea --url https://gitea.example.com

# SSH agent login (requires running ssh-agent with key loaded)
tea login add --ssh-agent-key <fingerprint> --ssh-agent-principal <principal>

# List logins
tea login list

# Set default
tea login default gitea.example.com

# Refresh OAuth token
tea login oauth-refresh [login-name]

# Delete login
tea login delete gitea.example.com

# Verify
tea whoami
```

## Issues

### List Issues
```bash
# Open issues in current repo
tea issues list

# All issues (including closed)
tea issues list --state all

# Filter by milestone
tea issues list --milestone "v1.0.0"

# Filter by assignee and labels
tea issues list --assignee username --label bug,critical

# From specific repo
tea issues list --repo owner/repo --login gitea.com
```

### View Issue
```bash
# View issue with comments
tea issue 42

# Without comments
tea issue 42 --comments=false

# Open in browser
tea open 42
```

### Create Issue
```bash
# With arguments
tea issues create \
  --title "Fix authentication bug" \
  --body "Users cannot login with special characters" \
  --label bug,security \
  --assignee developer1 \
  --milestone "v1.2.0"

# From file
tea issues create \
  --title "Feature request" \
  --body "$(cat feature-request.md)"
```

### Modify Issues
```bash
# Close issue
tea issues close 42

# Reopen issue
tea issues reopen 42

# Edit issue
tea issues edit 42 \
  --title "Updated title" \
  --assignee newdev \
  --add-labels "enhancement"
```

## Pull Requests

### List PRs
```bash
# Open PRs
tea pulls

# Closed PRs
tea pulls --state closed

# Filter by reviewer and labels
tea pulls --reviewer username --label "needs-review"
```

### View PR
```bash
# View PR details
tea pr 15

# Without comments
tea pr 15 --comments=false

# Open in browser
tea open 15
```

### Create PR
```bash
# With arguments
tea pulls create \
  --title "Implement user authentication" \
  --description "Adds OAuth and JWT support" \
  --base main \
  --head feature/auth \
  --assignee reviewer1,reviewer2 \
  --label "enhancement"

# Description from file
tea pulls create \
  --title "Major refactor" \
  --description "$(cat pr-description.md)"
```

### Checkout PR
```bash
# Checkout PR locally
tea pulls checkout 20

# Custom branch name
tea pulls checkout 20 pr-20-custom-name

# Clean up checked out PRs
tea pulls clean
```

### Review & Merge
```bash
# Approve PR
tea pulls approve 20 --comment "LGTM!"

# Request changes
tea pulls reject 20 --comment "Please add tests"

# Leave comment
tea pulls review 20 \
  --state comment \
  --comment "Consider refactoring this section"

# Merge PR (squash)
tea pulls merge 20 --style squash --message "feat: implement auth"

# Merge PR (rebase)
tea pulls merge 20 --style rebase

# Close PR
tea pulls close 20

# Reopen PR
tea pulls reopen 20
```

## Releases

### List Releases
```bash
tea releases list
tea releases list --limit 10
tea releases list --repo owner/project
```

### Create Release
```bash
# Basic release
tea releases create v1.0.0 \
  --title "Version 1.0.0" \
  --note "First stable release"

# From changelog file
tea releases create v1.2.0 \
  --title "Version 1.2.0" \
  --note-file CHANGELOG.md

# Draft release
tea releases create v2.0.0-beta \
  --title "Beta Release" \
  --draft \
  --note "Beta for testing"

# With assets
tea releases create v1.1.0-rc1 \
  --title "Release Candidate 1" \
  --prerelease \
  --asset dist/binary-linux-amd64 \
  --asset dist/binary-darwin-amd64

# Create tag + release
tea releases create v1.3.0 \
  --target main \
  --title "Version 1.3.0" \
  --note "New features"
```

### Edit/Delete Release
```bash
# Update release
tea releases edit v1.0.0 \
  --title "Version 1.0.0 - Updated" \
  --note-file NEW-NOTES.md

# Publish draft
tea releases edit v2.0.0 --draft=false

# Delete release
tea releases delete v0.9.0
tea releases delete v1.0.0-beta --confirm
```

## Labels

```bash
# List labels
tea labels list
tea labels list --repo owner/project
tea labels list --save  # Save labels to file

# Create label
tea labels create bug \
  --color "#ff0000" \
  --description "Something isn't working"

tea labels create enhancement \
  --color "0,255,0" \
  --description "New feature"

# Update label
tea labels update bug --color "#cc0000"
tea labels update old-name --name new-name

# Delete label
tea labels delete bug
```

## Milestones

```bash
# List milestones
tea milestones list
tea milestones list --state open
tea milestones list --state closed

# View milestone issues
tea milestones issues "v1.0.0"
tea milestones issues "v1.0.0" --kind pull  # Only PRs
tea milestones issues "v1.0.0" --state all

# Add issue/PR to milestone
tea milestones issues add "v1.0.0" 42

# Remove issue/PR from milestone
tea milestones issues remove "v1.0.0" 42

# Create milestone
tea milestones create "v2.0.0" \
  --description "Major version release" \
  --deadline "2024-12-31"

# Close milestone
tea milestones close "v1.0.0"

# Reopen milestone
tea milestones reopen "v1.0.0"

# Delete milestone
tea milestones delete "v0.9.0"
```

## Repositories

```bash
# List repos
tea repos list
tea repos list --org myorg
tea repos list --watched  # Watched repos
tea repos list --starred  # Starred repos
tea repos list --type fork  # Filter: fork, mirror, source
tea repos list --output yaml

# Search repos
tea repos search "keyword" --login gitea.com

# View repo details
tea repos owner/repo

# Create repo
tea repos create --name myrepo --private --init
tea repos create \
  --name myrepo \
  --owner myorg \
  --description "My project" \
  --private \
  --init \
  --gitignores Go \
  --license MIT

# Create from template
tea repos create-from-template \
  --template owner/template-repo \
  --name new-repo

# Fork repo
tea repos fork --repo owner/repo
tea repos fork --repo owner/repo --owner myorg

# Edit repo
tea repos edit owner/repo \
  --description "Updated description" \
  --private=false

# Delete repo
tea repos delete owner/repo

# Clone repo (without git)
tea repos clone owner/repo
tea repos clone owner/repo ./target-dir
tea repos clone gitea.com/owner/repo  # With host
```

## SSH Keys

```bash
# List your SSH keys
tea ssh-keys list

# Add SSH key from file
tea ssh-keys add ~/.ssh/id_ed25519.pub
tea ssh-keys add ~/.ssh/id_ed25519.pub --title "Work laptop"

# Delete SSH key by ID
tea ssh-keys delete 123 --confirm
```

## Actions / CI/CD

### Workflow Runs
```bash
# List workflow runs
tea actions runs list
tea actions runs list --status success --branch main
tea actions runs list --event push --since "24h"
tea actions runs list --actor username --limit 50

# View run details
tea actions runs view 12345
tea actions runs view 12345 --jobs=false

# View run logs
tea actions runs logs 12345 1  # run ID, job ID

# Cancel run
tea actions runs cancel 12345

# Rerun run
tea actions runs rerun 12345

# Delete run
tea actions runs delete 12345 --confirm
```

### Workflows
```bash
# List workflows
tea actions workflows list

# View workflow file
tea actions workflows view .gitea/workflows/ci.yml

# Enable/disable workflow
tea actions workflows enable .gitea/workflows/ci.yml
tea actions workflows disable .gitea/workflows/ci.yml

# Dispatch workflow
tea actions workflows dispatch .gitea/workflows/ci.yml --ref main
```

### Actions Secrets
```bash
# List secrets
tea actions secrets list

# Create secret
tea actions secrets create DEPLOY_TOKEN --value "secret-value"
tea actions secrets create DB_PASSWORD --file /path/to/password.txt
echo "secret-value" | tea actions secrets create API_KEY --stdin

# Delete secret
tea actions secrets delete DEPLOY_TOKEN --confirm
```

### Actions Variables
```bash
# List variables (get specific one)
tea actions variables list --name BUILD_VERSION

# Set variable
tea actions variables set BUILD_VERSION --value "1.2.3"
tea actions variables set CONFIG --file /path/to/config.json

# Delete variable
tea actions variables delete BUILD_VERSION --confirm
```

## Webhooks

```bash
# List webhooks
tea webhooks list
tea webhooks list --repo owner/repo

# Create webhook
tea webhooks create https://example.com/webhook \
  --type gitea \
  --secret mysecret \
  --events push,pull_request \
  --active

# Update webhook
tea webhooks update 1 \
  --url https://new-url.com/hook \
  --secret newsecret \
  --events push

# Enable/disable webhook
tea webhooks update 1 --active
tea webhooks update 1 --inactive

# Delete webhook
tea webhooks delete 1 --confirm
```

## Attachments

```bash
# List attachments
tea attachments list 42  # issue/PR number

# Create attachment
tea attachments create 42 --file ./artifact.zip

# Delete attachment
tea attachments delete 42 --id 1 --confirm
```

## Time Tracking

```bash
# List time entries
tea times list
tea times list --issue 42
tea times list --user username
tea times list --from "2024-01-01" --until "2024-12-31"

# Add time
tea times add 42 --time "2h"
tea times add 42 --time "1h30m" --message "Implemented auth logic"

# Delete entry
tea times delete 42 --id 123
```

## Notifications

```bash
# List notifications (current repo)
tea notifications list

# List all notifications
tea notifications list --mine

# Filter by type
tea notifications list --types issue,pull

# Filter by state
tea notifications list --states unread,pinned

# Mark as read
tea notifications read  # All filtered
tea notifications read 123  # Specific ID

# Mark as unread
tea notifications unread 123

# Pin/unpin
tea notifications pin 123
tea notifications unpin 123
```

## Organizations

```bash
# List organizations
tea organizations list

# View organization details
tea organizations view myorg

# Create organization
tea organizations create myorg

# Delete organization
tea organizations delete myorg --confirm
```

## Branches

```bash
# List branches
tea branches list
tea branches list --output json

# View branch details
tea branches main

# Protect branch
tea branches protect main

# Unprotect branch
tea branches unprotect main

# Rename branch
tea branches rename old-name new-name
```

## Comments

```bash
# Add comment to issue or PR
tea comment 42 "This is my comment"

# From specific repo
tea comment 42 "Comment text" --repo owner/repo
```

## Open in Browser

```bash
# Open issue/PR by number
tea open 42

# Open specific pages
tea open issues
tea open pulls
tea open releases
tea open commits
tea open branches
tea open wiki
tea open activity
tea open settings
tea open labels
tea open milestones
```

**Warning:** `tea open` opens a browser window. It will hang indefinitely in headless/agent environments — do not use in non-interactive contexts.

## Admin (requires admin access)

### Users
```bash
# List users
tea admin users list
tea admin users list --output json
tea admin users list --page 2 --limit 50

# Create user
tea admin users create \
  --username newuser \
  --email newuser@example.com \
  --password "SecurePass123!" \
  --full-name "New User" \
  --admin \
  --visibility public

# Edit user
tea admin users edit username \
  --email newemail@example.com \
  --full-name "Updated Name" \
  --admin \
  --no-admin \
  --restricted \
  --active \
  --visibility private

# Delete user
tea admin users delete username --confirm
```

## Generic API Command

Make authenticated requests directly to the Gitea API:

```bash
# GET request (default)
tea api /user

# POST with JSON body
tea api /repos/owner/repo/issues \
  --method POST \
  --data '{"title":"New issue","body":"Description"}'

# POST with form fields
tea api /repos/owner/repo/issues \
  --method POST \
  --field title="New issue" \
  --field body="Description"

# With headers
tea api /repos/owner/repo \
  --header "X-Custom-Header: value"

# Include response headers in output
tea api /user --include

# Write response to file
tea api /repos/owner/repo/archive --output release.zip

# Placeholder expansion (from git context)
tea api /repos/{owner}/{repo}/actions/runs --login gitea.com
```

## Non-Interactive Mode (AI Agents)

**IMPORTANT:** When using tea in AI agent environments (no TTY), avoid interactive prompts:

```bash
# Use --output to disable interactive mode
tea issues --output simple
tea pulls --output json

# Provide ALL required arguments upfront
tea issue create --title "Bug title" --body "Description here"
tea pr create --title "PR title" --head feature-branch --base main

# Use -y or --yes for confirmations
tea pr merge 5 --yes
tea releases delete v0.9.0 --yes
tea admin users delete username --yes

# Set default login to avoid prompts
tea login default <login-name>

# Always specify --login when not in a git repo
tea issues list --login gitea.com --repo owner/repo
```

**Always prefer explicit flags over interactive prompts.**

## Guidelines

### Do
- Use `--output simple` or `--output json` for non-interactive mode
- Provide all required arguments upfront to avoid prompts
- Run `tea whoami` to verify authentication before operations
- Use `tea open <number>` to quickly view in browser
- Specify `--login <host>` when operating outside a git repository

### Don't
- Use interactive commands in AI agent context (no TTY)
- Forget `--repo owner/repo` when outside git repository
- Skip `--yes` flag for destructive operations in scripts
- Use `tea login add` interactively (configure beforehand)

## Examples

### Example: Feature Branch → PR
```bash
git checkout -b feature/new-feature
# ... make changes ...
git add . && git commit -m "feat: add new feature"
git push -u origin feature/new-feature
tea pulls create --title "Add new feature" --base main --head feature/new-feature
```

### Example: Review & Merge PR
```bash
tea pulls checkout 20
# ... review code ...
tea pulls approve 20 --comment "LGTM!"
tea pulls merge 20 --style squash
```

### Example: Create Release with Assets
```bash
git tag v1.0.0
git push origin v1.0.0
tea releases create v1.0.0 \
  --title "v1.0.0" \
  --note-file CHANGELOG.md \
  --asset dist/app-linux \
  --asset dist/app-darwin
```

### Example: Manage Actions Secrets
```bash
# Deploy to staging
tea actions secrets create STAGING_DEPLOY_TOKEN \
  --value "$(cat ~/secrets/staging-token)" \
  --repo myorg/myrepo

# Trigger workflow
tea actions workflows dispatch .gitea/workflows/deploy.yml --ref staging \
  --repo myorg/myrepo
```

### Example: Admin User Management
```bash
# Create service account
tea admin users create ci-bot \
  --email ci-bot@mycompany.com \
  --password "$(openssl rand -base64 24)" \
  --restricted \
  --no-must-change-password

# Deactivate user
tea admin users edit username --prohibit-login
```