From bb4ad963ee5193456cc036c707d6d214b17f90de Mon Sep 17 00:00:00 2001 From: naudachu Date: Mon, 18 May 2026 15:50:02 +0500 Subject: [PATCH] initial --- SKILL.md | 30 +++++++++ references/tea/entities.md | 130 +++++++++++++++++++++++++++++++++++++ references/tea/helpers.md | 30 +++++++++ references/tea/index.md | 36 ++++++++++ references/tea/misc.md | 17 +++++ references/tea/setup.md | 19 ++++++ 6 files changed, 262 insertions(+) create mode 100644 SKILL.md create mode 100644 references/tea/entities.md create mode 100644 references/tea/helpers.md create mode 100644 references/tea/index.md create mode 100644 references/tea/misc.md create mode 100644 references/tea/setup.md diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..673ac6e --- /dev/null +++ b/SKILL.md @@ -0,0 +1,30 @@ +--- +name: gitea-docs +description: Reference docs for the `tea` CLI — Gitea's command-line client. Load when the user asks about Gitea repos, issues, pulls, releases, actions, or other Gitea entities, to look up the right `tea` command and flags. +--- + +# gitea-docs + +Reference material for the `tea` CLI (Gitea's official command-line client). Use these docs to look up commands, flags, filters, and output fields before running `tea` via Bash. + +## How to use + +1. Identify the entity in the user request: issues, pulls, labels, milestones, releases, times, repos, branches, actions, webhooks, comments, notifications, etc. +2. Find the matching command in the index below. +3. Run it via Bash, e.g. `tea issues list --repo owner/repo --state open`. + +`tea` auto-detects owner/repo/login from `$PWD` when inside a git repo; otherwise pass `--repo owner/repo` (or `-r`) explicitly. Config lives in `$XDG_CONFIG_HOME/tea`. + +## Index + +- [tea CLI overview](references/tea/index.md) — global flags, common options, output formats +- [ENTITIES](references/tea/entities.md) — issues, pulls, labels, milestones, releases, times, repos, branches, actions, webhooks, comment +- [HELPERS](references/tea/helpers.md) — open, notifications, clone, api +- [MISC](references/tea/misc.md) — whoami, admin +- [SETUP](references/tea/setup.md) — logins, logout, ssh-keys + +## Tips + +- Pass `-o json` for structured output when parsing programmatically. +- Use `--fields, -f` to narrow columns. +- Pagination: `--page, -p ` and `--limit, --lm ` (defaults 1 / 30). diff --git a/references/tea/entities.md b/references/tea/entities.md new file mode 100644 index 0000000..56354b0 --- /dev/null +++ b/references/tea/entities.md @@ -0,0 +1,130 @@ +# tea CLI — ENTITIES + +See [`./index.md`](./index.md) for global options and common flags shared by all commands. + +## `tea issues` (aliases: `issue`, `i`) +Without args lists issues; with `` shows issue detail. + +Shared filters: `--state {all|open|closed}` (default: open), `--kind {issues|pulls|all}`, `--keyword/-k`, `--labels/-L`, `--milestones/-m`, `--author/-A`, `--assignee/-a`, `--mentions/-M`, `--owner/--org`, `--from/-F`, `--until/-u`, `--comments`. Available fields: `index,state,kind,author,author-id,url,title,body,created,updated,deadline,assignees,milestone,labels,comments,owner,repo`. + +Subcommands: +- `list, ls` — list (same filters as above). +- `create, c` — create an issue. Options: `--title/-t`, `--description/-d`, `--assignees/-a`, `--labels/-L`, `--milestone/-m`, `--deadline/-D`, `--referenced-version/-v` (commit hash or tag). +- `edit, e ...` — edit. `--title`, `--description`, `--add-assignees/-a`, `--add-labels/-L`, `--remove-labels`, `--milestone`, `--deadline`, `--referenced-version`. To unset a value pass an empty string (`--milestone ""`). +- `reopen, open ...` +- `close ...` + +## `tea pulls` (aliases: `pull`, `pr`) +Without args lists PRs; with `` shows PR detail. Fields: `index,state,author,author-id,url,title,body,mergeable,base,base-commit,head,diff,patch,created,updated,deadline,assignees,milestone,labels,comments,ci`. + +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. +- `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`). +- `close ...`, `reopen, open ...` +- `edit, e ...` — like `issues edit` plus `--add-reviewers/-r`, `--remove-reviewers`. +- `review ` — interactive review. +- `approve, lgtm, a [comment]` +- `reject ` +- `merge, m ` — `--style/-s {merge|rebase|squash|rebase-merge}` (default merge), `--title/-t`, `--message/-m`. +- `review-comments, rc ` — list review comments. Fields: `id,body,reviewer,path,line,resolver,created,updated,url`. +- `resolve ` / `unresolve ` + +## `tea labels` (alias: `label`) +- `list, ls` — `--save/-s` dumps labels to a file. +- `create, c` — `--name`, `--color`, `--description`, `--file` (bulk import from file). +- `update` — `--id`, `--name`, `--color`, `--description`. +- `delete, rm` — `--id`. + +## `tea milestones` (aliases: `milestone`, `ms`) +Fields: `title,state,items_open,items_closed,items,duedate,description,created,updated,closed,id`. + +- `list, ls` (`--state`) +- `create, c` — `--title/-t`, `--description/-d`, `--deadline/--expires/-x`, `--state`. +- `close ...` — `--force/-f` deletes instead of closing. +- `reopen, open ...` +- `delete, rm ` +- `issues, i ` — manage milestone contents: + - `add, a ` + - `remove, r ` + +## `tea releases` (aliases: `release`, `r`) +- `list, ls` +- `create, c []` — `--tag`, `--target` (branch/commit), `--title/-t`, `--note/-n`, `--note-file/-f`, `--draft/-d`, `--prerelease/-p`, `--asset/-a ` (repeatable). +- `edit, e ...` — `--tag`, `--target`, `--title/-t`, `--note/-n`, `--draft/-d `, `--prerelease/-p `. +- `delete, rm ...` — `--confirm/-y` required; `--delete-tag` also removes the git tag. +- `assets, asset, a` — manage release attachments: + - `list, ls ` + - `create, c ...` + - `delete, rm ...` — `--confirm/-y`. + +## `tea times` (aliases: `time`, `t`) +Time tracking on issues/PRs. Fields: `id,created,repo,issue,user,duration`. Command-level: `--from/-f`, `--until/-u`, `--total/-t`, `--mine/-m`. + +- `add, a ` — e.g. `tea times add 1 1h25m`. +- `delete, rm ` +- `reset ` +- `list, ls [username | #issue]` — username filters by user on the repo; `#N` filters by issue; `--mine` aggregates across all repos. + +## `tea organizations` (aliases: `organization`, `org`) +- `list, ls` +- `create, c ` — `--full-name/-n`, `--description/-d`, `--website/-w`, `--location/-L`, `--visibility/-v`, `--repo-admins-can-change-team-access`. +- `delete, rm ` + +## `tea repos` (alias: `repo`) +Fields: `description,forks,id,name,owner,stars,ssh,updated,url,permission,type`. + +- `list, ls` — `--watched/-w`, `--starred/-s`, `--owner/-O`, `--type/-T {fork|mirror|source}`. +- `search, s [term]` — `--topic/-t`, `--type/-T`, `--owner/-O`, `--private {true|false}`, `--archived {true|false}`. +- `create, c` — `--name`, `--owner/-O`, `--private`, `--description/--desc`, `--init`, `--labels`, `--gitignores/--git`, `--license`, `--readme`, `--branch`, `--template`, `--trustmodel {committer|collaborator|collaborator+committer}`, `--object-format {sha1|sha256}`. +- `create-from-template, ct` — `--template/-t`, `--name/-n`, `--owner/-O`, `--private`, `--description/--desc`, copy toggles: `--content`, `--githooks`, `--avatar`, `--labels`, `--topics`, `--webhooks`. +- `fork, f` — `--owner/-O` (default: current user). +- `migrate, m` — `--name`, `--owner`, `--clone-url`, `--service {git|gitea|gitlab|gogs}`, `--mirror`, `--mirror-interval`, `--private`, `--template`, copy toggles: `--wiki`, `--issues`, `--labels`, `--pull-requests`, `--releases`, `--milestones`, `--lfs`, `--lfs-endpoint`, auth: `--auth-user`, `--auth-password`, `--auth-token`. +- `delete, rm` — `--name`, `--owner/-O`, `--force/-f`. +- `edit, e` — `--name`, `--description/--desc`, `--website`, `--private `, `--template `, `--archived `, `--default-branch`. + +## `tea branches` (aliases: `branch`, `b`) +Fields: `name,protected,user-can-merge,user-can-push,protection`. + +- `list, ls` +- `protect, P ` — enable branch protection. +- `unprotect, U ` — remove protection. +- `rename, rn ` + +## `tea actions` (alias: `action`) +CI management: secrets, variables, workflow definitions, workflow runs. + +### `tea actions secrets` (alias: `secret`) +- `list, ls` +- `create, add, set [value]` — `--file` or `--stdin` to read the value. +- `delete, remove, rm ` — `--confirm/-y`. + +### `tea actions variables` (aliases: `variable`, `vars`, `var`) +- `list, ls` — `--name` to fetch a single variable. +- `set, create, update [value]` — `--file`, `--stdin`. +- `delete, remove, rm ` — `--confirm/-y`. + +### `tea actions runs` (alias: `run`) +- `list, ls` — `--status {success|failure|pending|queued|in_progress|skipped|canceled}`, `--branch`, `--event`, `--actor`, `--since`, `--until`. +- `view, show, get ` — `--jobs` prints the jobs table. +- `delete, remove, rm, cancel ` — `--confirm/-y`. +- `logs, log ` — `--job `, `--follow/-f` (requires the job to be in progress). + +### `tea actions workflows` (alias: `workflow`) +- `list, ls` +- `view, show, get ` +- `dispatch, trigger, run ` — `--ref/-r`, `--input/-i key=value` (repeatable), `--follow/-f`. +- `enable ` +- `disable ` — `--confirm/-y`. + +## `tea webhooks` (aliases: `webhook`, `hooks`, `hook`) +Scope is selected by flag: `--repo`, `--org`, `--global`. + +- `list, ls` +- `create, c ` — `--type {gitea|gogs|slack|discord|dingtalk|telegram|msteams|feishu|wechatwork|packagist}` (default: gitea), `--secret`, `--events` (default: push), `--active`, `--branch-filter`, `--authorization-header`. +- `update, edit, u ` — `--url`, `--secret`, `--events`, `--active` / `--inactive`, `--branch-filter`, `--authorization-header`. +- `delete, rm ` — `--confirm/-y`. + +## `tea comment, c [body]` +Add a comment to an issue or PR. Body may be passed as an argument or supplied interactively. diff --git a/references/tea/helpers.md b/references/tea/helpers.md new file mode 100644 index 0000000..d1a605b --- /dev/null +++ b/references/tea/helpers.md @@ -0,0 +1,30 @@ +# tea CLI — HELPERS + +See [`./index.md`](./index.md) for global options and common flags shared by all commands. + +## `tea open, o` +Open the current repository/context in a web browser. + +## `tea notifications` (aliases: `notification`, `n`) +Defaults to the current repo; `--mine/-m` aggregates across all your repos. Fields: `id,status,updated,index,type,state,title,repository`. Filters: `--types/-t {issue|pull|repository|commit}`, `--states/-s {pinned|unread|read}` (default: `unread,pinned`). + +- `ls, list` +- `read, r [all | ]` +- `unread, u [all | ]` +- `pin, p [all | ]` +- `unpin [all | ]` + +## `tea clone, C [target-dir]` +Clone without requiring a local git install. Accepts slug forms: `gitea/tea`, `tea`, `gitea.com/gitea/tea`, `git@gitea.com:gitea/tea`, `https://gitea.com/gitea/tea`, `ssh://gitea.com:22/gitea/tea`. A host in the slug overrides `--login`. Options: `--depth/-d`, `--login/-l`. + +## `tea api ` +Authenticated HTTP request to the Gitea API. Endpoints are auto-prefixed with `/api/v1/` unless they start with `/api/` or `http(s)://`. Placeholders `{owner}` and `{repo}` are filled from the repo context. + +- `--method/-X {GET|POST|PUT|PATCH|DELETE}` (default GET; switches to POST automatically when a body is provided) +- `--field/-f key=value` — string field on body (repeatable). +- `--Field/-F key=value` — typed field (numbers, booleans, null, JSON arrays/objects); `@file` or `@-` (stdin); `"null"` forces literal string. +- `--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). +- Quote the endpoint if it contains `?` or `&` to prevent shell expansion. diff --git a/references/tea/index.md b/references/tea/index.md new file mode 100644 index 0000000..61a7031 --- /dev/null +++ b/references/tea/index.md @@ -0,0 +1,36 @@ +# tea CLI — Index + +Version: `tea 0.14.1` (go-sdk v0.25.1). Source: recursive `--help` traversal. Upstream: https://gitea.com/gitea/tea + +`tea` is a productivity helper for Gitea. It uses the current git repository context (`$PWD`) — owner/repo/login are auto-detected when inside a repo. Config is persisted in `$XDG_CONFIG_HOME/tea`. + +## Global options + +- `--debug, --vvv` — enable debug mode +- `--help, -h`, `--version, -v` + +## Common flags (present on nearly every command) + +| Flag | Purpose | +|---|---| +| `--login, -l ` | use a specific login from the config | +| `--repo, -r ` | override repository context (local path or slug) | +| `--remote, -R ` | discover login from this git remote | +| `--output, -o ` | output format: `simple, table, csv, tsv, yaml, json` | +| `--page, -p ` / `--limit, --lm ` | pagination (defaults 1 / 30) | +| `--fields, -f ` | which columns to print | + +## Command categories + +``` +ENTITIES: issues, pulls, labels, milestones, releases, times, + organizations, repos, branches, actions, webhooks, comment +HELPERS: open, notifications, clone, api +MISC: whoami, admin +SETUP: logins, logout, ssh-keys +``` + +- [ENTITIES](./entities.md) +- [HELPERS](./helpers.md) +- [MISC](./misc.md) +- [SETUP](./setup.md) diff --git a/references/tea/misc.md b/references/tea/misc.md new file mode 100644 index 0000000..f32b66c --- /dev/null +++ b/references/tea/misc.md @@ -0,0 +1,17 @@ +# tea CLI — MISCELLANEOUS + +See [`./index.md`](./index.md) for global options and common flags shared by all commands. + +## `tea whoami` +Show the currently logged in user. + +## `tea admin, a` +Operations requiring admin access on the Gitea instance. + +### `tea admin users` (alias: `u`) +Fields: `id,login,full_name,email,avatar_url,language,is_admin,restricted,prohibit_login,location,website,description,visibility,activated,lastlogin_at,created_at`. + +- `list, ls` +- `create, add, new` — `--username/-u`, `--password/-p` / `--password-file` / `--password-stdin`, `--email/-e`, `--full-name`, `--admin`, `--restricted`, `--prohibit-login`, `--no-must-change-password`, `--visibility {public|limited|private}`. +- `edit, update, e, u ` — paired flags: `--password` (or `--password-file`/`--password-stdin`), `--email/-e`, `--full-name`, `--description`, `--website`, `--location`, `--admin`/`--no-admin`, `--restricted`/`--no-restricted`, `--prohibit-login`/`--allow-login`, `--active`/`--inactive`, `--no-must-change-password`, `--visibility`, `--max-repo-creation` (-1 = unlimited), `--allow-git-hook`/`--no-allow-git-hook`, `--allow-import-local`/`--no-allow-import-local`, `--allow-create-organization`/`--no-allow-create-organization`. +- `delete, rm, remove ` — `--confirm/-y`. diff --git a/references/tea/setup.md b/references/tea/setup.md new file mode 100644 index 0000000..d678949 --- /dev/null +++ b/references/tea/setup.md @@ -0,0 +1,19 @@ +# tea CLI — SETUP + +See [`./index.md`](./index.md) for global options and common flags shared by all commands. + +## `tea logins` (alias: `login`) +- `list, ls` +- `add` — interactive when called without args. `--name/-n`, `--url/-u` (`$GITEA_SERVER_URL`), `--token/-t` (`$GITEA_SERVER_TOKEN`), `--user` (`$GITEA_SERVER_USER`), `--password/--pwd` (`$GITEA_SERVER_PASSWORD`), `--otp` (`$GITEA_SERVER_OTP`), `--scopes` (`$GITEA_SCOPES`), `--ssh-key/-s`, `--ssh-agent-principal/-c`, `--ssh-agent-key/-a`, `--insecure/-i`, `--no-version-check/--nv`, `--helper/-j`, `--oauth/-o` (plus `--client-id`, `--redirect-url`). +- `edit, e` — interactive. +- `delete, rm ` +- `default []` — get or set the default login. +- `oauth-refresh []` — refresh an OAuth token (opens browser if the refresh token is also expired). + +## `tea logout ` +Remove a stored login. + +## `tea ssh-keys` (alias: `ssh-key`) +- `list, ls` +- `add ` — `--title/-t` (defaults to filename without extension). +- `delete, rm ` — `--confirm/-y`.