.nh
.TH "GT-EXTENSIONS" "1" "Nov 2026" "gitea-cli" "gitea-cli Manual"

.SH NAME
gt-extensions - How gt runs extensions, and what they may do


.SH SYNOPSIS
\fBgt extensions\fP


.SH DESCRIPTION
An extension is an executable named gt-NAME, or gh-NAME for a GitHub CLI extension, that
gt extension install puts in the extensions directory of $GITEA_CLI_DATA_DIR, or of gitea-cli
under the XDG data directory, and gt NAME runs. Built-in commands always win over an extension.

.PP
Installing: gt installs the release asset NAME-OS-ARCH or REPO-OS-ARCH (.exe on Windows) of the
latest release, else one whose name ends in OS-ARCH, or else clones the repository, which must
hold an executable gt-NAME at its root. It checks an asset against the SHA-256 GitHub recorded
at upload, else against the release's checksums.txt, in sha256sum format; without
either it asks with a default of no, or installs with --yes. An optional gt-extension.yml in
the repository declares:

.EX
  description      what the extension does, shown in gt help
  min_gt_version   the oldest gt that runs it
  platforms        such as linux/amd64 or darwin; none means every platform
  credentials      true when it needs your Gitea token
  completion       cobra, when it answers Cobra's __complete protocol for shell completion
  aliases          top-level commands that run the extension with fixed arguments: with
                   "user-group: user-group", gt user-group runs gt NAME user-group. Built-in
                   commands, extension names and your own aliases win over them, and of two
                   extensions the first by name does; gt warns about an alias it ignores and
                   installs the extension anyway.
.EE

.PP
Running: gt checks the executable against the SHA-256 recorded at install and refuses one that
changed. The extension inherits gt's terminal and environment, except for GITEA_TOKEN,
GITEA_INSTANCE_*, GH_TOKEN, GITHUB_TOKEN, GH_ENTERPRISE_TOKEN, GITHUB_ENTERPRISE_TOKEN and
GH_HOST. It gets:

.EX
  GITEA_CLI_EXTENSION          its name
  GITEA_CLI_EXECUTABLE         the path of gt, to call gt commands such as gt api
  GITEA_CLI_HOST, _REPO, _USER  from --host, --repo and --user before its name
  GITEA_TOKEN, GITEA_INSTANCE_URL  your token and its instance, only when you allowed it at
                                   install; gh extensions also get GH_HOST, GH_TOKEN and
                                   GH_ENTERPRISE_TOKEN
.EE

.PP
Global flags go before the extension's name; everything after it is the extension's own.
--cwd sets its working directory, and --no-input and --yes are accepted but not passed on;
other global flags, such as --json, are refused.

.PP
gt itself refuses your stored credentials to an extension that was not given them. This is
hygiene, not a sandbox: an extension runs with your privileges, can read gt's configuration
directory, and can change its own files and manifest. The digest check notices a corrupted or
replaced executable, not a deliberate change: for a script extension it covers the gt-NAME
script, not other files of its clone. Install extensions only from sources you trust.

.PP
Upgrading: gt extension upgrade shows the old and new version and digest first, refuses a
repository that was transferred or recreated and a release tag whose asset changed, and never
upgrades in the background.

.PP
Compatibility: GitHub CLI extensions that only use gh api and the REST endpoints Gitea shares
with GitHub can work; those that use GraphQL or other GitHub-only features do not. With
--compat-gh, an extension's gh calls reach gt, which answers gh api, gh auth token and
gh repo view, whose --json takes gt's fields, such as full_name, not gh's.

.PP
Policy: extensions (enabled or disabled), extension_hosts and extension_owners in config.yml
restrict extensions for you. An administrator sets the same, and extension_credentials: denied,
in /etc/gitea-cli/policy.yml (%ProgramData%\\gitea-cli\\policy.yml on Windows), which you
cannot loosen.


.SH SEE ALSO
\fBgt(1)\fP