# Gitea Access (tea CLI)

**Never access the Gitea API directly** — use the `tea` CLI with all required flags to bypass interactive mode.

Always pass `--login schweitz --repo jpmschweitzer/settled-reach --output simple` to avoid TTY prompts.

```bash
# List open PRs
tea pr list --login schweitz --repo jpmschweitzer/settled-reach --state open --output simple

# View a PR with comments
tea pr --login schweitz --repo jpmschweitzer/settled-reach --comments -o simple <PR_NUMBER>

# Post a comment on a PR (or issue) — use @filepath for long comments
tooling/tea-comment <NUMBER> @/tmp/review.md
tooling/tea-comment <NUMBER> "short inline comment"

# Approve a PR
tea pr approve --login schweitz --repo jpmschweitzer/settled-reach <PR_NUMBER>

# List issues
tea issue list --login schweitz --repo jpmschweitzer/settled-reach --state open --output simple
```

## Key rules

- **All flags must be explicit** — omitting `--login` or `--repo` triggers interactive prompts that crash in Claude Code (no TTY). **One exception: `tea pr create` must OMIT `--repo`** — see Pull requests below.
- **Use `--output simple`** for machine-readable output (no table borders)
- **For comments, use `tooling/tea-comment <number> @/tmp/file.md`** for long comments (write to file first, then pass `@filepath`). Short inline strings also work: `tooling/tea-comment <number> "body"`. The `@filepath` form avoids `$()` subshells which break permission matching.
- **`tea pr reject` does not work on your own PRs** — use `tea comment` instead
- **Run `tea` from the main checkout, never a linked worktree** — its go-git can't read a worktree's `.git` *file* and errors with "local/remote repository required". `tea pr close`/`comment` take explicit `--login`/`--repo` so cwd barely matters for them, but `tea pr create` resolves the repo from the **local checkout's remote** (see below) — that is why it must run from the main repo.
- **Never delete protected branches:** `main`, `maintenance`, `server`, `client`, `copy`, `audio`, `visual`, `ci` are protected on Gitea. Do not use `tea pr clean`, `git push --delete`, or `git branch -D` on these branches.

## Pull requests

**Use `tea` (Gitea CLI), not `gh` (GitHub CLI).** The remote is Gitea at `https://git.schweitz.net` (the `.internal` vhost was retired in the 2026-07 proxy migration; AdGuard hairpins the `.net` name to the LAN).

`tea pr create` is the one command that must **omit `--repo`**: an explicit
`--repo <slug>` makes tea skip local-repo setup, but `pr create` unconditionally
needs the local repo handle (it checks whether the head branch is pushed) and
dies with `local repository required` — the flag *causes* the failure it
suggests fixing. Run it from the **main checkout** and let tea infer the repo
from `origin`'s URL. (This inference is also why the login's `ssh_host` in
`~/.config/tea/config.yml` must match the remote host — currently
`git.schweitz.net`.)

```bash
tea pr create \
  --login schweitz \
  --title "feat(scope): short description" \
  --description "PR body here" \
  --base main \
  --head branch-name
```