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.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

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

Set up a token-based login non-interactively:

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

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

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