From 9db7da1360e35fd40bedaf17c5d0decb5646864c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A2u=20Cao?= Date: Mon, 26 Oct 2026 18:57:41 +0400 Subject: [PATCH] Split references into focused files, trim SKILL.md, update README --- README.md | 27 +- skills/gitea-gt-cli/SKILL.md | 139 ++---- skills/gitea-gt-cli/references/actions.md | 134 ++++++ skills/gitea-gt-cli/references/auth.md | 92 ++++ skills/gitea-gt-cli/references/ci-config.md | 97 ++++ .../references/commands-actions.md | 262 ----------- .../gitea-gt-cli/references/commands-core.md | 428 ------------------ .../gitea-gt-cli/references/commands-misc.md | 331 -------------- skills/gitea-gt-cli/references/discovery.md | 110 +++++ skills/gitea-gt-cli/references/instance.md | 189 ++++++++ skills/gitea-gt-cli/references/issues.md | 142 ++++++ .../gitea-gt-cli/references/organizations.md | 64 +++ .../gitea-gt-cli/references/pull-requests.md | 133 ++++++ skills/gitea-gt-cli/references/releases.md | 53 +++ skills/gitea-gt-cli/references/repos.md | 84 ++++ skills/gitea-gt-cli/references/workflows.md | 74 +++ 16 files changed, 1215 insertions(+), 1144 deletions(-) create mode 100644 skills/gitea-gt-cli/references/actions.md create mode 100644 skills/gitea-gt-cli/references/auth.md create mode 100644 skills/gitea-gt-cli/references/ci-config.md delete mode 100644 skills/gitea-gt-cli/references/commands-actions.md delete mode 100644 skills/gitea-gt-cli/references/commands-core.md delete mode 100644 skills/gitea-gt-cli/references/commands-misc.md create mode 100644 skills/gitea-gt-cli/references/discovery.md create mode 100644 skills/gitea-gt-cli/references/instance.md create mode 100644 skills/gitea-gt-cli/references/issues.md create mode 100644 skills/gitea-gt-cli/references/organizations.md create mode 100644 skills/gitea-gt-cli/references/pull-requests.md create mode 100644 skills/gitea-gt-cli/references/releases.md create mode 100644 skills/gitea-gt-cli/references/repos.md create mode 100644 skills/gitea-gt-cli/references/workflows.md diff --git a/README.md b/README.md index 0145125..b19f604 100644 --- a/README.md +++ b/README.md @@ -7,19 +7,12 @@ releases, Actions, packages, organizations, and authentication. ## Install ```bash -# HTTPS npx skills add https://gitea.kosmos.org/raucao/gitea-gt-cli.git -# SSH -npx skills add ssh://git@gitea.kosmos.org/raucao/gitea-gt-cli.git - # Specific agent / global -npx skills add https://gitea.kosmos.org/raucao/gitea-gt-cli.git -a claude-code -g +npx skills add https://gitea.kosmos.org/raucao/gitea-gt-cli.git -a opencode -g ``` -The `skills` CLI supports any git host, so this works from Gitea. It will not be -listed on skills.sh, which only indexes GitHub repositories. - Without the `skills` CLI, copy `skills/gitea-gt-cli/` into your agent's skills directory, for example `~/.agents/skills/gitea-gt-cli/` or `.agents/skills/gitea-gt-cli/`. @@ -28,14 +21,22 @@ directory, for example `~/.agents/skills/gitea-gt-cli/` or ```text skills/gitea-gt-cli/ -├── SKILL.md # when to use gt, auth, core concepts, workflows, gotchas +├── SKILL.md # when to use gt, auth, core concepts, command map, gotchas └── references/ - ├── commands-core.md # auth, repo, issue, pr, release, org, label, milestone, branch - ├── commands-actions.md # run, workflow, secret, variable, package, admin - └── commands-misc.md # team, notification, search, status, time, webhook, wiki, ... + ├── workflows.md # end-to-end recipes (issues, PRs, Actions, releases, fork/sync) + ├── auth.md # auth, doctor, setup-git, env vars + ├── repos.md # repo, branch + ├── issues.md # issue, label, milestone + ├── pull-requests.md # pr (reviews, checks, diff, merge, status) + ├── releases.md # release + ├── organizations.md # org, team + ├── actions.md # run, workflow + ├── ci-config.md # secret, variable, package + ├── discovery.md # search, status, notification, time + └── instance.md # config, api, alias, completion, webhook, wiki, ssh-key, admin ``` -`SKILL.md` stays small and points at the reference file for each command group, +`SKILL.md` stays small and maps each command group to a focused reference file, so the agent loads only the detail it needs. ## Requirements diff --git a/skills/gitea-gt-cli/SKILL.md b/skills/gitea-gt-cli/SKILL.md index a750666..2f504e9 100644 --- a/skills/gitea-gt-cli/SKILL.md +++ b/skills/gitea-gt-cli/SKILL.md @@ -23,8 +23,8 @@ at your desk and in CI. which is stable; text output is for people. Use this skill whenever a task involves running `gt` or managing a Gitea -instance from the shell. Do not guess flags: every command's help lists its -flags and JSON fields, and the reference files below mirror that help. +instance from the shell. Do not guess flags: each command's help lists its flags +and JSON fields, and the reference files mirror that help. ## Install `gt` @@ -35,9 +35,6 @@ curl -fsSL https://gitea.com/gitea/cli/raw/branch/main/scripts/install.sh | sh # Windows (PowerShell) irm https://gitea.com/gitea/cli/raw/branch/main/scripts/install.ps1 | iex -# Docker -docker run --rm gitea/gitea-cli --help - # From source go install gitea.dev/cli/cmd/gt@latest ``` @@ -47,38 +44,21 @@ Verify with `gt version`. Binaries are also at ## Authenticate -`gt` keeps accounts in `hosts.yml` and tokens in the system keyring (or a -private file), under `~/.config/gitea-cli/` (`GITEA_CLI_CONFIG_DIR` overrides). -It never reads `tea`'s config. +`gt` stores accounts in `hosts.yml` and tokens in the system keyring (or a +private file), under `~/.config/gitea-cli/`. It never reads `tea`'s config. ```bash -# Interactive: asks for instance, OAuth or token, storage, and git setup -gt auth login - -# CI / non-interactive: token on stdin -gt auth login --host gitea.example.com --with-token < token.txt +gt auth login # interactive: OAuth or token +gt auth login --host gitea.example.com --with-token < token.txt # CI echo "$TOKEN" | gt auth login --host gitea.example.com --with-token - -# OAuth in the browser with explicit scopes -gt auth login --host gitea.example.com --oauth --scopes read:repository,read:user - -# Inspect and use accounts -gt auth status # which accounts, active one, method (exit 4 if none/invalid) -gt auth status --verify # check credentials against the instance -gt auth token # print the active token (for curl/scripts) -gt auth switch # change the active account of an instance -gt auth setup-git # configure git to use gt for https push/fetch -gt doctor # diagnose settings, instance, account, repo and git +gt auth status --verify # check the active credential +gt doctor # diagnose the setup here ``` -### Environment variables (CI) - -- `GITEA_TOKEN` + `GITEA_INSTANCE_URL` (or `GITEA_CLI_HOST`): use a token - instead of stored credentials. -- `GITEA_CLI_*` prefixed variables mirror global flags and settings; see - `gt help environment` for the full list (config dir, user, repo, editor, - pager, color, http timeout, ...). -- `GITEA_INSTANCE_INSECURE`, `GITEA_INSTANCE_SSH_HOST`: pair with `GITEA_TOKEN`. +In CI, `GITEA_TOKEN` + `GITEA_INSTANCE_URL` (or `GITEA_CLI_HOST`) replace stored +credentials; other `GITEA_CLI_*` variables mirror flags and settings. Full flags, +`setup-git`, `token`, and the environment list are in +[references/auth.md](references/auth.md). ## Core concepts @@ -94,12 +74,6 @@ It picks the **repository** from: `--repo`/`-R OWNER/REPO`, `GITEA_CLI_REPO`, remote, upstream, or origin). Like `gh`, a clone with `upstream` and `origin` targets `upstream`. -```bash -gt -R alice/project issue list -gt issue list --repo alice/project # same, flag after the command -gt repo set-default upstream/name # make this clone target the upstream -``` - ### Global flags Work with every command, before or after the command name: @@ -117,6 +91,9 @@ Work with every command, before or after the command name: | `--debug` | Log HTTP method, URL, status, duration to stderr | | `--cwd dir` / `--remote remote` | Repository discovery | +Repository-scoped groups also inherit `--remote`, `--cwd`; list/view commands +add `--json`/`--jq`. See `gt help environment`. + ### JSON output Text output is for people and may change; **use `--json` in scripts**. `--jq` @@ -125,8 +102,6 @@ available ones, and each command's help lists its JSON fields. ```bash gt issue list --json number,title --jq '.[] | "\(.number)\t\(.title)"' -gt pr list --json number,title,head --jq '.[] | select(.head == "feature/login")' -gt run list --since 24h --json id,status,conclusion,workflow ``` Some fields cost extra requests (e.g. `pr list` reviewers, `issue view` @@ -149,78 +124,22 @@ Commands may document further codes. See `gt help exit-codes`. ## Command map +Read the reference file for a group to get its per-command flags, arguments, +`--json` fields and examples. `gt --help` is always authoritative. + | Group | Commands | Reference | | --- | --- | --- | -| Auth | `auth` (login, logout, refresh, setup-git, status, switch, token) | `references/commands-core.md` | -| Repositories | `repo` (create, clone, fork, sync, view, list, edit, migrate, deploy-key, ...) | `references/commands-core.md` | -| Issues | `issue` (create, list, view, edit, close, reopen, comment, timeline, attachment) | `references/commands-core.md` | -| Pull requests | `pr` (create, list, view, checkout, diff, checks, review, merge, status, clean) | `references/commands-core.md` | -| Releases | `release` (create, list, view, edit, upload, download, asset, publish) | `references/commands-core.md` | -| Orgs & labels | `org`, `label`, `milestone`, `branch` | `references/commands-core.md` | -| Actions | `run`, `workflow`, `secret`, `variable`, `package`, `admin` | `references/commands-actions.md` | -| Everything else | `team`, `notification`, `search`, `status`, `time`, `webhook`, `wiki`, `ssh-key`, `api`, `config`, `alias`, `completion` | `references/commands-misc.md` | - -**Read the reference file** when you need exact flags, arguments, accepted -`--json` fields, or examples for a command. `gt --help` is always -authoritative for the installed version. - -## Common workflows - -### Issue lifecycle - -```bash -gt issue list --assignee @me --state open -gt issue view 12 --comments -gt issue create --title "Crash on start" --body "Steps..." --label bug --milestone v1.0 -gt issue edit 12 --add-label triage --add-assignee @me -gt issue comment 12 --body "Fixed in #14" -gt issue close 12 --comment "Done in #14" -``` - -### Pull requests (create → checks → review → merge) - -```bash -gt pr create --fill # push branch, open PR, title/body from commits -gt pr create --fill --yes # non-interactive: also push without asking -gt pr list --author @me --state all -gt pr checkout 13 --update # local branch tracking the PR head -gt pr diff 13 | git apply # pipe clean diff (git apply works) -gt pr checks 13 --watch # waits; exit 8 while pending, 1 if a check failed -gt pr review --approve -gt pr review 13 --request-changes -b "Please hash the password" -gt pr merge 13 --squash --delete-branch -``` - -### Actions: run, watch, logs, artifacts - -```bash -gt workflow list -gt workflow run deploy.yml --ref main --field env=staging -gt run list --workflow CI --branch main --status failure -gt run watch 34 --timeout 10m && echo deployed -gt run view 34 --log -gt run logs 34 --job build --follow -gt run download 34 --name build --dir dist -gt secret set DEPLOY_TOKEN -``` - -### Releases - -```bash -gt release create v1.0.0 dist/tool-linux dist/tool-darwin --notes-file CHANGELOG.md -gt release list -gt release upload v1.0.0 dist/tool-darwin --clobber -gt release download v1.0.0 -``` - -### Fork / clone / keep in sync - -```bash -gt repo fork --remote # inside a clone: add fork as origin, rename old origin to upstream -gt repo clone alice/project src --depth 1 -gt repo sync # fast-forward the default branch from its remote -gt repo sync bob/project # fork without a local remote: update it on the server -``` +| Auth | `auth`, `doctor` | [auth.md](references/auth.md) | +| Repositories | `repo`, `branch` | [repos.md](references/repos.md) | +| Issues | `issue`, `label`, `milestone` | [issues.md](references/issues.md) | +| Pull requests | `pr` | [pull-requests.md](references/pull-requests.md) | +| Releases | `release` | [releases.md](references/releases.md) | +| Organizations | `org`, `team` | [organizations.md](references/organizations.md) | +| Actions | `run`, `workflow` | [actions.md](references/actions.md) | +| CI config | `secret`, `variable`, `package` | [ci-config.md](references/ci-config.md) | +| Discovery | `search`, `status`, `notification`, `time` | [discovery.md](references/discovery.md) | +| Instance | `config`, `api`, `alias`, `completion`, `webhook`, `wiki`, `ssh-key`, `admin` | [instance.md](references/instance.md) | +| Recipes | end-to-end workflows | [workflows.md](references/workflows.md) | ## Coming from `tea` diff --git a/skills/gitea-gt-cli/references/actions.md b/skills/gitea-gt-cli/references/actions.md new file mode 100644 index 0000000..8835dd3 --- /dev/null +++ b/skills/gitea-gt-cli/references/actions.md @@ -0,0 +1,134 @@ +# Actions: runs and workflows + +Gitea Actions are first-class in `gt`. This file covers `run` (workflow runs) +and `workflow` (definitions and dispatch). Secrets, variables and packages are +in [ci-config.md](ci-config.md). `gt --help` is authoritative. + +**Run argument:** a run ID (`34`, `#34`) or a run URL +(`https://HOST/OWNER/REPO/actions/runs/34`). Without one, a terminal asks you to +pick a recent run. + +**JSON fields (run):** `actor, attempt, branch, commit, completed_at, conclusion, +created_at, event, id, jobs, run_number, started_at, status, title, updated_at, +url, workflow, workflow_path`. + +## run + +```text +gt run + artifact cancel delete download jobs list logs rerun view watch +``` + +`run list` aliases `run ls`. + +### list + +`-u/--actor @me`, `-b/--branch`, `-c/--commit SHA|rev`, `-e/--event`, +`-w/--workflow file|name`, `-s/--status` (status or conclusion, repeatable), +`--since`/`--until` (date, RFC3339, or duration ago; scans up to 5000 runs), +`-L/--limit`, `--page`. + +```bash +gt run list +gt run list --workflow CI --branch main --status failure +gt run list --since 24h --json id,status,conclusion,workflow +``` + +### view / watch + +- `view [] [--log] [--no-jobs] [-w]` — run, jobs and steps. +- `watch [] [-i|--interval 3s] [--timeout 1h]` — refresh until done; + **fails when the run completes without success**; tolerates a 5-minute outage. + +```bash +gt run view 34 +gt run view 34 --json jobs --jq '.jobs[] | {name, conclusion}' +gt run watch 34 --timeout 10m && echo deployed +``` + +### logs + +`logs [] [-j|--job name|ID] [-f|--follow] [--failed] +[-i|--interval 5s] [-O|--output file|-] [-D|--dir dir] [--timeout 1h] +[--clobber] [--skip-existing]` + +Prints each job's logs, job names to stderr. `--follow` waits for jobs to start +and prints new lines. `--output`/`--dir` download the whole run's logs as a ZIP. + +```bash +gt run logs 34 +gt run logs 34 --job build --follow +gt run logs 34 --output logs.zip +``` + +### download + +`download [] [-n|--name artifact] [-D|--dir dir] [-O|--output path|-] +[--zip] [--clobber] [--skip-existing]` — extracts each artifact into a +directory named after it; a single `--name` extracts into the destination +itself; `--zip` keeps archives. + +```bash +gt run download 34 +gt run download 34 --name build --dir dist +gt run download 34 --zip +``` + +### jobs / artifact list / cancel / rerun / delete + +- `jobs [] [-L n] [--page n]` — JSON: `completed_at, conclusion, + created_at, id, labels, name, run_attempt, started_at, status, steps, url`. +- `artifact list []` — list uploaded artifacts. +- `cancel [] [--force]` — keeps the run and logs. +- `rerun [] [--failed] [-j|--job name|ID]` — all jobs, failed only, or one. +- `delete []`. + +```bash +gt run jobs 34 --json id,conclusion --jq '.[] | select(.conclusion == "failure") | .id' +gt run rerun 34 --failed +``` + +## workflow + +```text +gt workflow + disable enable list run view +``` + +`workflow list` aliases `workflow ls`. + +**Workflow argument:** file name (`ci.yml`), name without extension (`ci`), +path (`.gitea/workflows/ci.yml`), or workflow name (`CI`). + +**JSON fields:** `id, name, path, state, url`. + +### run (dispatch) + +`gt workflow run ` with `-r/--ref branch|tag`, +`-f/--field key=value` (repeatable), `--follow`, `--interval 2s`, +`--timeout 30m`. Requires a `workflow_dispatch` trigger. Inputs are validated +against the declared inputs: unknown, missing-required, or invalid choice/boolean +values are refused. The workflow must exist on the default branch (like `gh`); +`--ref` selects the version that runs. Without `--ref`, runs on the checked-out +branch if it is on the server, else the default branch. With `--follow`, fails +like `gt run watch` when the run completes without success. + +JSON fields: `id, url`. + +```bash +gt workflow run CI +gt workflow run ci.yml --ref main -f target=production -f dry_run=false +gt workflow run nightly --follow +``` + +### view / list / enable / disable + +- `view [-r ref] [--yaml] [-w]` — workflow and recent runs. +- `list` +- `enable `, `disable ` + +```bash +gt workflow view CI +gt workflow view ci.yml --yaml --ref feature/login +gt workflow disable Nightly +``` diff --git a/skills/gitea-gt-cli/references/auth.md b/skills/gitea-gt-cli/references/auth.md new file mode 100644 index 0000000..def7860 --- /dev/null +++ b/skills/gitea-gt-cli/references/auth.md @@ -0,0 +1,92 @@ +# auth (`gt auth`) + +Authentication, accounts, git credential setup, and environment variables. +`gt --help` is authoritative. + +`gt` keeps accounts in `hosts.yml` and tokens in the system keyring (or a +private file), under `~/.config/gitea-cli/` (`GITEA_CLI_CONFIG_DIR` overrides). +It never reads `tea`'s config. One account per instance is active; `--user` or +`GITEA_CLI_USER` selects another for a single command. + +## Commands + +```text +gt auth + login logout refresh setup-git status switch token +``` + +### login + +Without a method flag on a terminal it asks for the instance, login method, +token storage and whether git should use `gt`. + +| Flag | Meaning | +| --- | --- | +| `--with-token` | Read an access token from stdin (or prompt) | +| `--oauth` | Authorize in a browser; `--client-id ID` selects the OAuth app | +| `--scopes scopes` | OAuth scopes, e.g. `read:repository,read:user` (implies `--oauth`) | +| `--credential-store {keyring\|file}` | Where to keep the token (default `keyring`) | +| `--insecure` | Skip TLS verification for this instance | +| `--header "Name: value"` | Send a header with every request (repeatable; `$VAR` expansion) | +| `--ssh-key file`, `--ssh-agent-key fp`, `--ssh-agent-principal p` | Sign requests with SSH | +| `--client-cert file`, `--client-key file` | TLS client certificate | +| `-y, --yes` | Replace an existing account without confirming | + +```bash +gt auth login +gt auth login --host gitea.com --with-token < token.txt +gt auth login --host gitea.com --oauth --scopes read:repository,read:user +gt auth login --host g.example.com --with-token \ + --header 'CF-Access-Client-Id: $CF_ID' --header 'CF-Access-Client-Secret: $CF_SECRET' +``` + +Create a token on the instance under **Settings > Applications**. The first +instance logged in to becomes `default_host` unless one is set. + +### status / token / switch / setup-git / logout / refresh + +- `status [--verify] [--json ...]` — accounts per instance, active one, method. + Fails with exit **4** when there is no account or the credential is + missing/rejected; with `--json` it exits 0 and you read + `credential_available`, `verified`, `error`. JSON fields: `active, + credential_available, credential_store, error, expires_at, + git_credential_helper, host, method, scopes, user, verified`. +- `token` — print the active token (refreshing an expiring OAuth token). SSH-key + accounts have no token. +- `switch` — change the active account of an instance. +- `setup-git [--keep-helpers] [--local]` — configure git to ask `gt` for + credentials. Other credential helpers are turned off for the instance unless + `--keep-helpers`; `--local` configures only the current repository. +- `logout` — log out of an account. +- `refresh` — refresh an OAuth token. + +```bash +gt auth status --verify +gt auth status --host gitea.com --json +curl -H "Authorization: token $(gt auth token)" https://gitea.com/api/v1/user +``` + +## Environment variables + +- `GITEA_TOKEN` + `GITEA_INSTANCE_URL` (or `GITEA_CLI_HOST`): use a token + instead of stored credentials. `GITEA_TOKEN` replaces the active account of + its instance for the active account too; it must belong to the account + `--user`/`GITEA_CLI_USER` names. +- `GITEA_CLI_*` prefixed variables mirror global flags and settings; see + `gt help environment` for the full list (config dir, user, repo, editor, + pager, color, http timeout, ...). +- `GITEA_INSTANCE_INSECURE`, `GITEA_INSTANCE_SSH_HOST`: pair with `GITEA_TOKEN`. + +## doctor + +`gt doctor [-R ...] [--json ...]` checks the setup commands in this directory +use: settings files, the instance and its headers, whether it answers, the +account and credential, the repository, and git. Each problem names the command +that fixes it; `gt doctor` fails when a check fails. JSON fields: `checks, +host, host_source, repo, repo_source, user, user_source`. + +```bash +gt doctor +gt doctor -R gitea.com/gitea/cli +gt doctor --jq '.checks[] | select(.status == "failed")' +``` diff --git a/skills/gitea-gt-cli/references/ci-config.md b/skills/gitea-gt-cli/references/ci-config.md new file mode 100644 index 0000000..9121563 --- /dev/null +++ b/skills/gitea-gt-cli/references/ci-config.md @@ -0,0 +1,97 @@ +# CI configuration: secrets, variables, packages + +Actions secrets and variables and the package registry. Workflow files and +dispatch are in [actions.md](actions.md). `gt --help` is authoritative. + +**Scoping (secrets and variables):** repository (default), organization +(`--org`), or your account (`--account`). Names are stored **upper-cased**. + +> The global `--user` flag selects the account `gt` acts as — it is **not** a +> scope. Use `--org` / `--account` for scope. + +## secret + +```text +gt secret + delete list set +``` + +Read by workflows as `${{ secrets.NAME }}`. Secret values are never shown. + +- `set [] [-b|--body value] [-F|--body-file file|-] [-d|--description] + [-f|--env-file file|-] [-o|--org ORG] [--account]` — `--env-file` sets every + `NAME=value` of a dotenv file. The value comes from the flag/file, else stdin + when not a terminal (one trailing newline removed), else a prompt. Setting an + existing secret without `--description` clears its description. +- `list [-L n] [--page n] [-o|--org ORG] [--account]` (alias `ls`) +- `delete [-o|--org ORG] [--account] [-y|--yes]` (alias `rm`) + +JSON: `created_at, description, name`. + +```bash +gt secret set DEPLOY_TOKEN +echo -n "$TOKEN" | gt secret set NPM_TOKEN --org acme +gt secret set --env-file .env +gt secret list --org acme +``` + +## variable + +```text +gt variable + delete get list set view +``` + +Read by workflows as `${{ vars.NAME }}`. Same scoping and naming rules as +secrets. + +**JSON fields:** `description, name, value`. + +- `set [] [-b value] [-F file|-] [-d description] [-f|--env-file file|-] + [-o|--org ORG] [--account]` +- `get [...]` — print just the value (for scripts). +- `view ` — value plus description. +- `list [-L n] [--page n] [-o|--org ORG] [--account]` (alias `ls`) +- `delete [-o|--org ORG] [--account] [-y|--yes]` (alias `rm`) + +```bash +gt variable set ENVIRONMENT --body staging +gt variable set CONFIG --org acme < config.json +gt variable set --env-file .env +region=$(gt variable get REGION --org acme) +gt variable list --org acme +``` + +## package + +```text +gt package + delete link list unlink upload versions view +``` + +Packages live in the registry of a user or organization: the owner of the +selected repository, else your account, unless `--owner` names another. A +package is addressed by **type** (e.g. `generic`, `npm`, `container`) and +**name**. + +`package list` aliases `package ls`; `package delete` aliases `package rm`. + +**JSON fields:** `created_at, creator, id, name, owner, repository, type, url, +version`; `view` adds `files`. + +- `list [-t|--type type] [-S|--search text] [--owner OWNER] [-L n] [--page n]` +- `versions [--owner] [-L n] [--page n]` +- `view [] [--owner]` — latest version without one. +- `upload ... [--owner]` — generic packages; each file + is stored under its base name; a version cannot hold two files of the same + name. +- `link [--owner]` +- `unlink [--owner]` +- `delete [] [--all] [--owner] [-y|--yes]` + +```bash +gt package upload tool 1.0.0 dist/tool-linux-amd64 dist/tool-darwin-arm64 +gt package list --owner acme --type container +gt package versions generic tool +gt package delete generic tool 1.0.0 +``` diff --git a/skills/gitea-gt-cli/references/commands-actions.md b/skills/gitea-gt-cli/references/commands-actions.md deleted file mode 100644 index 912aa75..0000000 --- a/skills/gitea-gt-cli/references/commands-actions.md +++ /dev/null @@ -1,262 +0,0 @@ -# Command reference: Actions - -`gt` treats Gitea Actions as first-class. Groups: `run` (workflow runs), `workflow` -(definitions and dispatch), `secret`, `variable`, `package` (registry), and `admin`. - -`gt --help` is authoritative for the installed version. - -**Run argument:** a run ID (`34`, `#34`) or a run URL -(`https://HOST/OWNER/REPO/actions/runs/34`). Without one, a terminal asks you to -pick a recent run. - -**JSON fields (run):** `actor, attempt, branch, commit, completed_at, conclusion, -created_at, event, id, jobs, run_number, started_at, status, title, updated_at, -url, workflow, workflow_path`. - ---- - -## run - -```text -gt run - artifact cancel delete download jobs list logs rerun view watch -``` - -`run list` aliases `run ls`. - -### list - -`-u/--actor @me`, `-b/--branch`, `-c/--commit SHA|rev`, `-e/--event`, -`-w/--workflow file|name`, `-s/--status` (status or conclusion, repeatable), -`--since`/`--until` (date, RFC3339, or duration ago; scans up to 5000 runs), -`-L/--limit`, `--page`. - -```bash -gt run list -gt run list --workflow CI --branch main --status failure -gt run list --since 24h --json id,status,conclusion,workflow -``` - -### view / watch - -- `view [] [--log] [--no-jobs] [-w]` — run, jobs and steps. -- `watch [] [-i|--interval 3s] [--timeout 1h]` — refresh until done; - **fails when the run completes without success**; tolerates a 5-minute outage. - -```bash -gt run view 34 -gt run view 34 --json jobs --jq '.jobs[] | {name, conclusion}' -gt run watch 34 --timeout 10m && echo deployed -``` - -### logs - -`logs [] [-j|--job name|ID] [-f|--follow] [--failed] -[-i|--interval 5s] [-O|--output file|-] [-D|--dir dir] [--timeout 1h] -[--clobber] [--skip-existing]` - -Prints each job's logs, job names to stderr. `--follow` waits for jobs and new -lines. `--output`/`--dir` download the whole run's logs as a ZIP. - -```bash -gt run logs 34 -gt run logs 34 --job build --follow -gt run logs 34 --output logs.zip -``` - -### download - -`download [] [-n|--name artifact] [-D|--dir dir] [-O|--output path|-] -[--zip] [--clobber] [--skip-existing]` — extracts each artifact into a -directory named after it; a single `--name` extracts into the destination -itself; `--zip` keeps archives. - -```bash -gt run download 34 -gt run download 34 --name build --dir dist -gt run download 34 --zip -``` - -### jobs / artifact list / cancel / rerun / delete - -- `jobs [] [-L n] [--page n]` — JSON: `completed_at, conclusion, - created_at, id, labels, name, run_attempt, started_at, status, steps, url`. -- `artifact list []` — list uploaded artifacts. -- `cancel [] [--force]` — keeps the run and logs. -- `rerun [] [--failed] [-j|--job name|ID]` — all jobs, failed only, or one. -- `delete []`. - -```bash -gt run jobs 34 --json id,conclusion --jq '.[] | select(.conclusion == "failure") | .id' -gt run rerun 34 --failed -``` - ---- - -## workflow - -```text -gt workflow - disable enable list run view -``` - -`workflow list` aliases `workflow ls`. - -**Workflow argument:** file name (`ci.yml`), name without extension (`ci`), -path (`.gitea/workflows/ci.yml`), or workflow name (`CI`). - -**JSON fields:** `id, name, path, state, url`. - -### run (dispatch) - -`gt workflow run ` with `-r/--ref branch|tag`, -`-f/--field key=value` (repeatable), `--follow`, `--interval 2s`, -`--timeout 30m`. Requires a `workflow_dispatch` trigger. Inputs are validated -against the declared inputs: unknown, missing-required, or invalid choice/boolean -values are refused. The workflow must exist on the default branch (like `gh`); -`--ref` selects the version that runs. Without `--ref`, runs on the checked-out -branch if it is on the server. - -JSON fields: `id, url`. - -```bash -gt workflow run CI -gt workflow run ci.yml --ref main -f target=production -f dry_run=false -gt workflow run nightly --follow -``` - -### view / list / enable / disable - -- `view [-r ref] [--yaml] [-w]` — workflow and recent runs. -- `list` -- `enable `, `disable ` - -```bash -gt workflow view CI -gt workflow view ci.yml --yaml --ref feature/login -gt workflow disable Nightly -``` - ---- - -## secret - -```text -gt secret - delete list set -``` - -Secrets are read by workflows as `${{ secrets.NAME }}`. Scope: repository -(default), organization (`--org`), or your account (`--account`). Names are -stored **upper-cased**. - -> The global `--user` flag selects the account `gt` acts as — it is **not** a -> scope. Use `--org` / `--account` for scope. - -### set - -`gt secret set []` with `-b/--body value`, `-F/--body-file file|-`, -`-d/--description`, `-f/--env-file file|-` (sets every `NAME=value`). -The value comes from the flag/file, else stdin when not a terminal (one -trailing line break removed), else a prompt. - -JSON: `created_at, description, name`. - -```bash -gt secret set DEPLOY_TOKEN -echo -n "$TOKEN" | gt secret set NPM_TOKEN --org acme -gt secret set --env-file .env -``` - -### list / delete - -- `list [-L n] [--page n] [-o|--org ORG]` (alias `ls`) -- `delete [-o|--org ORG] [--account] [-y|--yes]` (alias `rm`) - -```bash -gt secret list --org acme -gt secret delete DEPLOY_TOKEN --org acme --yes -``` - ---- - -## variable - -```text -gt variable - delete get list set view -``` - -Variables are read by workflows as `${{ vars.NAME }}`. Same scoping and naming -rules as secrets (`--org`, `--account`; names upper-cased). - -**JSON fields:** `description, name, value`. - -### set / get / view / list / delete - -- `set [] [-b value] [-F file|-] [-d description] [-f|--env-file file|-] - [-o|--org ORG] [--account]` -- `get [...]` — print just the value (for scripts). -- `view ` — value plus description. -- `list [-L n] [--page n] [-o|--org ORG] [--account]` (alias `ls`) -- `delete [-o|--org ORG] [--account] [-y|--yes]` (alias `rm`) - -```bash -gt variable set ENVIRONMENT --body staging -gt variable set CONFIG --org acme < config.json -gt variable set --env-file .env -region=$(gt variable get REGION --org acme) -gt variable list --org acme -``` - ---- - -## package - -```text -gt package - delete link list unlink upload versions view -``` - -Packages live in the registry of a user or organization: the owner of the -selected repository, else your account, unless `--owner` names another. A -package is addressed by **type** (e.g. `generic`, `npm`, `container`) and -**name**. - -`package list` aliases `package ls`; `package delete` aliases `package rm`. - -**JSON fields:** `created_at, creator, id, name, owner, repository, type, url, -version`; `view` adds `files`. - -- `list [-t|--type type] [-S|--search text] [--owner OWNER] [-L n] [--page n]` -- `versions [--owner] [-L n] [--page n]` -- `view [] [--owner]` — latest version without one. -- `upload ... [--owner]` — generic packages; each file - is stored under its base name. -- `link [--owner]` -- `unlink [--owner]` -- `delete [] [--all] [--owner] [-y|--yes]` - -```bash -gt package upload tool 1.0.0 dist/tool-linux-amd64 dist/tool-darwin-arm64 -gt package list --owner acme --type container -gt package versions generic tool -gt package delete generic tool 1.0.0 -``` - ---- - -## admin - -```text -gt admin - user (list, view, create, edit, delete) -``` - -Instance administration; requires an administrator account. (`--sudo user` on -other commands acts as another user.) - -```bash -gt admin user list -gt admin user create alice --email alice@example.com -``` diff --git a/skills/gitea-gt-cli/references/commands-core.md b/skills/gitea-gt-cli/references/commands-core.md deleted file mode 100644 index 638b0e1..0000000 --- a/skills/gitea-gt-cli/references/commands-core.md +++ /dev/null @@ -1,428 +0,0 @@ -# Command reference: core - -Per-command flags, arguments, JSON fields and examples for the core `gt` groups: -`auth`, `repo`, `issue`, `pr`, `release`, `org`, `label`, `milestone`, `branch`. - -`gt --help` is authoritative for the installed version. - -## Shared flags - -- **Repository-scoped groups** (`repo`, `issue`, `pr`, `release`, `branch`, - `label`, `milestone`) inherit: - `-R, --repo OWNER/REPO`, `--remote remote`, `--cwd directory`. -- **List/view commands** additionally inherit `--json fields` and - `-q, --jq expression` (see `gt help formatting`). -- **Mutating commands** that confirm inherit `-y, --yes`. -- Global flags (`--host`, `--user`, `--sudo`, `--no-input`, `--interactive`, - `--debug`) work everywhere; see `gt help environment`. - ---- - -## auth - -```text -gt auth - login logout refresh setup-git status switch token -``` - -### gt auth login - -Log in to a Gitea instance. Without a method flag on a terminal it asks for the -instance, login method, token storage and whether git should use `gt`. - -| Flag | Meaning | -| --- | --- | -| `--with-token` | Read an access token from stdin (or prompt) | -| `--oauth` | Authorize in a browser; `--client-id ID` selects the OAuth app | -| `--scopes scopes` | OAuth scopes, e.g. `read:repository,read:user` (implies `--oauth`) | -| `--credential-store {keyring\|file}` | Where to keep the token (default `keyring`) | -| `--insecure` | Skip TLS verification for this instance | -| `--header "Name: value"` | Send a header with every request (repeatable; `$VAR` expansion) | -| `--ssh-key file`, `--ssh-agent-key fp`, `--ssh-agent-principal p` | Sign requests with SSH | -| `--client-cert file`, `--client-key file` | TLS client certificate | -| `-y, --yes` | Replace an existing account without confirming | - -```bash -gt auth login -gt auth login --host gitea.com --with-token < token.txt -gt auth login --host gitea.com --oauth --scopes read:repository,read:user -gt auth login --host g.example.com --with-token \ - --header 'CF-Access-Client-Id: $CF_ID' --header 'CF-Access-Client-Secret: $CF_SECRET' -``` - -### gt auth status / token / switch / setup-git / logout / refresh - -- `status [--verify] [--json ...]` — accounts per instance, active one, method. - Fails exit 4 when there is no account or the credential is missing/rejected; - with `--json` it exits 0 and you read `credential_available`, `verified`, - `error`. JSON fields: `active, credential_available, credential_store, error, - expires_at, git_credential_helper, host, method, scopes, user, verified`. -- `token` — print the active token (refreshing an expiring OAuth token). SSH-key - accounts have no token. -- `switch` — change the active account of an instance. -- `setup-git [--keep-helpers] [--local]` — configure git to ask `gt` for - credentials. -- `logout`, `refresh` (refresh an OAuth token). - -```bash -gt auth status --verify -curl -H "Authorization: token $(gt auth token)" https://gitea.com/api/v1/user -``` - ---- - -## repo - -```text -gt repo - archive clone create delete deploy-key edit fork list migrate - rename set-default sync transfer unarchive view -``` - -`repo list` aliases `repo ls`; `repo create` aliases `repo new`. - -**Repository argument** (where accepted): `NAME` (one of yours), `OWNER/NAME`, -`HOST/OWNER/NAME`, or a URL. Without one, the current clone's repository. - -**JSON fields (repo objects):** `actions_enabled, archived, clone_url, -default_branch, description, empty, fork, forks_count, full_name, id, mirror, -mirror_interval, name, open_issues_count, open_pr_count, original_url, parent, -private, ssh_url, stars_count, template, topics, updated_at, url, website`. - -### Key subcommands - -- `list [] [--starred] [--watched] [--type {fork|source|mirror}] [-L n] - [--page n]` -- `view [] [-b branch] [-w]` -- `create [] [--org ORG] [--private|--public] [--auto-init] - [--readme TMPL] [--gitignores TMPL] [--license TMPL] [--default-branch NAME] - [-d DESC] [--template OWNER/REPO] [--source DIR] [--push] [--clone] - [--as-template]` -- `clone [] [-- ] [-d depth] [--no-upstream] - [-u upstream-name]` — a fork's parent is added as `upstream`; a mirror's - source as `source`. -- `fork [] [--clone] [--org ORG] [--remote] [--remote-name NAME] - [--fork-name NAME] [-- ]` — inside a clone, `--remote` adds the fork - as `origin` and renames the old `origin` to `upstream`. -- `sync [] [-b branch]` — fast-forward a local branch (default: default - branch) from its remote without switching; for a fork/mirror without a local - remote, updates it on the server. JSON: `branch, commit, previous, remote`. -- `set-default [] [-u|--unset] [-v|--view]` — store `gt.repository` in the - clone so commands target it instead of the git remotes. -- `edit`, `delete`, `rename`, `transfer`, `archive`, `unarchive`, `migrate`, - `deploy-key`. - -```bash -gt repo list --starred --json full_name,url -gt repo create project --private --auto-init --license MIT -gt repo create acme/service --template acme/service-template -gt repo create project --source . --push -gt repo fork alice/project --clone -- --depth 1 -gt repo sync --branch release/1.0 -gt repo sync bob/project # update the fork on the server -``` - ---- - -## issue - -```text -gt issue - attachment close comment create edit list reopen timeline view -``` - -`issue list` aliases `issue ls`; `issue create` aliases `issue new`. - -**Issue argument:** `123`, `#123`, a URL, or `OWNER/REPO#123`. - -**JSON fields (issue):** `assignees, author, body, comments, created_at, -due_date, id, kind, labels, milestone, number, ref, state, title, updated_at, -url`. `view`/`edit` add `blocked_by, blocks` (extra requests, only when named). - -### list - -| Flag | Meaning | -| --- | --- | -| `-s, --state {open\|closed\|all}` | default `open` | -| `-a, --assignee`, `-A, --author`, `--mentions` | `@me` for yourself | -| `--no-assignee` | only issues without an assignee | -| `-l, --label names`, `-m, --milestone titles` | filters | -| `--kind {issues\|pulls\|all}` | include PRs (Gitea lists PRs among issues) | -| `-S, --search text` | search titles and bodies | -| `--since`, `--until` | updated window (date, timestamp, or duration ago) | -| `-L, --limit n` (1..1000, default 30), `--page n` | pagination | -| `-w, --web` | open in browser | - -```bash -gt issue list --label bug --state all -gt issue list --assignee @me --json number,title -gt issue list --kind all --milestone v1.0 | cut -f1,2 -``` - -### create - -`-t/--title`, `-b/--body`, `-F/--body-file file|-`, `-e/--editor`, -`-a/--assignee login`, `-l/--label name` (prefix `repo:`/`org:` to disambiguate), -`-m/--milestone`, `-p/--project`, `--ref`, `--deadline DATE`, -`-T/--template name`, `--attachment File`, `-w/--web`. - -Gitea applies labels/milestone/assignees/deadline only to users with issue write -access; otherwise `gt` reports the left-out fields and fails. - -```bash -gt issue create --title "Crash on start" --body "Steps..." \ - --label bug --milestone v1.0 -gt issue create --template "Bug report" -``` - -### edit - -Adds/removes relative to current values, or replaces with `--set-*`: -`--add-label`, `--remove-label`, `--set-labels`, `--add-assignee`, -`--remove-assignee`, `--set-assignees`, `-m/--milestone`, -`--remove-milestone`, `--add-blocked-by`, `--remove-blocked-by`, -`--add-project`, `--remove-project`, `-t/--title`, `-b/--body`, -`-F/--body-file`, `-e/--editor`, `--ref`, `--deadline`. Accepts multiple issues. - -```bash -gt issue edit 12 --title "Crash on start" --add-label bug -gt issue edit 12 13 --add-assignee @me --milestone v1.0 -gt issue edit 12 --add-blocked-by 9 -``` - -### close / reopen / comment / timeline / view / attachment - -- `close {N}... [-c comment]`, `reopen {N}...` -- `comment {N} [-b text] [-F file] [-e] [--edit-last] [--delete-last] - [--attachment File]`; subcommands `list|view|edit|delete`. JSON: `author, - body, created_at, id, issue_number, updated_at, url`. -- `timeline {N} [-L n] [--page n]` — comments and changes, oldest first. -- `view {N} [-c|--comments] [-w]` -- `attachment {list|view|upload|download|edit|delete}` - -```bash -gt issue view 12 --comments -gt issue comment 12 --body "Fixed in #14" -gt issue close 12 13 --comment "Done in #14" -``` - ---- - -## pr - -```text -gt pr - attachment checkout checks clean close comment create diff - edit list merge ready reopen review status timeline view -``` - -`pr list` aliases `pr ls`; `pr create` aliases `pr new`; `pr checkout` aliases -`pr co`. - -**PR argument:** `13`, `#13`, a URL, or a head branch name (e.g. `feature/login` -or `bob:feature/login`). Without one, the PR of the current branch. - -**JSON fields (PR):** `assignees, author, base, body, comments, created_at, -draft, due_date, head, head_remote_deleted, head_repo, head_sha, id, labels, -merge_commit_sha, mergeable, merged, merged_at, merged_by, milestone, number, -review_decision, reviewer_teams, reviewers, reviews, state, title, updated_at, -url`. `reviewers`, `reviewer_teams`, `reviews`, `review_decision` and -`merged_by` on `list` cost extra requests and are fetched only when named. - -### list - -`-s, --state {open|closed|merged|all}` (default `open`), `-a/--assignee`, -`-A/--author`, `--no-assignee`, `-l/--label`, `-m/--milestone`, -`-B/--base branch`, `-H/--head branch|OWNER:BRANCH`, `-d/--draft`, -`-S/--search`, `--sort`, `-L/--limit`, `--page`, `-w/--web`. - -### create - -`--fill` (title/body from commits), `-t/--title`, `-b/--body`, -`-F/--body-file`, `-e/--editor`, `-B/--base`, `-H/--head`, `-d/--draft`, -`-a/--assignee`, `-r/--reviewer`, `--reviewer-team`, `-l/--label`, -`-m/--milestone`, `-p/--project`, `--deadline`, `--attachment`, -`--allow-maintainer-edits` (default true), `--agit` (+ `--topic`), `-w/--web`, -`-y/--yes`. - -Pushes a not-yet-remote branch after confirmation (`--yes` in CI). A branch -without a same-named upstream goes to the fork when origin is a fork, or to the -only remote of your own fork; otherwise to the repository's remote. - -```bash -gt pr create --fill --yes -gt pr create -t "Add login" -b "Closes #1" -B develop -r carol -l enhancement -``` - -### checkout / diff / checks - -- `checkout {N|url|branch} [-b branch] [--detach] [--update]` — local branch - tracking the head. JSON: `branch, commit, detached, remote, tracking`. -- `diff [{N|url|branch}] [--name-only] [--color auto|always|never] [-w]` — clean - diff when piped (`gt pr diff 13 | git apply`). -- `checks [{N|url|branch}] [--watch] [--interval d] [--timeout d] [-w]` — exit - **8** while pending, **1** on failure. JSON: `created_at, description, id, - name, sha, state, updated_at, url`. - -```bash -gt pr checkout 13 --update -gt pr diff 13 | git apply -gt pr checks 13 --watch && gt pr merge 13 -``` - -### merge - -`-s/--method {merge|rebase|rebase-merge|squash|fast-forward-only}` (default: -repo's style), shortcuts `--merge`, `--rebase`, `--squash`, `--auto` -(after checks), `-d/--delete-branch` (also deletes the local head branch when -checked out), `-t/--title`, `-b/--message`, `-F/--message-file`, `-e/--editor`. - -```bash -gt pr merge 13 --squash --delete-branch -gt pr merge 13 --auto --yes -``` - -### review - -Choose the type with `-a/--approve`, `-r/--request-changes` (needs a body), or -`-c/--comment`. Flags: `-b/--body`, `-F/--body-file`, `-e/--editor`, -`--pending` (save for later), `--commit sha`, -`--comments-file file` (JSON array of `path`, `body`, `new_position` or -`old_position`), `-y/--yes`. Subcommands: `create, list, view, delete, submit, -request, cancel-request, comments, reply, resolve, unresolve, dismiss, -undismiss`. JSON: `author, body, comments_count, commit, dismissed, id, -official, stale, state, submitted_at, team, url`. - -On a terminal, no type opens an interactive review that can annotate the diff -in your editor. - -```bash -gt pr review --approve -gt pr review 13 -r -b "Please hash the password" -gt pr review 13 --pending --comments-file inline.json -gt pr review submit 13 --approve -``` - -### status / clean / ready / comment - -- `status [--limit n]` — current branch's PR with checks/review, then your - authored/assigned/review-requested PRs. JSON: `assigned, authored, - current_branch, review_requested`. -- `clean [{...}] [--ignore-sha]` — delete the branch of a merged/closed PR - locally and on Gitea. JSON: `default_branch, local_branch, remote, - remote_branch, remote_deleted, remote_skip_reason, remote_skipped`. -- `ready [{...}] [--undo]` — mark ready/back to draft (toggles `WIP:`/`[WIP]`). -- `comment` — like `issue comment` (JSON: `author, body, created_at, id, - issue_number, updated_at, url`). -- `view`, `edit`, `close`, `reopen`, `timeline`, `attachment`. - ---- - -## release - -```text -gt release - asset create delete download edit list publish upload view -``` - -`release list` aliases `release ls`; `release create` aliases `release new`. - -**JSON fields:** `assets, author, body, created_at, draft, id, prerelease, -published_at, tag, target, title, url`. - -### create - -`gt release create [] [...]` with `-t/--title`, `-n/--notes`, -`-F/--notes-file`, `-e/--editor`, `-d/--draft`, `-p/--prerelease`, -`--target branch|commit` (for a new tag), `--asset File`, `--verify-tag`. - -`gt` **never pushes**: push the tag first, or let Gitea create it with -`--target`. A tag that exists only in your clone is refused without `--target`. - -```bash -gt release create v1.0.0 dist/tool-linux dist/tool-darwin --notes-file CHANGELOG.md -gt release create v1.1.0-rc1 --target release/1.1 --draft --prerelease --title "1.1 RC 1" -``` - -### upload / download / asset / publish / edit / delete / list / view - -- `upload ... [--name NAME] [--clobber]` — JSON per asset: - `created_at, download_count, id, name, size, url`. -- `download [...]`, `asset `, `publish ...`, - `edit ...`, `delete ...`, `list [-L n] [--page n]`, - `view `. - -```bash -gt release upload v1.0.0 dist/tool-linux --clobber -``` - ---- - -## org - -```text -gt org - create delete edit list member view -``` - -Organizations you belong to. Teams are in `team` (see -`commands-misc.md`). - -```bash -gt org list -gt org view acme -gt org member list acme -gt org create acme --description "Acme org" -``` - -## label - -```text -gt label - create delete edit export import list -``` - -Scope with `--org organization` for organization labels; otherwise the -repository's. Addressed by name or ID. JSON: `color, description, exclusive, -id, is_archived, name`. - -`create [-c color] [-d description] [--exclusive] [--archived] -[-f/--force]` — random color without `-c`; `--force` updates on name clash. - -```bash -gt label create bug --color d73a4a --description "Something is broken" -gt label create "priority/high" --exclusive -gt label export labels.yml -gt label import labels.yml -``` - -## milestone - -```text -gt milestone - close create delete edit issue list reopen view -``` - -Addressed by title or ID. `milestone issue` manages the issues/PRs in it. - -```bash -gt milestone create v1.0 --deadline 2026-12-31 --description "First release" -gt milestone list --state open -gt milestone issue list v1.0 -``` - -## branch - -```text -gt branch - create delete list protect rename unprotect view -``` - -Server-side branches (use `git` for local branches). - -```bash -gt branch list -gt branch create release/1.0 --source main -gt branch protect main --required-approvals 2 --status-check ci/build -gt branch view main -``` diff --git a/skills/gitea-gt-cli/references/commands-misc.md b/skills/gitea-gt-cli/references/commands-misc.md deleted file mode 100644 index 946da54..0000000 --- a/skills/gitea-gt-cli/references/commands-misc.md +++ /dev/null @@ -1,331 +0,0 @@ -# Command reference: misc - -Remaining `gt` groups: `team`, `notification`, `search`, `status`, `time`, -`webhook`, `wiki`, `ssh-key`, `api`, `config`, `alias`, `completion`. - -`gt --help` is authoritative for the installed version. - ---- - -## team - -```text -gt team - create delete edit list member repo view -``` - -Teams grant members access to an organization's repositories. In JSON, `access` -is the effective access shown in text (e.g. `write`, `"write (code, issues, -pulls)"`); `permission` is the team-wide level Gitea reports (`none` for a team -that grants access per unit). - -**JSON fields:** `access, all_repositories, can_create_repo, description, id, -name, organization, permission, units`. - -- `create [] [--name NAME] [--permission {read|write|admin}] - [--unit repo.code=write,repo.wiki=read] [--all-repositories] - [--can-create-repo] [-d description]` -- `edit`, `delete`, `view`, `list` -- `member {add|list|remove}` — adding a user to a team of an org also makes them - an org member. -- `repo {add|list|remove}` — repositories named alone (`service`) or `ORG/NAME`. - -```bash -gt team create acme developers --permission write -gt team create acme/reviewers --unit repo.code=read,repo.pulls=write -gt team member add acme/developers bob -gt team repo add acme/developers service -``` - ---- - -## notification - -```text -gt notification - list mark-read mark-unread pin unpin view watch -``` - -Across your whole inbox unless `-R`/`--this-repo` selects a repository. **IDs -are notification thread IDs, not issue numbers.** `--type` is `issue`, `pull`, -`commit`, or `repository`. - -**JSON fields:** `id, number, pinned, repository, state, title, type, unread, -updated_at, url`. - -- `list [--status unread,read,pinned] [--type ...] [--since/--before when] - [-L n] [--page n] [--this-repo]` (alias `ls`) -- `view [--this-repo]` — marks unread as read. -- `mark-read [...] [--all] [--status ...] [--before when] [--this-repo]`, - `mark-unread`, `pin`, `unpin`. -- `watch [--type ...] [--status ...] [--interval 5s] [--timeout d] [--json]` — - streams as they arrive; on a terminal runs until Ctrl-C, otherwise stops after - 1 minute unless `--timeout` is given. - -```bash -gt notification list -gt notification list --type pull --since 24h -gt notification mark-read --all -R alice/project -gt notification watch --type pull --json id,repository,title --timeout 0 | ./notify.sh -``` - ---- - -## search - -```text -gt search - issue pr repo -``` - -Searches the selected instance within what your account can see. Words match -titles and bodies. - -- `search repo [...] [--topic] [--owner OWNER] [--type {fork|source|mirror}] - [--archived[=false]] [--private[=false]] [--sort {alpha|created|updated|size|id}] - [--order {asc|desc}] [-L n] [--page n]` -- `search issue [...] [--assigned] [--authored] [--mentioned] - [-A author] [-l label] [-m milestone] [--owner] [--team team] [-s state] - [--since/--until when] [-L n] [--page n]` (alias `search issues`) -- `search pr [...]` — like issue plus `--review-requested`, `--reviewed` - (instance-wide) (alias `search prs`). - -`search issue`/`pr` JSON: `author, body, created_at, id, number, repository, -state, title, type, updated_at, url`. - -```bash -gt search repo command line -gt search repo --owner acme --archived -gt search issue "login error" -gt search issue crash -R alice/project --label bug --milestone v1.0 -gt search pr --review-requested -``` - ---- - -## status - -```text -gt status [flags] -``` - -Open issues and PRs assigned to you, reviews requested from you, and discussions -mentioning you; in a clone it also lists failing Actions runs. `-R` scopes -everything to one repository. - -Flags: `--limit n` (1..100, default 30), `--runs` (default true). - -JSON: `assigned_issues, failing_runs, host, mentions, pull_requests, -repository, runs_included, runs_repository, user`. - -```bash -gt status -gt status -R alice/project --runs=false -``` - ---- - -## time - -```text -gt time - create delete list reset -``` - -Log time on issues/PRs. Durations use `h`, `m`, `s` (`1h25m` or `"1h 25m"`). -`create` aliases `add`/`log`; `list` aliases `ls`; `delete` aliases `rm`. - -**JSON fields:** `created_at, id, issue_number, issue_title, issue_url, -repository, seconds, user`. - -- `create {issue} ` -- `list [--issue N|URL] [--mine] [--username user|@me] [--since/--until when] - [--total] [-L n] [--page n]` -- `delete {issue} [-y]` -- `reset {issue}` — delete your logged time on an issue. - -```bash -gt time create 12 1h25m -gt time list --issue 12 -gt time list --mine --since 168h -gt time delete 12 8 -``` - ---- - -## webhook - -```text -gt webhook - create delete edit list view -``` - -Scope: repository (default), organization (`--org`), your account (`--account`), -or the instance (`--global`, administrators). Delivery URLs are shown without -credentials/path unless `view --reveal-url`. Signing secrets and authorization -headers are never shown. - -**JSON fields:** `active, branch_filter, content_type, created_at, events, id, -type, updated_at, url`. - -- `create [] [--url URL] [--type {gitea|gogs|slack|discord|dingtalk|telegram|msteams|feishu|matrix|wechatwork|packagist}] - [--events push,issues,...] [--branch-filter glob] [--active[=false]] - [--secret-file file|-] [--authorization-header-file file|-] [--config k=v]` -- `list [-L n] [--page n]` (alias `ls`) -- `view [--reveal-url]`, `edit `, `delete ` - -Events include: `create, delete, fork, push, issues, issues_only, -issue_assign, issue_label, issue_milestone, issue_comment, pull_request, -pull_request_only, pull_request_assign, pull_request_label, -pull_request_milestone, pull_request_comment, pull_request_review, -pull_request_sync, pull_request_review_request, wiki, repository, release, -package, status, workflow_run, workflow_job`. - -```bash -gt webhook create https://ci.example.com/hook --events push,pull_request --secret-file secret.txt -gt webhook list --org acme -gt webhook view 3 --reveal-url -``` - ---- - -## wiki - -```text -gt wiki - create delete edit list revisions view -``` - -**JSON fields (page):** `author, body, commit_count, footer, sha, sidebar, -title, updated_at, url`; `list` returns `author, sha, title, updated_at, url`. - -- `create [] [-t title] [-b body] [-F file|-] [-e] [-m message]` -- `edit <title> [...]`, `view <title>`, `delete <title>`, - `list [-L n] [--page n]` (alias `ls`), `revisions <title>` - -```bash -gt wiki create "Getting Started" --body-file docs/start.md -gt wiki list -R alice/project --json title,url -gt wiki view Home -``` - ---- - -## ssh-key - -```text -gt ssh-key <command> - create delete list view -``` - -Manage the SSH public keys of your account. `create` aliases `add`; `list` -aliases `ls`. - -**JSON fields:** `created_at, fingerprint, id, key, read_only, title`. - -- `create [<file>|-] [-t|--title TITLE]` — without a file, reads stdin. -- `list [-L n] [--page n]`, `view <id>`, `delete <id>` - -```bash -gt ssh-key add ~/.ssh/id_ed25519.pub --title "Work laptop" -gt ssh-key list --json title,fingerprint -``` - ---- - -## api - -```text -gt api <endpoint> [flags] -``` - -Authenticated request to the instance API (path under `/api/v1`, or a full API -URL). `{owner}`, `{repo}` expand to the selected repository; `{branch}` to the -checked-out branch. - -| Flag | Meaning | -| --- | --- | -| `-X, --method` | HTTP method (default GET; POST when a body is supplied) | -| `-f, --raw-field k=v` | String parameter (query for GET/HEAD, JSON body otherwise) | -| `-F, --field k=v` | Typed value: `true`/`false`/`null`, numbers, arrays, `@FILE`, `@-` | -| `-H, --header name:value` | Request header | -| `--input file` | Request body from a file, or `-` | -| `--paginate`, `--max-pages n` | Follow next-page links / list paging | -| `-i, --include` | Print status/headers to stderr | -| `--output-file file` | Write the whole response to a file | -| `--jq expr` | Filter each JSON response (jq not required) | -| `--silent`, `--verbose` | No body / request+response to stderr | - -Non-2xx responses print the body and fail with the HTTP status. - -```bash -gt api repos/{owner}/{repo}/issues -f state=open -gt api user -F name=alice -F admin=true -gt api repos/{owner}/{repo}/branches --paginate --jq '.[].name' -``` - ---- - -## config - -```text -gt config <command> - get list path set -``` - -Preferences live in `config.yml`, instance settings in `hosts.yml`, in the -configuration directory (`$GITEA_CLI_CONFIG_DIR`, else `gitea-cli` under the XDG -config dir). `gt config path` prints both files. - -- `get <key> [--show-source]`, `list` (alias `ls`, add `--host` for instance - settings), `set <key> <value> [--host URL] [--user NAME]`. -- Keys: `default_host`, `git_protocol`, `editor`, `prompt`, `pager`, `browser`, - `color`, `hyperlinks`, `markdown`, `remote`, `http_timeout`; instance: - `user`, `ssh_host`, `insecure`, `git_protocol`, `oauth_client_id`, `headers`, - `client_cert`, `client_key`; account: `ssh_key`, `ssh_agent`, - `ssh_certificate_principal`, `ssh_key_fingerprint`. - -```bash -gt config path -gt config set editor "code --wait" -gt config set ssh_host git.example.com:2222 --host https://example.com -gt config get default_host --show-source -``` - ---- - -## alias - -```text -gt alias <command> - delete list set -``` - -An alias expands to a `gt` command with arguments, before `gt` runs it. `$1`, -`$2`, ... take positional arguments; other arguments follow the expansion. No -shell is run; built-ins always win. - -- `set <name> <expansion> [--clobber]` -- `list` (alias `ls`), `delete [<name>...] [--all]` (alias `rm`) - -```bash -gt alias set il "issue list --label bug" -gt alias set review 'pr review $1 --approve' -gt alias list -``` - ---- - -## completion - -```text -gt completion <command> - bash fish powershell zsh -``` - -Generate the shell completion script. Completion offers `--json` field names. - -```bash -gt completion bash > /etc/bash_completion.d/gt -gt completion zsh > "${fpath[1]}/_gt" -``` diff --git a/skills/gitea-gt-cli/references/discovery.md b/skills/gitea-gt-cli/references/discovery.md new file mode 100644 index 0000000..8d59148 --- /dev/null +++ b/skills/gitea-gt-cli/references/discovery.md @@ -0,0 +1,110 @@ +# Discovery: notifications, search, status, time + +Finding and triaging work across repositories. `gt <cmd> --help` is +authoritative. Global flags are in SKILL.md. + +## notification + +```text +gt notification <command> + list mark-read mark-unread pin unpin view watch +``` + +Across your whole inbox unless `-R`/`--this-repo` selects a repository. **IDs +are notification thread IDs, not issue numbers.** `--type` is `issue`, `pull`, +`commit`, or `repository`. + +**JSON fields:** `id, number, pinned, repository, state, title, type, unread, +updated_at, url`. + +- `list [--status unread,read,pinned] [--type ...] [--since/--before when] + [-L n] [--page n] [--this-repo]` (alias `ls`) +- `view <id> [--this-repo]` — marks unread as read. +- `mark-read [<id>...] [--all] [--status ...] [--before when] [--this-repo]`, + `mark-unread`, `pin`, `unpin`. +- `watch [--type ...] [--status ...] [--interval 5s] [--timeout d] [--json]` — + streams as they arrive; on a terminal runs until Ctrl-C, otherwise stops after + 1 minute unless `--timeout` is given. + +```bash +gt notification list +gt notification list --type pull --since 24h +gt notification mark-read --all -R alice/project +gt notification watch --type pull --json id,repository,title --timeout 0 | ./notify.sh +``` + +## search + +```text +gt search <command> + issue pr repo +``` + +Searches the selected instance within what your account can see. Words match +titles and bodies. + +- `search repo [<query>...] [--topic] [--owner OWNER] [--type {fork|source|mirror}] + [--archived[=false]] [--private[=false]] [--sort {alpha|created|updated|size|id}] + [--order {asc|desc}] [-L n] [--page n]` +- `search issue [<query>...] [--assigned] [--authored] [--mentioned] + [-A author] [-l label] [-m milestone] [--owner] [--team team] [-s state] + [--since/--until when] [-L n] [--page n]` (alias `search issues`) +- `search pr [<query>...]` — like issue plus `--review-requested`, `--reviewed` + (instance-wide) (alias `search prs`). + +`search issue`/`pr` JSON: `author, body, created_at, id, number, repository, +state, title, type, updated_at, url`. + +```bash +gt search repo command line +gt search repo --owner acme --archived +gt search issue "login error" +gt search issue crash -R alice/project --label bug --milestone v1.0 +gt search pr --review-requested +``` + +## status + +```text +gt status [flags] +``` + +Open issues and PRs assigned to you, reviews requested from you, and discussions +mentioning you; in a clone it also lists failing Actions runs. `-R` scopes +everything to one repository. + +Flags: `--limit n` (1..100, default 30), `--runs` (default true). + +JSON: `assigned_issues, failing_runs, host, mentions, pull_requests, +repository, runs_included, runs_repository, user`. + +```bash +gt status +gt status -R alice/project --runs=false +``` + +## time + +```text +gt time <command> + create delete list reset +``` + +Log time on issues/PRs. Durations use `h`, `m`, `s` (`1h25m` or `"1h 25m"`). +`create` aliases `add`/`log`; `list` aliases `ls`; `delete` aliases `rm`. + +**JSON fields:** `created_at, id, issue_number, issue_title, issue_url, +repository, seconds, user`. + +- `create {issue} <duration>` +- `list [--issue N|URL] [--mine] [--username user|@me] [--since/--until when] + [--total] [-L n] [--page n]` +- `delete {issue} <time-id> [-y]` +- `reset {issue}` — delete your logged time on an issue. + +```bash +gt time create 12 1h25m +gt time list --issue 12 +gt time list --mine --since 168h +gt time delete 12 8 +``` diff --git a/skills/gitea-gt-cli/references/instance.md b/skills/gitea-gt-cli/references/instance.md new file mode 100644 index 0000000..22dac82 --- /dev/null +++ b/skills/gitea-gt-cli/references/instance.md @@ -0,0 +1,189 @@ +# Instance: webhooks, wiki, keys, API, config, admin + +Instance- and account-level commands. `gt <cmd> --help` is authoritative. +Global flags are in SKILL.md. + +## webhook + +```text +gt webhook <command> + create delete edit list view +``` + +Scope: repository (default), organization (`--org`), your account (`--account`), +or the instance (`--global`, administrators). Delivery URLs often carry +credentials, so `gt` shows them without user info and query (and without the path +for chat services); `view --reveal-url` shows a URL whole. Signing secrets and +authorization headers are never shown. + +**JSON fields:** `active, branch_filter, content_type, created_at, events, id, +type, updated_at, url`. + +- `create [<url>] [--url URL] [--type {gitea|gogs|slack|discord|dingtalk|telegram|msteams|feishu|matrix|wechatwork|packagist}] + [--events push,issues,...] [--branch-filter glob] [--active[=false]] + [--secret-file file|-] [--authorization-header-file file|-] [--config k=v]` +- `list [-L n] [--page n]` (alias `ls`) +- `view <id> [--reveal-url]`, `edit <id>`, `delete <id>` + +Events include: `create, delete, fork, push, issues, issues_only, issue_assign, +issue_label, issue_milestone, issue_comment, pull_request, pull_request_only, +pull_request_assign, pull_request_label, pull_request_milestone, +pull_request_comment, pull_request_review, pull_request_sync, +pull_request_review_request, wiki, repository, release, package, status, +workflow_run, workflow_job`. + +```bash +gt webhook create https://ci.example.com/hook --events push,pull_request --secret-file secret.txt +gt webhook list --org acme +gt webhook view 3 --reveal-url +``` + +## wiki + +```text +gt wiki <command> + create delete edit list revisions view +``` + +**JSON fields (page):** `author, body, commit_count, footer, sha, sidebar, +title, updated_at, url`; `list` returns `author, sha, title, updated_at, url`. + +- `create [<title>] [-t title] [-b body] [-F file|-] [-e] [-m message]` +- `edit <title> [...]`, `view <title>`, `delete <title>`, + `list [-L n] [--page n]` (alias `ls`), `revisions <title> [--page n]` + +```bash +gt wiki create "Getting Started" --body-file docs/start.md +gt wiki list -R alice/project --json title,url +gt wiki view Home +``` + +## ssh-key + +```text +gt ssh-key <command> + create delete list view +``` + +Manage the SSH public keys of your account. `create` aliases `add`; `list` +aliases `ls`. + +**JSON fields:** `created_at, fingerprint, id, key, read_only, title`. + +- `create [<file>|-] [-t|--title TITLE]` — without a file, reads stdin; the + title defaults to the key comment, then the computer's name. +- `list [-L n] [--page n]`, `view <id>`, `delete <id>` + +```bash +gt ssh-key add ~/.ssh/id_ed25519.pub --title "Work laptop" +gt ssh-key list --json title,fingerprint +``` + +## api + +```text +gt api <endpoint> [flags] +``` + +Authenticated request to the instance API (path under `/api/v1`, or a full API +URL). `{owner}`, `{repo}` expand to the selected repository; `{branch}` to the +checked-out branch. + +| Flag | Meaning | +| --- | --- | +| `-X, --method` | HTTP method (default GET; POST when a body is supplied) | +| `-f, --raw-field k=v` | String parameter (query for GET/HEAD, JSON body otherwise) | +| `-F, --field k=v` | Typed value: `true`/`false`/`null`, numbers, arrays, `@FILE`, `@-` | +| `-H, --header name:value` | Request header | +| `--input file` | Request body from a file, or `-` | +| `--paginate`, `--max-pages n` | Follow next-page links / list paging | +| `-i, --include` | Print status/headers to stderr | +| `--output-file file` | Write the whole response to a file | +| `--jq expr` | Filter each JSON response (jq not required) | +| `--silent`, `--verbose` | No body / request+response to stderr | + +Non-2xx responses print the body and fail with the HTTP status. + +```bash +gt api repos/{owner}/{repo}/issues -f state=open +gt api user -F name=alice -F admin=true +gt api repos/{owner}/{repo}/branches --paginate --jq '.[].name' +``` + +## config + +```text +gt config <command> + get list path set +``` + +Preferences live in `config.yml`, instance settings in `hosts.yml`, in the +configuration directory (`$GITEA_CLI_CONFIG_DIR`, else `gitea-cli` under the XDG +config dir). `gt config path` prints both files. + +- `get <key> [--show-source]`, `list` (alias `ls`, add `--host` for instance + settings), `set <key> <value> [--host URL] [--user NAME]`. +- Keys: `default_host`, `git_protocol`, `editor`, `prompt`, `pager`, `browser`, + `color`, `hyperlinks`, `markdown`, `remote`, `http_timeout`; instance: + `user`, `ssh_host`, `insecure`, `git_protocol`, `oauth_client_id`, `headers`, + `client_cert`, `client_key`; account: `ssh_key`, `ssh_agent`, + `ssh_certificate_principal`, `ssh_key_fingerprint`. + +```bash +gt config path +gt config set editor "code --wait" +gt config set ssh_host git.example.com:2222 --host https://example.com +gt config get default_host --show-source +``` + +## alias + +```text +gt alias <command> + delete list set +``` + +An alias expands to a `gt` command with arguments, before `gt` runs it. `$1`, +`$2`, ... take positional arguments; other arguments follow the expansion. No +shell is run; built-in commands always win over an alias of the same name. + +- `set <name> <expansion> [--clobber]` +- `list` (alias `ls`), `delete [<name>...] [--all]` (alias `rm`) + +```bash +gt alias set il "issue list --label bug" +gt alias set review 'pr review $1 --approve' +gt alias list +``` + +## completion + +```text +gt completion <command> + bash fish powershell zsh +``` + +Generate the shell completion script. Completion offers `--json` field names. + +```bash +gt completion bash > /etc/bash_completion.d/gt +gt completion zsh > "${fpath[1]}/_gt" +``` + +## admin + +```text +gt admin <command> + user (list, view, create, edit, delete) +``` + +Instance administration; requires an administrator account. (`--sudo user` on +other commands acts as another user.) JSON: `active, admin, created_at, +description, email, full_name, id, location, prohibit_login, restricted, url, +username, visibility, website`. + +```bash +gt admin user list +gt admin user list --query bob +gt admin user create alice --email alice@example.com +``` diff --git a/skills/gitea-gt-cli/references/issues.md b/skills/gitea-gt-cli/references/issues.md new file mode 100644 index 0000000..97d7933 --- /dev/null +++ b/skills/gitea-gt-cli/references/issues.md @@ -0,0 +1,142 @@ +# Issues, labels, milestones + +Issue management plus repository/organization labels and milestones. +`gt <cmd> --help` is authoritative. Global/repository-selection flags are in +SKILL.md. + +## issue + +```text +gt issue <command> + attachment close comment create edit list reopen timeline view +``` + +`issue list` aliases `issue ls`; `issue create` aliases `issue new`. + +**Issue argument:** `123`, `#123`, a URL, or `OWNER/REPO#123`. + +**JSON fields (issue):** `assignees, author, body, comments, created_at, +due_date, id, kind, labels, milestone, number, ref, state, title, updated_at, +url`. `view`/`edit` add `blocked_by, blocks` (extra requests, only when named). + +Gitea lists pull requests among issues, so most issue commands also accept a PR +number. + +### list + +| Flag | Meaning | +| --- | --- | +| `-s, --state {open\|closed\|all}` | default `open` | +| `-a, --assignee`, `-A, --author`, `--mentions` | `@me` for yourself | +| `--no-assignee` | only issues without an assignee | +| `-l, --label names`, `-m, --milestone titles` | filters | +| `--kind {issues\|pulls\|all}` | include PRs | +| `-S, --search text` | search titles and bodies | +| `--since`, `--until` | updated window (date, timestamp, or duration ago) | +| `-L, --limit n` (1..1000, default 30), `--page n` | pagination | +| `-w, --web` | open in browser | + +```bash +gt issue list --label bug --state all +gt issue list --assignee @me --json number,title +gt issue list --kind all --milestone v1.0 | cut -f1,2 +``` + +### create + +`-t/--title`, `-b/--body`, `-F/--body-file file|-`, `-e/--editor`, +`-a/--assignee login`, `-l/--label name` (prefix `repo:`/`org:` to disambiguate), +`-m/--milestone`, `-p/--project`, `--ref`, `--deadline DATE`, +`-T/--template name`, `--attachment File`, `-w/--web`. + +Without flags on a terminal, a form asks for title and body, then optionally +assignees, a milestone, labels and a due date. Gitea applies +labels/milestone/assignees/deadline only to users with issue write access; +otherwise `gt` reports the left-out fields and fails. + +```bash +gt issue create --title "Crash on start" --body "Steps..." \ + --label bug --milestone v1.0 +gt issue create --template "Bug report" +``` + +### edit + +Adds/removes relative to current values, or replaces with `--set-*`: +`--add-label`, `--remove-label`, `--set-labels`, `--add-assignee`, +`--remove-assignee`, `--set-assignees`, `-m/--milestone`, +`--remove-milestone`, `--add-blocked-by`, `--remove-blocked-by`, +`--add-project`, `--remove-project`, `-t/--title`, `-b/--body`, +`-F/--body-file`, `-e/--editor`, `--ref`, `--deadline`. Accepts multiple issues. + +```bash +gt issue edit 12 --title "Crash on start" --add-label bug +gt issue edit 12 13 --add-assignee @me --milestone v1.0 +gt issue edit 12 --add-blocked-by 9 +``` + +### close / reopen / comment / timeline / view / attachment + +- `close {N}... [-c comment]`, `reopen {N}...` +- `comment {N} [-b text] [-F file] [-e] [--edit-last] [--delete-last] + [--attachment File]`; subcommands `list|view|edit|delete`. JSON: `author, + body, created_at, id, issue_number, updated_at, url`. +- `timeline {N} [-L n] [--page n]` — comments and changes, oldest first. +- `view {N} [-c|--comments] [-w]` +- `attachment {list|view|upload|download|edit|delete}` + +```bash +gt issue view 12 --comments +gt issue comment 12 --body "Fixed in #14" +gt issue close 12 13 --comment "Done in #14" +``` + +## label + +```text +gt label <command> + create delete edit export import list +``` + +Scope with `--org organization` for organization labels; otherwise the +repository's. Addressed by name or ID. JSON: `color, description, exclusive, +id, is_archived, name`. + +- `create <name> [-c color] [-d description] [--exclusive] [--archived] + [-f/--force]` — random color without `-c`; `--force` updates on name clash. +- `list`, `edit`, `delete` +- `export [-O|--output file]` and `import <file> [-f|--force]` — a label file, + one label per line: `#color name ;description ;flags`. `gt label export` + writes this format; Gitea label templates use it. `-` reads/writes stdin. + +```bash +gt label create bug --color d73a4a --description "Something is broken" +gt label create "priority/high" --exclusive +gt label export --org acme --output labels.txt +gt label export -R alice/old | gt label import - -R alice/new +``` + +## milestone + +```text +gt milestone <command> + close create delete edit issue list reopen view +``` + +`milestone list` aliases `milestone ls`; `milestone create` aliases +`milestone new`. Addressed by title or ID. `milestone issue` manages the +issues/PRs in it. JSON: `closed_issues, description, due_on, id, open_issues, +state, title`. + +- `create [<title>] [-t title] [-d description] [-F desc-file] [-e] + [--deadline date] [--state {open|closed}] [-f/--force]` — `--force` updates an + existing milestone of the same title. +- `list [-s {open|closed|all}] [-L n] [--page n]`, `view`, `edit`, `close`, + `reopen`, `delete` +- `issue list <milestone>` etc. + +```bash +gt milestone create v1.0 --deadline 2026-12-31 --description "First release" +gt milestone list --state open +gt milestone issue list v1.0 +``` diff --git a/skills/gitea-gt-cli/references/organizations.md b/skills/gitea-gt-cli/references/organizations.md new file mode 100644 index 0000000..2493aec --- /dev/null +++ b/skills/gitea-gt-cli/references/organizations.md @@ -0,0 +1,64 @@ +# Organizations and teams + +Organization management and team access. `gt <cmd> --help` is authoritative. +Global flags are in SKILL.md. + +## org + +```text +gt org <command> + create delete edit list member view +``` + +Organizations you belong to. + +- `list`, `view <org>` +- `create <name> [-d description] [--full-name NAME] [--location LOC] + [--website URL] [--visibility {public|limited|private}] + [--repo-admins-can-change-team-access[=false]]` +- `edit <org>`, `delete <org>` +- `member {list|add|remove}` — `member list <org> [--public]`; Gitea lists every + membership as public to administrators, so for them `gt` checks each one's + visibility (one request per member) unless the output omits it. + +JSON: `description, full_name, id, location, name, repo_admin_change_team_access, +visibility, website`. + +```bash +gt org list +gt org create acme --full-name "ACME Corp" +gt org create acme-internal --visibility private +gt org member list acme --public +``` + +## team + +```text +gt team <command> + create delete edit list member repo view +``` + +Teams grant members access to an organization's repositories. In JSON, `access` +is the effective access shown in text (e.g. `write`, `"write (code, issues, +pulls)"`); `permission` is the team-wide level Gitea reports (`none` for a team +that grants access per unit). + +**JSON fields:** `access, all_repositories, can_create_repo, description, id, +name, organization, permission, units`. + +- `create <org> [<name>] [--name NAME] [--permission {read|write|admin}] + [--unit repo.code=write,repo.wiki=read] [--all-repositories] + [--can-create-repo] [-d description]` — `--permission` grants every repository + unit; `--unit` sets single units and overrides `--permission` per unit. +- `edit <team>`, `delete <team>`, `view <team>`, `list <org>` +- `member {add|list|remove} <team> [<username>...]` — a team is `ORG/TEAM` or a + numeric ID; adding a user also makes them an org member. +- `repo {add|list|remove} <team> [<repository>...]` — repositories named alone + (`service`) or `ORG/NAME`. + +```bash +gt team create acme developers --permission write +gt team create acme/reviewers --unit repo.code=read,repo.pulls=write +gt team member add acme/developers bob +gt team repo add acme/developers service +``` diff --git a/skills/gitea-gt-cli/references/pull-requests.md b/skills/gitea-gt-cli/references/pull-requests.md new file mode 100644 index 0000000..924e8e5 --- /dev/null +++ b/skills/gitea-gt-cli/references/pull-requests.md @@ -0,0 +1,133 @@ +# Pull requests (`gt pr`) + +Pull requests, including reviews, checks, diff, checkout and merge. +`gt <cmd> --help` is authoritative. Global/repository-selection flags are in +SKILL.md. + +```text +gt pr <command> + attachment checkout checks clean close comment create diff + edit list merge ready reopen review status timeline view +``` + +`pr list` aliases `pr ls`; `pr create` aliases `pr new`; `pr checkout` aliases +`pr co`. + +**PR argument:** `13`, `#13`, a URL, or a head branch name (e.g. `feature/login` +or `bob:feature/login`). Without one, the PR of the current branch. + +**JSON fields (PR):** `assignees, author, base, body, comments, created_at, +draft, due_date, head, head_remote_deleted, head_repo, head_sha, id, labels, +merge_commit_sha, mergeable, merged, merged_at, merged_by, milestone, number, +review_decision, reviewer_teams, reviewers, reviews, state, title, updated_at, +url`. On `list`, `reviewers`, `reviewer_teams`, `reviews`, `review_decision` and +`merged_by` cost extra requests and are fetched only when named. + +## list + +`-s, --state {open|closed|merged|all}` (default `open`), `-a/--assignee`, +`-A/--author`, `--no-assignee`, `-l/--label`, `-m/--milestone`, +`-B/--base branch`, `-H/--head branch|OWNER:BRANCH`, `-d/--draft`, +`-S/--search`, `--sort`, `-L/--limit`, `--page`, `-w/--web`. + +`review_decision` is `changes_requested`, `approved`, `review_required` or +empty. + +```bash +gt pr list --author @me --state all +gt pr list --json number,title,head --jq '.[] | select(.head == "feature/login")' +``` + +## create + +`--fill` (title/body from commits), `-t/--title`, `-b/--body`, +`-F/--body-file`, `-e/--editor`, `-B/--base`, `-H/--head`, `-d/--draft`, +`-a/--assignee`, `-r/--reviewer`, `--reviewer-team`, `-l/--label`, +`-m/--milestone`, `-p/--project`, `--deadline`, `--attachment`, +`--allow-maintainer-edits` (default true), `--agit` (+ `--topic`), `-w/--web`, +`-y/--yes`. + +Creates from the current branch, or `--head`. Pushes a not-yet-remote branch +after a confirmation (`--yes` in CI). A branch without a same-named upstream +goes to the fork when origin is a fork, or to the only remote of your own fork; +otherwise to the repository's remote. Any flag skips the interactive questions; +the title is then `--title`, else the commit message of a single-commit branch, +else the branch name. + +```bash +gt pr create --fill --yes +gt pr create -t "Add login" -b "Closes #1" -B develop -r carol -l enhancement +``` + +## checkout / diff / checks + +- `checkout {N|url|branch} [-b branch] [--detach] [--update]` — local branch + tracking the head, so `git push` updates it. `--update` fast-forwards an + existing branch and rejects divergence. JSON: `branch, commit, detached, + remote, tracking`. +- `diff [{N|url|branch}] [--name-only] [--color auto|always|never] [-w]` — clean + diff when piped (`gt pr diff 13 | git apply`); colored and paged on a + terminal. +- `checks [{N|url|branch}] [--watch] [--interval d] [--timeout d] [-w]` — latest + status of each check. Exits **8** while pending, **1** on failure. JSON: + `created_at, description, id, name, sha, state, updated_at, url`. + +```bash +gt pr checkout 13 --update +gt pr diff 13 | git apply +gt pr checks 13 --watch && gt pr merge 13 +``` + +## merge + +`-s/--method {merge|rebase|rebase-merge|squash|fast-forward-only}` (default: +repo's style), shortcuts `--merge`, `--rebase`, `--squash`, `--auto` +(merge once required checks succeed), `-d/--delete-branch` (also deletes the +local head branch when checked out, switching to the base), `-t/--title`, +`-b/--message`, `-F/--message-file`, `-e/--editor`. + +```bash +gt pr merge 13 --squash --delete-branch +gt pr merge 13 --auto --yes +``` + +## review + +Choose the type with `-a/--approve`, `-r/--request-changes` (needs a body), or +`-c/--comment`. Flags: `-b/--body`, `-F/--body-file`, `-e/--editor`, +`--pending` (save for later), `--commit sha`, +`--comments-file file` (JSON array of `path`, `body`, `new_position` or +`old_position`), `-y/--yes`. Subcommands: `create, list, view, delete, submit, +request, cancel-request, comments, reply, resolve, unresolve, dismiss, +undismiss`. JSON: `author, body, comments_count, commit, dismissed, id, +official, stale, state, submitted_at, team, url`. + +On a terminal, no type opens an interactive review that can annotate the diff in +your editor (lines you start with `#` become inline comments). + +```bash +gt pr review --approve +gt pr review 13 -r -b "Please hash the password" +gt pr review 13 --pending --comments-file inline.json +gt pr review submit 13 --approve +``` + +## status / clean / ready / comment / view / edit + +- `status [--limit n]` — current branch's PR with checks/review, then your + authored/assigned/review-requested PRs. JSON: `assigned, authored, + current_branch, review_requested`. +- `clean [{...}] [--ignore-sha]` — delete the branch of a merged/closed PR + locally and on Gitea. JSON: `default_branch, local_branch, remote, + remote_branch, remote_deleted, remote_skip_reason, remote_skipped`. +- `ready [{...}] [--undo]` — mark ready/back to draft (toggles `WIP:`/`[WIP]`). +- `comment [{...}]` — like `issue comment` (JSON: `author, body, created_at, id, + issue_number, updated_at, url`); subcommands `list|view|edit|delete`. +- `view [{...}] [-c|--comments] [-w]`, `edit`, `close`, `reopen`, `timeline`, + `attachment`. + +```bash +gt pr status +gt pr ready +gt pr clean 13 +``` diff --git a/skills/gitea-gt-cli/references/releases.md b/skills/gitea-gt-cli/references/releases.md new file mode 100644 index 0000000..2b972da --- /dev/null +++ b/skills/gitea-gt-cli/references/releases.md @@ -0,0 +1,53 @@ +# Releases (`gt release`) + +Releases and their assets. `gt <cmd> --help` is authoritative. Global/repository +selection flags are in SKILL.md. + +```text +gt release <command> + asset create delete download edit list publish upload view +``` + +`release list` aliases `release ls`; `release create` aliases `release new`. + +**JSON fields:** `assets, author, body, created_at, draft, id, prerelease, +published_at, tag, target, title, url`. + +## create + +`gt release create [<tag>] [<file>...]` with `-t/--title`, `-n/--notes`, +`-F/--notes-file`, `-e/--editor`, `-d/--draft`, `-p/--prerelease`, +`--target branch|commit` (for a new tag), `--asset File`, `--verify-tag`. +Files after the tag are uploaded as assets; the title defaults to the tag. + +`gt` **never pushes**: commits and tags that exist only in your clone are not on +the server, so push them first (`git push <remote> <tag>`). A tag that exists +only in your clone is refused unless `--target` says where Gitea creates it; +`--verify-tag` refuses any tag not on the server yet. + +```bash +gt release create v1.0.0 dist/tool-linux dist/tool-darwin --notes-file CHANGELOG.md +gt release create v1.1.0-rc1 --target release/1.1 --draft --prerelease --title "1.1 RC 1" +``` + +## upload / download + +- `upload <tag> <file>... [--name NAME] [--clobber]` — an asset of the same name + is replaced only with `--clobber`. JSON per asset: `created_at, + download_count, id, name, size, url`. +- `download [<tag>] [<asset>...] [-A|--archive {zip|tar.gz}] [-p|--pattern glob] + [-D|--dir dir] [-O|--output file|-] [--clobber] [--skip-existing]` — latest + release without a tag; `--archive` downloads source code instead. + +```bash +gt release upload v1.0.0 dist/tool-linux --clobber +gt release download v1.0.0 --pattern '*linux*' --dir dist +gt release download v1.0.0 --archive zip +``` + +## asset / publish / edit / delete / list / view + +- `asset {list|upload|download|delete|...}` — manage assets individually. +- `publish <tag>...` — publish draft releases. +- `edit <tag>...`, `delete <tag>...`, `list [-L n] [--page n]`, + `view [<tag>] [-w]` (latest without a tag). diff --git a/skills/gitea-gt-cli/references/repos.md b/skills/gitea-gt-cli/references/repos.md new file mode 100644 index 0000000..d504808 --- /dev/null +++ b/skills/gitea-gt-cli/references/repos.md @@ -0,0 +1,84 @@ +# Repositories (`gt repo`, `gt branch`) + +Repository management plus server-side branches. `gt <cmd> --help` is +authoritative. Global/repository-selection flags are in SKILL.md. + +## repo + +```text +gt repo <command> + archive clone create delete deploy-key edit fork list migrate + rename set-default sync transfer unarchive view +``` + +`repo list` aliases `repo ls`; `repo create` aliases `repo new`. + +**Repository argument** (where accepted): `NAME` (one of yours), `OWNER/NAME`, +`HOST/OWNER/NAME`, or a URL. Without one, the current clone's repository. + +**JSON fields (repo objects):** `actions_enabled, archived, clone_url, +default_branch, description, empty, fork, forks_count, full_name, id, mirror, +mirror_interval, name, open_issues_count, open_pr_count, original_url, parent, +private, ssh_url, stars_count, template, topics, updated_at, url, website`. + +### Key subcommands + +- `list [<owner>] [--starred] [--watched] [--type {fork|source|mirror}] [-L n] + [--page n]` +- `view [<repo>] [-b branch] [-w]` — description, state, counts, clone URLs, + then the rendered README. +- `create [<name>] [--org ORG] [--private|--public] [--auto-init] + [--readme TMPL] [--gitignores TMPL] [--license TMPL] [--default-branch NAME] + [-d DESC] [--template OWNER/REPO] [--source DIR] [--push] [--clone] + [--as-template]` — `--source`/`--push` publish a local repo; + `--template` copies another; `--auto-init` adds a first commit. +- `clone <repo> [<dir>] [-- <gitflags>] [-d depth] [--no-upstream] + [-u upstream-name]` — a fork's parent is added as `upstream`; a mirror's + source as `source`. `gt` commands in the clone then target the parent. +- `fork [<repo>] [--clone] [--org ORG] [--remote] [--remote-name NAME] + [--fork-name NAME] [-- <gitflags>]` — inside a clone, `--remote` adds the fork + as `origin` and renames the old `origin` to `upstream`. +- `sync [<repo>] [-b branch]` — fast-forward a local branch (default: default + branch) from its remote without switching; for a fork/mirror without a local + remote, updates it on the server. JSON: `branch, commit, previous, remote`. +- `set-default [<repo>] [-u|--unset] [-v|--view]` — store `gt.repository` in the + clone so commands target it instead of the git remotes. +- `edit`, `delete`, `rename`, `transfer`, `archive`, `unarchive`, `migrate`, + `deploy-key`. + +```bash +gt repo list --starred --json full_name,url +gt repo create project --private --auto-init --license MIT +gt repo create acme/service --template acme/service-template +gt repo create project --source . --push +gt repo fork alice/project --clone -- --depth 1 +gt repo sync --branch release/1.0 +gt repo sync bob/project # update the fork on the server +``` + +## branch + +```text +gt branch <command> + create delete list protect rename unprotect view +``` + +Server-side branches (use `git` for local branches). JSON: `can_merge, +can_push, message, name, protected, required_approvals, sha, updated_at`. + +- `create <branch> [-s|--source branch|tag|commit]` — default branch unless + `--source` names one. +- `list`, `view <branch> [-w]`, `rename`, `delete` +- `protect <branch>... [--pattern glob] [--required-approvals n] + [--allow-push user|ORG/TEAM] [--status-check name] [--dismiss-stale-approvals] + [--block-on-rejected-reviews]` — by default nobody pushes directly and PRs + need one approval. `--pattern` protects every matching branch; existing rules + change only the named settings. +- `unprotect <branch>...` + +```bash +gt branch list +gt branch create release/1.0 --source main +gt branch protect main --required-approvals 2 --status-check ci/build +gt branch protect --pattern 'release/*' --allow-push acme/release +``` diff --git a/skills/gitea-gt-cli/references/workflows.md b/skills/gitea-gt-cli/references/workflows.md new file mode 100644 index 0000000..38ba96f --- /dev/null +++ b/skills/gitea-gt-cli/references/workflows.md @@ -0,0 +1,74 @@ +# Workflows (recipes) + +End-to-end recipes for common tasks. For per-command flags and JSON fields, read +the group file in this directory (listed in SKILL.md's command map). All flags +are from `gt` 0.1.0; `gt <cmd> --help` is authoritative. + +## Issue lifecycle + +```bash +gt issue list --assignee @me --state open +gt issue view 12 --comments +gt issue create --title "Crash on start" --body "Steps..." --label bug --milestone v1.0 +gt issue edit 12 --add-label triage --add-assignee @me +gt issue comment 12 --body "Fixed in #14" +gt issue close 12 --comment "Done in #14" +``` + +## Pull requests: create → checks → review → merge + +```bash +gt pr create --fill # push branch, open PR, title/body from commits +gt pr create --fill --yes # non-interactive: also push without asking +gt pr list --author @me --state all +gt pr checkout 13 --update # local branch tracking the PR head +gt pr diff 13 | git apply # pipe clean diff (git apply works) +gt pr checks 13 --watch # waits; exit 8 while pending, 1 if a check failed +gt pr review --approve +gt pr review 13 --request-changes -b "Please hash the password" +gt pr merge 13 --squash --delete-branch +``` + +A branch that is not on the remote is pushed first, after a confirmation; in CI +pass `--yes` (or `--no-input` will fail rather than prompt). See +[pull-requests.md](pull-requests.md) for fork handling. + +## Actions: dispatch, watch, logs, artifacts + +```bash +gt workflow list +gt workflow run deploy.yml --ref main --field env=staging +gt run list --workflow CI --branch main --status failure +gt run watch 34 --timeout 10m && echo deployed +gt run view 34 --log +gt run logs 34 --job build --follow +gt run download 34 --name build --dir dist +gt secret set DEPLOY_TOKEN +``` + +`gt run watch` and `gt workflow run --follow` **fail when the run completes +without success**, so they chain well with `&&`. See [actions.md](actions.md). + +## Releases + +```bash +gt release create v1.0.0 dist/tool-linux dist/tool-darwin --notes-file CHANGELOG.md +gt release list +gt release upload v1.0.0 dist/tool-darwin --clobber +gt release download v1.0.0 +``` + +`gt release create` never pushes a tag: push it first (`git push origin v1.0.0`) +or let Gitea create it with `--target`. See [releases.md](releases.md). + +## Fork, clone and keep in sync + +```bash +gt repo fork --remote # inside a clone: add fork as origin, rename old origin to upstream +gt repo clone alice/project src --depth 1 +gt repo sync # fast-forward the default branch from its remote +gt repo sync bob/project # fork without a local remote: update it on the server +``` + +In a clone with both `upstream` and `origin`, `gt` targets `upstream` (like +`gh`). See [repos.md](repos.md).