---
name: "gt-extensions"
section: "1"
platform: "linux"
package: "gitea-cli"
version: "1.0.0-1"
release: "Arch Linux 2026-11-07"
platforms: ["linux"]
url: "https://carta.tech/man/gt-extensions"
---

# gt-extensions(1)

How gt runs extensions, and what they may do

## NAME

gt-extensions - How gt runs extensions, and what they may do

## SYNOPSIS

**gt extensions**

## 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.

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:

```
  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.
```

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:

```
  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
```

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.

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.

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.

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.

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.

## SEE ALSO

**[gt(1)](/man/gt/1.md)**