diff --git a/skills/use/SKILL.md b/skills/use/SKILL.md index a3b95b9..8da4a41 100644 --- a/skills/use/SKILL.md +++ b/skills/use/SKILL.md @@ -58,6 +58,37 @@ The pin takes effect immediately — no restart. Only `tea logins list` and per-project by the operator (see `/tea:auth`) and injected by the guard. Config lives in `$XDG_CONFIG_HOME/tea`. +### `--repo` takes a slug — except where a checkout is required + +A few commands touch local git, not just the API, and for those `--repo` +**must be a path to a checkout**; a slug is rejected: + +``` +Error: local repository required: execute from a repo dir, or specify a path with --repo +``` + +The message reads like the flag is missing even when it was passed. Confirmed +for `pulls create`, `pulls checkout` and `pulls clean` (tea 0.14.x). Everything +that is only an API call — `pulls list`, `milestones`, `releases`, `times`, +`labels`, `issues` — takes the slug from any directory. + +Three working forms for `pulls create`: + +```bash +# 1. cwd inside the checkout, no --repo at all +tea pulls create --login "$GITEA_LOGIN" --head feat/x --base main \ + --title "…" --description "…" + +# 2. from anywhere, --repo as a PATH (this is also the git-worktree answer: +# point it at the main checkout) +tea pulls create --login "$GITEA_LOGIN" --repo /path/to/checkout \ + --head feat/x --base main --title "…" --description "…" + +# 3. no checkout in reach — POST it, where owner/repo is a slug again +tea api --login "$GITEA_LOGIN" -X POST -d @tmp/pull/x.json \ + repos/{owner}/{repo}/pulls +``` + ## Index - [tea CLI overview](references/tea/index.md) — global flags, common options, output formats @@ -125,7 +156,11 @@ are still fine via entity commands. Always the placeholder, never a login name. ## Tips -- Pass `-o json` for structured output when parsing programmatically. +- Pass `-o json` for structured output when parsing programmatically — on + **entity commands only**. On `tea api`, `-o` is a *file name*: `-o json` + writes the response body to a file called `json` and leaves stdout empty. + The response is already JSON, so there is nothing to format; use `-` for + stdout, or leave the flag off. - Use `--fields, -f` to narrow columns. - Pagination: `--page, -p ` and `--limit, --lm ` (defaults 1 / 30). - If a `tea` command is blocked by `tea-guard`: either you forgot diff --git a/skills/use/references/tea/entities.md b/skills/use/references/tea/entities.md index 56354b0..80f8dbf 100644 --- a/skills/use/references/tea/entities.md +++ b/skills/use/references/tea/entities.md @@ -19,9 +19,16 @@ Without args lists PRs; with `` shows PR detail. Fields: `index,state,aut Subcommands: - `list, ls` (`--state`) -- `checkout, co ` — check out PR locally. `--branch/-b` creates a local branch if missing. -- `clean ` — delete local and remote feature branches for a closed PR. `--ignore-sha` matches branch by name instead of commit hash. +- `checkout, co ` — check out PR locally. `--branch/-b` creates a local branch if missing. Needs a checkout, same as `create`: `--repo` is a path here, not a slug. +- `clean ` — delete local and remote feature branches for a closed PR. `--ignore-sha` matches branch by name instead of commit hash. Needs a checkout, same as `create`. - `create, c` — create a PR. `--head `, `--base/-b`, `--allow-maintainer-edits/--edits`, `--agit`, `--topic`, plus all issue-style fields (`--title`, `--description`, `--assignees`, `--labels`, `--milestone`, `--deadline`, `--referenced-version`). + **Needs a local checkout.** `--repo owner/repo` is *not* accepted here — the + slug fails with `local repository required: execute from a repo dir, or + specify a path with --repo`, whose advice reads like the flag was missing. + Run it with cwd inside the checkout and no `--repo`, or pass `--repo + /path/to/checkout`. From a git worktree, point `--repo` at the main + checkout. With no checkout in reach, `POST repos/{owner}/{repo}/pulls` + through `tea api`, which takes the slug. - `close ...`, `reopen, open ...` - `edit, e ...` — like `issues edit` plus `--add-reviewers/-r`, `--remove-reviewers`. - `review ` — interactive review. diff --git a/skills/use/references/tea/helpers.md b/skills/use/references/tea/helpers.md index d1a605b..fb0070d 100644 --- a/skills/use/references/tea/helpers.md +++ b/skills/use/references/tea/helpers.md @@ -26,5 +26,5 @@ Authenticated HTTP request to the Gitea API. Endpoints are auto-prefixed with `/ - `--data/-d` — raw JSON body (`@file` / `@-`). Incompatible with `-f`/`-F`. - `--header/-H key:value` (repeatable) - `--include/-i` — write status + response headers to stderr. -- `--output/-o ` — write response body to file (`-` = stdout). +- `--output/-o ` — write response body to file (`-` = stdout). **Not the entity commands' format flag**: `-o json` here creates a file named `json` and prints nothing. The body is already JSON. - Quote the endpoint if it contains `?` or `&` to prevent shell expansion. diff --git a/skills/use/references/tea/index.md b/skills/use/references/tea/index.md index 61a7031..0f823db 100644 --- a/skills/use/references/tea/index.md +++ b/skills/use/references/tea/index.md @@ -14,9 +14,9 @@ Version: `tea 0.14.1` (go-sdk v0.25.1). Source: recursive `--help` traversal. Up | Flag | Purpose | |---|---| | `--login, -l ` | use a specific login from the config | -| `--repo, -r ` | override repository context (local path or slug) | +| `--repo, -r ` | override repository context (local path or slug). **A slug only works where the command is pure API.** `pulls create`, `pulls checkout` and `pulls clean` need a real checkout and read this flag as a path — see [SKILL.md](../../SKILL.md) | | `--remote, -R ` | discover login from this git remote | -| `--output, -o ` | output format: `simple, table, csv, tsv, yaml, json` | +| `--output, -o ` | output format: `simple, table, csv, tsv, yaml, json`. **Entity commands only** — on `tea api` the same flag is a FILE NAME, see [HELPERS](./helpers.md) | | `--page, -p ` / `--limit, --lm ` | pagination (defaults 1 / 30) | | `--fields, -f ` | which columns to print |