GT-EXTENSIONS(1) gitea-cli Manual GT-EXTENSIONS(1)

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

gt extensions

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.

gt(1)

Nov 2026 gitea-cli