# `tea` Command Reference

Verified against `tea` v0.14.1. When in doubt, run `tea <command> --help`. Flags below are exhaustive only for the operations agents need most often.

## Conventions

- `--login`/`-l`, `--repo`/`-r`, `--remote`/`-R` are available on most subcommands. Outside a git repo, pass `--repo owner/name` and (if you have multiple logins) `--login <name>`.
- `--output`/`-o` accepts: `simple`, `table`, `csv`, `tsv`, `yaml`, `json`. Use `json` for parsing, `simple` for terse non-interactive output.
- `--limit`/`--lm` (yes, double-dash on the short form), `--page`/`-p` for paging.
- Destructive ops normally require `--confirm`/`-y`. **Exceptions:** `tea repos delete` uses `--force`/`-f`; `tea labels delete` / `tea milestones delete` / `tea organizations delete` have no confirm flag (they just delete).

## Auth

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

# Or via env vars (read on first command)
export GITEA_SERVER_URL=https://gitea.example.com
export GITEA_SERVER_TOKEN=<token>

tea logins list
tea logins default <login-name>     # set default
tea logins delete <login-name>
tea whoami                          # verify
```

OAuth/SSH-agent logins exist (`tea logins add --oauth …`, `--ssh-agent-key …`); they are interactive and not useful in agent contexts.

> `tea logins env` does **not** exist. The original wiki doc referenced it — ignore.

## Issues

```bash
# List
tea issues list
tea issues list --state all --labels bug,critical --assignee alice --milestone v1.0.0
tea issues list --repo owner/repo --login gitea.example.com

# View (positional <index>)
tea issues 42                       # detail view
tea issue 42 --comments=false       # without comments

# Create — note: --description (NOT --body), --assignees (plural), --labels (plural)
tea issues create \
  --title "Fix authentication bug" \
  --description "Users cannot login with special characters" \
  --labels bug,security \
  --assignees alice,bob \
  --milestone v1.2.0

# Description from file
tea issues create --title "Feature request" --description "$(cat req.md)"

# Edit — add/remove labels are separate flags
tea issues edit 42 \
  --title "Updated title" \
  --add-assignees bob \
  --add-labels enhancement \
  --remove-labels stale

# State
tea issues close 42
tea issues reopen 42
```

## Pull requests

```bash
# List
tea pulls list
tea pulls list --state closed
# Note: --reviewer / --label do NOT exist on pulls list; filter client-side or via API.

# View
tea pulls 15
tea pr 15 --comments=false

# Create — same flag conventions as issues create
tea pulls create \
  --title "Implement OAuth" \
  --description "$(cat pr.md)" \
  --base main --head feature/auth \
  --assignees reviewer1,reviewer2 \
  --labels enhancement \
  --allow-maintainer-edits

# Checkout (no custom branch-name positional; only --branch/-b to create one)
tea pulls checkout 20
tea pulls checkout 20 --branch
tea pulls clean 20                  # delete local + remote branches after merge

# Review — comment/reason are POSITIONAL, no --comment flag
tea pulls approve 20 "LGTM"
tea pulls reject 20 "Please add tests"
# Note: `tea pulls review <id>` is interactive — do not use in agent context.

# Merge
tea pulls merge 20 --style squash --title "feat: oauth" --message "Adds OAuth + JWT"
tea pulls merge 20 --style rebase
# Merge styles: merge, rebase, squash, rebase-merge

# State
tea pulls close 20
tea pulls reopen 20
```

## Releases

```bash
tea releases list
tea releases list --limit 10 --repo owner/repo

# Create — tag is positional; --target sets commitish; --note OR --note-file
tea releases create v1.0.0 \
  --title "Version 1.0.0" \
  --note "First stable release"

tea releases create v1.2.0 --title "v1.2.0" --note-file CHANGELOG.md
tea releases create v2.0.0-beta --title "Beta" --draft --note "For testing"
tea releases create v1.1.0-rc1 --title "RC1" --prerelease \
  --asset dist/binary-linux-amd64 --asset dist/binary-darwin-amd64
tea releases create v1.3.0 --target main --title "v1.3.0" --note "..."

# Edit — note that --note-file does NOT exist on edit (use --note only)
tea releases edit v1.0.0 --title "v1.0.0 — Updated" --note "$(cat NEW-NOTES.md)"
tea releases edit v2.0.0 --draft false       # publish

