gitea-gt-cli/references/instance.md

# 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  test  view
```

Scope: repository (default), organization (`--org`), your account (`--account`),
or the instance's system webhooks (`--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>] [--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]`
- `edit <id>` — only the flags you pass change; Gitea drops the stored
  authorization header on every edit, so pass it again (or `--clear-authorization`).
  Signing secrets cannot be changed: recreate the webhook.
- `list [-L n] [--page n]` (alias `ls`), `view <id> [--reveal-url]`,
  `delete <id>`, `test <id>` — send a test push delivery (repository webhooks
  only).

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 test 3
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`;
`revisions` returns `author, created_at, message, sha`.

- `create [<title>] [-t title] [-b body] [-F file|-] [-e] [-m message]`
- `edit <page> [...]` (rename with `--title` alone), `view <page> [-w]`,
  `delete <page>`, `list [-L n] [--page n]` (alias `ls`),
  `revisions <page> [--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`; `delete` aliases `rm`.

**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> [-y]`

```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]`.
- Preference keys: `default_host`, `git_protocol`, `editor`, `prompt`, `pager`,
  `browser`, `color`, `hyperlinks`, `markdown`, `remote`, `http_timeout`,
  `extensions`, `extension_hosts`, `extension_owners`; instance (`--host`):
  `user`, `ssh_host`, `insecure`, `git_protocol`, `oauth_client_id`, `headers`,
  `client_cert`, `client_key`; account (`--host` + `--user`): `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 set extension_hosts https://gitea.com/gitea
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} [-y]` (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`/`--csv` 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`.

- `user list [--query text] [-L n] [--page n]`, `user view <username>`
- `user create [<username>] [--email addr] [--password-file file]
  [--full-name NAME] [--admin] [--must-change-password[=false]]
  [--prohibit-login] [--restricted] [--visibility ...]`
- `user edit <username> [...]` — as above plus `--active[=false]`,
  `--allow-*-`/`--max-repo-creation`, `--location`, `--website`.
- `user delete <username> [--purge] [-y]`

```bash
gt admin user list --query bob
gt admin user create alice --email alice@example.com
gt admin user delete spammer --purge
```