---
sidebar_position: 2
---

# Installation

gt is a single binary, built for Linux, macOS, Windows, and FreeBSD.

## Install script

The install script downloads the binary for your system from
[dl.gitea.com](https://dl.gitea.com/gitea-cli/), verifies its SHA-256 checksum and installs
it as `gt`.

On Linux, macOS or FreeBSD:

```bash
curl -fsSL https://gitea.com/gitea/cli/raw/branch/main/scripts/install.sh | sh
```

It installs into `/usr/local/bin` when that directory is writable, else into `~/.local/bin`.

On Windows, in PowerShell:

```powershell
irm https://gitea.com/gitea/cli/raw/branch/main/scripts/install.ps1 | iex
```

It installs `gt.exe` into `%LOCALAPPDATA%\Programs\gitea-cli` and adds that directory to
your `PATH`.

Both scripts read these environment variables:

| Variable | Description |
| --- | --- |
| `GITEA_CLI_VERSION` | Version to install, such as `1.0.0`, or `nightly` for the latest build of the `main` branch. Default: the latest release. |
| `GITEA_CLI_INSTALL_DIR` | Directory to install gt into. |

`install.sh` also accepts `--nightly` and `--version VERSION`:

```bash
curl -fsSL https://gitea.com/gitea/cli/raw/branch/main/scripts/install.sh | sh -s -- --nightly
```

## Binaries

Download releases from [dl.gitea.com/gitea-cli](https://dl.gitea.com/gitea-cli/). Builds of
the `main` branch are in its [`main`](https://dl.gitea.com/gitea-cli/main/) directory. Each
binary is available as is and compressed with xz, and has a matching `.sha256` checksum
file:

```bash
VERSION=main
curl -sSLO "https://dl.gitea.com/gitea-cli/$VERSION/gitea-cli-$VERSION-linux-amd64"
curl -sSLO "https://dl.gitea.com/gitea-cli/$VERSION/gitea-cli-$VERSION-linux-amd64.sha256"
sha256sum -c "gitea-cli-$VERSION-linux-amd64.sha256"
sudo install -m 0755 "gitea-cli-$VERSION-linux-amd64" /usr/local/bin/gt
```

Each version also has a `gitea-cli-<version>-docs.tar.xz` archive with the command
reference, the man pages and the shell completion scripts.

## Docker

The [`gitea/gitea-cli`](https://hub.docker.com/r/gitea/gitea-cli) image runs `gt` as its
entry point. Releases are tagged with their version and `latest`, builds of the `main`
branch with `nightly`.

```bash
docker run --rm -e GITEA_TOKEN -e GITEA_CLI_HOST=https://gitea.example.com \
  gitea/gitea-cli issue list --repo owner/repo
```

A container has no system keyring, so pass a token in the environment as above (see
[Using gt in CI](ci.md)). To keep the settings and a login between runs, mount a volume at
`/app`, the home directory of the image, and log in with `--credential-store file`.

## Go

With Go 1.27 or later:

```bash
go install gitea.dev/cli/cmd/gt@latest
```

To build gt from a clone of [gitea/cli](https://gitea.com/gitea/cli), run `make`; it needs
GNU Make.

## Shell completion

`gt completion <shell>` prints the completion script for bash, zsh, fish or PowerShell.
Completion includes your aliases and, after `--json`, the JSON fields of a command. Add
the line for your shell to its startup file:

```bash
# ~/.bashrc (on macOS, ~/.bash_profile); needs the bash-completion package
eval "$(gt completion bash)"

# ~/.zshrc, after compinit
source <(gt completion zsh)

# fish, once
gt completion fish > ~/.config/fish/completions/gt.fish
```

In PowerShell, add this line to your profile:

```powershell
gt completion powershell | Out-String | Invoke-Expression
```

`gt completion <shell> --help` shows the details for each shell.

## Man pages

`gt man` prints gt's full manual, and `gt man <command>` the man page of one command, such
as `gt man pr create`; `gt man` is not listed in `gt --help`. The man pages are also in the
docs archive of each version.

```bash
# bash or zsh
man <(gt man)

# write it to a file
gt man --output-file gt.1
```

## Upgrading

Run the install script again, download the new binary, or pull the new image.
`gt version` prints the version you run.