# Delete (--confirm/-y required)
tea releases delete v0.9.0 --confirm
tea releases delete v1.0.0-beta -y --delete-tag

# Release assets (NOT `tea attachments` — that command doesn't exist)
tea releases assets list v1.0.0
tea releases assets create v1.0.0 --file ./dist/binary.tar.gz
tea releases assets delete v1.0.0 --id 17 --confirm
```

## Labels

```bash
tea labels list
tea labels list --save              # dump to file

# Create — name via --name flag (NOT positional)
tea labels create --name bug --color "#ff0000" --description "Something isn't working"
tea labels create --name enhancement --color "0,255,0" --description "New feature"

# Update — by --id (NOT by name)
tea labels update --id 7 --color "#cc0000"
tea labels update --id 7 --name new-name

# Delete — by --id (NOT positional name; no --confirm)
tea labels delete --id 7
```

## Milestones

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

# Create — title via --title flag
tea milestones create --title v2.0.0 \
  --description "Major version" \
  --deadline 2025-12-31

# Manage issues/pulls in a milestone — positional <name> <index>
tea milestones issues v1.0.0
tea milestones issues v1.0.0 --kind pull --state all
tea milestones issues add v1.0.0 42
tea milestones issues remove v1.0.0 42

# State (positional name)
tea milestones close v1.0.0
tea milestones reopen v1.0.0
tea milestones delete v0.9.0        # no confirm flag
```

## Repositories

```bash
# List
tea repos list
tea repos list --owner myorg
tea repos list --watched
tea repos list --starred
tea repos list --type fork           # fork|mirror|source

# Search — positional <term>
tea repos search "keyword"
tea repos search "k8s" --topic --login gitea.example.com

# Create — fields via flags
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 --content --labels

# Fork — source via --repo, target owner via --owner
tea repos fork --repo owner/source
tea repos fork --repo owner/source --owner myorg

# Edit
tea repos edit --description "Updated" --private false

# Delete — via --name + --owner + --force (NOT positional owner/repo, NOT --yes)
tea repos delete --owner myorg --name myrepo --force

# Clone (NOT `tea repos clone`) — top-level helper, takes repo slug
tea clone owner/repo
tea clone owner/repo ./target-dir
tea clone gitea.example.com/owner/repo
tea clone --depth 1 owner/repo
```

## Branches

```bash
tea branches list
tea branches main                    # detail view (positional name)
tea branches protect main
tea branches unprotect main
tea branches rename old new
```

## Actions / CI/CD

### Workflow runs

```bash
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 alice --limit 50

tea actions runs view 12345
tea actions runs view 12345 --jobs              # show jobs table

# Logs — job is via --job flag (NOT a positional second arg)
tea actions runs logs 12345
tea actions runs logs 12345 --job 7
tea actions runs logs 12345 --job 7 --follow

# Cancel/delete (same subcommand; aliases: delete, remove, rm, cancel)
tea actions runs cancel 12345 --confirm
tea actions runs delete 12345 -y

# Note: `tea actions runs rerun` does NOT exist. Use the MCP `actions_run_write` tool
# (method="rerun_run") or the REST API.
```

### Workflows

```bash
tea actions workflows list
tea actions workflows view ci.yml
tea actions workflows enable ci.yml
tea actions workflows disable ci.yml

# Dispatch — workflow_dispatch event
tea actions workflows dispatch ci.yml --ref main
tea actions workflows dispatch ci.yml --ref staging --input env=prod --input version=1.2.3
tea actions workflows dispatch ci.yml --ref main --follow      # tail logs after dispatch
```

### Secrets

```bash
tea actions secrets list

# Create — value is POSITIONAL (NOT --value)
tea actions secrets create DEPLOY_TOKEN "secret-value"
tea actions secrets create DEPLOY_TOKEN --file /path/to/value.txt
echo "secret-value" | tea actions secrets create API_KEY --stdin

tea actions secrets delete DEPLOY_TOKEN --confirm
```

### Variables

```bash
tea actions variables list
tea actions variables list --name BUILD_VERSION

# Set — value is POSITIONAL (NOT --value)
tea actions variables set BUILD_VERSION "1.2.3"
tea actions variables set CONFIG --file /path/to/config.json

tea actions variables delete BUILD_VERSION --confirm
```

