gitea-cli

The official CLI for Gitea

gitea-cli manages repositories, issues, pull requests, releases, and other Gitea resources with explicit commands suitable for local development and CI. The binary is called gt.

gt auth login --host https://gitea.example.org --with-token < token-file
gt issue list --repo owner/repository
gt pr view 123 --repo owner/repository --json
gt alias set bugs 'issue list --label bug'
gt help

gt requires Gitea 28 or newer. It keeps its preferences in config.yml and its instances and accounts in hosts.yml. Run gt --help or gt <command> --help for supported commands and flags; the full reference, man pages, and shell completions ship in each release's docs archive. Credentials use the operating-system keyring by default; explicitly select --credential-store file when private file storage is needed. For CI, supply GITEA_TOKEN and its instance through GITEA_CLI_HOST or GITEA_INSTANCE_URL; environment credentials are never persisted.

Installation

There are different ways to get gt:

1. Run the install script. It downloads the binary for your system from dl.gitea.com, verifies its checksum and installs gt; GITEA_CLI_VERSION and GITEA_CLI_INSTALL_DIR choose another version or directory, and the version nightly installs the latest build of the main branch. Later, gt upgrade upgrades it the same way.

   On Linux, macOS, FreeBSD or OpenBSD:

   curl -fsSL https://gitea.com/gitea/cli/raw/branch/main/scripts/install.sh | sh
   # the latest nightly build
   curl -fsSL https://gitea.com/gitea/cli/raw/branch/main/scripts/install.sh | sh -s -- --nightly
   

   On Windows, in PowerShell, which also adds gt to your PATH:

   irm https://gitea.com/gitea/cli/raw/branch/main/scripts/install.ps1 | iex
   # the latest nightly build
   $env:GITEA_CLI_VERSION = 'nightly'; irm https://gitea.com/gitea/cli/raw/branch/main/scripts/install.ps1 | iex
   

2. Use the prebuilt binaries from dl.gitea.com

3. Docker: gitea-cli at docker hub

4. Homebrew on macOS or Linux:

   brew install gitea-cli
   

5. Linux packages: download the .deb, .rpm, .apk or Arch .pkg.tar.zst for your system from the release and install it with your package manager, for example sudo apt install ./gitea-cli_<version>_amd64.deb. They include the man pages and shell completions.

6. Install from source: see Compilation

Log in to Gitea from gt

Gitea can use many different authentication schemes, and not every authentication method will work with every Gitea deployment. When you are a Gitea instance administrator you can tweak your settings to fit your use case. For the method that is most likely to work with any Gitea deployment use the following steps:

1. Open your Gitea instance in a web browser

2. Log in to Gitea in your web browser. Any MFA, IDP, or whatever else should be available this way.

3. In your "user settings", generate an application token with at least user read permissions. If you want to do anything useful with the token add additional permissions/scopes.

4. Save the token in a private file and run gt auth login --host https://your-instance --with-token < token-file. Credentials use the operating-system keyring by default.

You should now be logged in to your gitea instance from gt.

Alternatively, gt auth login --host https://your-instance --oauth authorizes gt in your browser. OAuth may not be available on all Gitea deployments, and needs a browser on the machine running gt.

MCP server for Forgejo

gt pop runs a deployable Streamable HTTP MCP server at /mcp. It uses OAuth authorization code with PKCE and redirects users to Forgejo to sign in. The Forgejo instance defaults to https://git.benjii.dev; override it with --host, --url, FORGEJO_URL, GITEA_CLI_HOST, GITEA_INSTANCE_URL, or GITEA_URL.

Register an OAuth application in Forgejo at /user/settings/applications and set its callback URL to https://<your-pop-host>/oauth/callback. Configure these deployment variables:

• POP_PUBLIC_URL: the public HTTPS origin where Pop is deployed.
• FORGEJO_OAUTH_CLIENT_ID and FORGEJO_OAUTH_CLIENT_SECRET: the registered Forgejo OAuth app.
• POP_OAUTH_SECRET: a stable random secret of at least 32 bytes.
• PORT or POP_ADDR: the HTTP listen port/address (defaults to 8080 / :8080).

Run one Pop instance: the short-lived authorization-code and refresh-token replay cache is process-local.

Start it with:

gt pop

Connect an MCP client to https://<your-pop-host>/mcp. Pop provides tools to read repositories, list and read issues or pull requests, create issues, and read or create comments. Forgejo OAuth does not limit token scopes, so approving Pop grants it every API permission available to that Forgejo account. Keep that account's permissions in mind. For local stdio use, run GITEA_TOKEN=... gt pop --stdio; gt mcp remains an alias.

Coming from tea

gt replaces tea. Migrating from tea maps tea's commands and flags to gt's.

Shell completion

If you installed from source or the package does not provide the completions with it you can add them yourself with gt completion <shell> command. Add the line for your shell to its startup file:

# ~/.bashrc (on macOS, ~/.bash_profile)
eval "$(gt completion bash)"

# ~/.zshrc, after compinit
autoload -U compinit && compinit
source <(gt completion zsh)

# fish
gt completion fish > ~/.config/fish/completions/gt.fish

# PowerShell profile
gt completion powershell | Out-String | Invoke-Expression

The bash script needs the bash-completion package. gt completion <shell> --help shows the details for each shell.

Man Page

The hidden command gt man can be used to generate the gt man page.

# for bash or zsh
man <(gt man)

# for fish
man (gt man | psub)

# write man page to a file
gt man --output-file ./gt.man

Agent skill

An agent skill teaches coding agents to drive gt: checking CI and reading the logs of failed jobs, turning an issue into a pull request, commenting and reviewing. It replaces gitea-tea-skill. Install it with skills:

# for the current project
npx skills add https://gitea.com/gitea/cli.git --skill gt

# for all your projects
npx skills add https://gitea.com/gitea/cli.git --skill gt -g

# after upgrading gt
npx skills update gt

Compilation

Make sure you have a current Go version installed (1.27 or newer).

• To compile the source yourself with the recommended flags & tags:

  git clone https://gitea.com/gitea/cli.git # or: gt repo clone https://gitea.com/gitea/cli ;)
  cd cli
  make
  

  Note that GNU Make (gmake on OpenBSD) is required. If you want to install the compiled program you have to execute the following command:

  make install
  

  This installs the binary into the "bin" folder inside of your GOPATH folder (go env GOPATH). It is possible that this folder isn't in your PATH Environment Variable.

• For a quick installation without git & make, set $version and exec:

  go install gitea.dev/cli/cmd/gt@${version}
  

Contributing

Fork -> Patch -> Push -> Pull Request

• make test run unit tests
• make vet run checks (check the order of imports; preventing failure on CI pipeline beforehand)
• make build builds the production CLI
• make docs regenerates references, man pages, and shell completions in docs/generated (not committed; built on release)
• ... (for other development tasks, check the Makefile)

Please read the CONTRIBUTING documentation, it will tell you about internal structures and concepts.

License

This project is under the MIT License. See the LICENSE file for the full license text.