# tea CLI Full Command Reference

## Global Flags

| Flag | Short | Description |
|------|-------|-------------|
| `--login` | `-l` | Use a specific configured login |
| `--repo` | `-r` | Override repo as `owner/repo` slug |
| `--remote` | `-R` | Discover login from a git remote name |
| `--output` | `-o` | Output format: `simple`, `table`, `csv`, `tsv`, `yaml`, `json` |

---

## logins / login

| Command | Description |
|---------|-------------|
| `tea login list` | List all configured logins |
| `tea login add` | Add a Gitea instance |
| `tea login edit <name>` | Edit a login entry |
| `tea login delete <name>` | Remove a login |
| `tea login default [name]` | Get or set default login |
| `tea login oauth-refresh` | Refresh OAuth token |
| `tea logout` | Log out from a server |
| `tea whoami` | Show current logged-in user |

### `tea login add` flags

| Flag | Description |
|------|-------------|
| `--url, -u` | Server URL (default: https://gitea.com) |
| `--token, -t` | Access token (Settings > Applications) |
| `--user` | Username for basic auth |
| `--password, --pwd` | Password for basic auth |
| `--oauth, -o` | Interactive OAuth2 flow |
| `--ssh-key, -s` | Path to SSH key |
| `--ssh-agent-key, -a` | SSH public key / fingerprint via agent |
| `--otp` | OTP token |
| `--name, -n` | Login alias name |
| `--insecure, -i` | Disable TLS verification |
| `--no-version-check, --nv` | Skip Gitea version check |

---

## issues / issue / i

### List
```
tea issues list [--state open|closed|all] [--keyword STR] [--labels L1,L2]
                [--assignee USER] [--author USER] [--milestone M]
                [--limit N] [--page N]
                [--fields index,state,kind,author,url,title,body,created,updated,
                          deadline,assignees,milestone,labels,comments,owner,repo]
```

### Create
```
tea issues create --title TITLE --description DESC
                  [--labels L1,L2] [--assignees U1,U2]
                  [--milestone M] [--deadline DATE]
```

### Edit
```
tea issues edit INDEX --title T --description D
                      --add-labels L1 --remove-labels L2
                      --add-assignees U1 --milestone M
```

### Other
```
tea issues close INDEX [INDEX...]
tea issues reopen INDEX [INDEX...]
tea issues comment INDEX               # Add a comment (interactive)
```

---

## pulls / pull / pr

### List
```
tea pulls list [--state open|closed|all]
               [--fields index,state,author,url,title,body,mergeable,base,
                         base-commit,head,diff,patch,created,updated,deadline,
                         assignees,milestone,labels,comments,ci]
```

### Create
```
tea pulls create --title T --description D --base BRANCH
                 [--head BRANCH] [--labels L] [--assignees U]
                 [--milestone M] [--allow-maintainer-edits]
```

### Review workflow
```
tea pulls checkout 99          # Check out PR locally
tea pulls review 99            # Interactive review
tea pulls approve 99           # Approve (LGTM)
tea pulls reject 99            # Request changes
tea pulls merge 99             # Merge the PR
tea pulls clean 99             # Delete merged branch
```

### Edit
```
tea pulls edit 99 --title T --description D
                  --add-labels L --remove-labels L
                  --add-reviewers U1,U2 --remove-reviewers U3
                  --add-assignees U1 --milestone M
```

### review-comments
```
tea pulls review-comments 99   # List review comments
tea pulls resolve COMMENT_ID   # Resolve a review comment
tea pulls unresolve COMMENT_ID
```

---

## repos / repo

```
tea repos list [--owner ORG] [--limit N]
tea repos create --name NAME [--description D] [--private] [--init]
                 [--default-branch BRANCH] [--template OWNER/REPO]
tea repos fork OWNER/REPO [--organization ORG]
tea repos delete OWNER/REPO
```

---

## releases / release

```
tea releases list [--limit N]
tea releases create --tag TAG --title TITLE --note "Notes"
                    [--draft] [--prerelease] [--target BRANCH_OR_SHA]
tea releases edit TAG --title T --note N [--draft] [--prerelease]
tea releases delete TAG
tea releases assets list TAG
tea releases assets upload TAG --asset FILE
tea releases assets delete TAG ASSET_ID
```

---

## milestones / milestone

```
tea milestones list
tea milestones create --title T [--description D] [--deadline DATE]
tea milestones edit INDEX --title T
tea milestones close INDEX
tea milestones reopen INDEX
tea milestones delete INDEX
```

---

## labels / label

```
tea labels list
tea labels create --name NAME --color "#HEX" [--description D]
tea labels delete INDEX
```

---

## notifications / notification / n

```
tea notifications list [--all] [--mine] [--limit N]
tea notifications markread [INDEX]      # Mark as read
```

---

## admin (server admin only)

```
tea admin users list
tea admin orgs list
```

---

## Output Fields Quick Reference

### Issues `--fields`
`index`, `state`, `kind`, `author`, `author-id`, `url`, `title`, `body`, `created`, `updated`, `deadline`, `assignees`, `milestone`, `labels`, `comments`, `owner`, `repo`

### PRs `--fields`
`index`, `state`, `author`, `author-id`, `url`, `title`, `body`, `mergeable`, `base`, `base-commit`, `head`, `diff`, `patch`, `created`, `updated`, `deadline`, `assignees`, `milestone`, `labels`, `comments`, `ci`

---

## Python Automation Patterns

### Get all open issues as structured data
```python
import subprocess, json

def get_issues(repo=None, state="open"):
    cmd = ["tea", "issues", "list", "--state", state, "-o", "json"]
    if repo:
        cmd += ["-r", repo]
    out = subprocess.check_output(cmd, text=True)
    return json.loads(out)
```

### Create issue from Python
```python
def create_issue(title, body="", labels=None, repo=None):
    cmd = ["tea", "issues", "create", "--title", title]
    if body:
        cmd += ["--description", body]
    if labels:
        cmd += ["--labels", ",".join(labels)]
    if repo:
        cmd += ["-r", repo]
    subprocess.run(cmd, check=True)
```

### Bulk close stale issues
```python
issues = get_issues(state="open")
stale = [i for i in issues if "stale" in [l["name"] for l in (i.get("labels") or [])]]
for issue in stale:
    idx = issue.get("number") or issue.get("index")
    subprocess.run(["tea", "issues", "close", str(idx)], check=True)
    print(f"Closed #{idx}")
```

### Export releases to JSON file
```python
import subprocess, json, pathlib

out = subprocess.check_output(["tea", "releases", "list", "-o", "json"], text=True)
pathlib.Path("releases.json").write_text(out)
```