## Webhooks

```bash
tea webhooks list
tea webhooks list --repo owner/repo
tea webhooks list --org myorg
tea webhooks list --global

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

# Update — ID is positional
tea webhooks update 1 --url https://new.example.com/hook --events push
tea webhooks update 1 --active        # enable
tea webhooks update 1 --inactive      # disable

tea webhooks delete 1 --confirm
```

Webhook types: `gitea, gogs, slack, discord, dingtalk, telegram, msteams, feishu, wechatwork, packagist`.

## SSH keys

```bash
tea ssh-keys list

# Add — key file is positional
tea ssh-keys add ~/.ssh/id_ed25519.pub
tea ssh-keys add ~/.ssh/id_ed25519.pub --title "Work laptop"

# Delete — ID is positional, --confirm required
tea ssh-keys delete 123 --confirm
```

## Time tracking

```bash
tea times list
tea times list --from 2024-01-01 --until 2024-12-31 --total
tea times list --mine                # across all repos

# Add — both args POSITIONAL: <issue> <duration>. No --time, no --message.
tea times add 42 2h
tea times add 42 1h30m

tea times delete --id 123
tea times reset 42                   # reset all on an issue
```

## Notifications

```bash
tea notifications list                       # current repo
tea notifications list --mine                # across all repos
tea notifications list --types issue,pull
tea notifications list --states unread,pinned

tea notifications read                       # mark all filtered as read
tea notifications read 123                   # mark one
tea notifications unread 123
tea notifications pin 123
tea notifications unpin 123
```

## Organizations

```bash
tea organizations list
tea organizations view myorg
tea organizations create myorg --description "..." --visibility public
tea organizations delete myorg               # no confirm flag
```

## Comments

```bash
# Both args positional: <issue/pr index> [<body>]
tea comment 42 "This is my comment"
tea comment 42 "Comment text" --repo owner/repo
```

## Admin (requires admin token)

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

tea admin users create \
  --username newuser --email newuser@example.com \
  --password "$(openssl rand -base64 24)" \
  --full-name "New User" \
  --admin --visibility public

# Edit — note: there is no --no-admin or --no-restricted. Boolean flags work in one direction.
tea admin users edit newuser \
  --email new@example.com \
  --full-name "Updated Name" \
  --admin --restricted --active

tea admin users edit newuser --prohibit-login         # deactivate

tea admin users delete newuser --confirm
```

## Generic API helper

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

# Endpoint placeholders auto-expand from git context
tea api '/repos/{owner}/{repo}/actions/runs?status=success'

# POST with string fields
tea api /repos/{owner}/{repo}/issues -X POST \
  -f title="New issue" -f body="Description"

# POST with typed fields (numbers, booleans). Read value from file with @path; stdin with @-.
tea api /repos/{owner}/{repo}/labels -X POST \
  -F name="prio:high" -F color="#ff0000" -F exclusive=true

# Raw JSON body (mutually exclusive with -f/-F)
tea api /repos/{owner}/{repo}/issues -X POST \
  -d '{"title":"New","body":"..."}'

tea api /repos/{owner}/{repo}/archive -o release.zip       # write body to file
tea api /user -i                                            # include status + headers (to stderr)
tea api /repos/{owner}/{repo} -H "X-Custom: value"
```

## Open in browser

```bash
tea open                             # current repo
```

> `tea open` opens a browser window. It will **hang indefinitely** in headless/agent environments. The previous skill version listed `tea open <issue-number>`, `tea open pulls`, etc. — those positional forms do not appear in `tea open --help`; do not rely on them.

## Common end-to-end recipes

### Feature branch → PR
```bash
git checkout -b feature/x
# ... commits ...
git push -u origin feature/x
tea pulls create --title "Add X" --base main --head feature/x --description "$(cat pr.md)"
```

### Review and merge
```bash
tea pulls checkout 20
# ... local review ...
tea pulls approve 20 "LGTM"
tea pulls merge 20 --style squash
tea pulls clean 20                   # cleanup branches
```

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

### Manage Actions secrets
```bash
tea actions secrets create STAGING_DEPLOY_TOKEN "$(cat ~/.staging-token)" \
  --repo myorg/myrepo
tea actions workflows dispatch deploy.yml --ref staging --repo myorg/myrepo
```

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