STACKITGit/cli
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request #11473 from cli/andyfeller/github-cli-934-reorganize-install-docs

Browse source 
Reorganize installation docs
This commit is contained in:
Andy Feller 2025-08-11 17:00:57 -04:00 • committed by GitHub
commit a247a045a3
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 585 additions and 261 deletions
Download patch file Download diff file Expand all files Collapse all files

2
.github/CONTRIBUTING.md vendored
View file

@ -10,6 +10,7 @@ We accept pull requests for bug fixes and features where we've discussed the app
* Open an issue if things aren't working as expected
* Open an issue to propose a significant change
* Open an issue to propose a design for an issue labelled [`needs-design` and `help wanted`][needs design and help wanted], following the [proposing a design guidelines](#proposing-a-design) instructions below
* Open an issue to propose a new community supported `gh` package with details about support and redistribution
* Mention `@cli/code-reviewers` when an issue you want to work on does not have clear Acceptance Criteria
* Open a pull request for any issue labelled [`help wanted`][hw] and [`good first issue`][gfi]
@ -17,7 +18,6 @@ We accept pull requests for bug fixes and features where we've discussed the app
* Open a pull request for issues without the `help wanted` label or explicit Acceptance Criteria
* Expand pull request scope to include changes that are not described in the issue's Acceptance Criteria
* Add installation instructions specifically for your OS/package manager
* Open pull requests for any issue marked `core`. These issues require additional context from
the core CLI team at GitHub and any external pull requests will not be accepted

130
README.md
View file

@ -8,106 +8,44 @@ GitHub CLI is supported for users on GitHub.com, GitHub Enterprise Cloud, and Gi
## Documentation
For [installation options see below](#installation), for usage instructions [see the manual][manual].
For [installation options see below](#installation), for usage instructions [see the manual]( https://cli.github.com/manual/).
## Contributing
If anything feels off or if you feel that some functionality is missing, please check out the [contributing page][contributing]. There you will find instructions for sharing your feedback, building the tool locally, and submitting pull requests to the project.
If anything feels off or if you feel that some functionality is missing, please check out the [contributing page](.github/CONTRIBUTING.md). There you will find instructions for sharing your feedback, building the tool locally, and submitting pull requests to the project.
If you are a hubber and are interested in shipping new commands for the CLI, check out our [doc on internal contributions][intake-doc].
If you are a hubber and are interested in shipping new commands for the CLI, check out our [doc on internal contributions](docs/working-with-us.md)
<!-- this anchor is linked to from elsewhere, so avoid renaming it -->
## Installation
### macOS
### [macOS](docs/install_macos.md)
`gh` is available via [Homebrew][], [MacPorts][], [Conda][], [Spack][], [Webi][], and as a downloadable binary including Mac OS installer `.pkg` from the [releases page][].
- [Homebrew](docs/install_macos.md#homebrew)
- [Precompiled binaries](docs/install_macos.md#precompiled-binaries) on [releases page][]
> [!NOTE]
> As of May 29th, Mac OS installer `.pkg` are unsigned with efforts prioritized in [`cli/cli#9139`](https://github.com/cli/cli/issues/9139) to support signing them.
For additional macOS packages and installers, see [community-supported docs](docs/install_macos.md#community-unofficial)
#### Homebrew
### [Linux & Unix](docs/install_linux.md)
| Install: | Upgrade: |
| ----------------- | ----------------- |
| `brew install gh` | `brew upgrade gh` |
- [Debian, Raspberry Pi, Ubuntu](docs/install_linux.md#debian)
- [Amazon Linux, CentOS, Fedora, openSUSE, RHEL, SUSE](docs/install_linux.md#rpm)
- [Precompiled binaries](docs/install_linux.md#precompiled-binaries) on [releases page][]
#### MacPorts
For additional Linux & Unix packages and installers, see [community-supported docs](docs/install_linux.md#community-unofficial)
| Install: | Upgrade: |
| ---------------------- | ---------------------------------------------- |
| `sudo port install gh` | `sudo port selfupdate && sudo port upgrade gh` |
### [Windows](docs/install_windows.md)
#### Conda
- [WinGet](docs/install_windows.md#winget)
- [Precompiled binaries](docs/install_windows.md#precompiled-binaries) on [releases page][]
| Install: | Upgrade: |
|------------------------------------------|-----------------------------------------|
| `conda install gh --channel conda-forge` | `conda update gh --channel conda-forge` |
For additional Windows packages and installers, see [community-supported docs](docs/install_windows.md#community-unofficial)
Additional Conda installation options available on the [gh-feedstock page](https://github.com/conda-forge/gh-feedstock#installing-gh).
### Build from source
#### Spack
See here on how to [build GitHub CLI from source](docs/install_source.md).
| Install: | Upgrade: |
| ------------------ | ---------------------------------------- |
| `spack install gh` | `spack uninstall gh && spack install gh` |
#### Webi
| Install: | Upgrade: |
| ----------------------------------- | ---------------- |
| `curl -sS https://webi.sh/gh \| sh` | `webi gh@stable` |
For more information about the Webi installer, see [its homepage](https://webinstall.dev/).
#### Flox
| Install: | Upgrade: |
| ----------------- | ----------------------- |
| `flox install gh` | `flox upgrade toplevel` |
For more information about Flox, see [its homepage](https://flox.dev)
### Linux & BSD
`gh` is available via:
- [our Debian and RPM repositories](./docs/install_linux.md);
- community-maintained repositories in various Linux distros;
- OS-agnostic package managers such as [Homebrew](#homebrew), [Conda](#conda), [Spack](#spack), [Webi](#webi); and
- our [releases page][] as precompiled binaries.
For more information, see [Linux & BSD installation](./docs/install_linux.md).
### Windows
`gh` is available via [WinGet][], [scoop][], [Chocolatey][], [Conda](#conda), [Webi](#webi), and as downloadable MSI.
#### WinGet
| Install: | Upgrade: |
| ------------------- | --------------------|
| `winget install --id GitHub.cli` | `winget upgrade --id GitHub.cli` |
> [!NOTE]
> The Windows installer modifies your PATH. When using Windows Terminal, you will need to **open a new window** for the changes to take effect. (Simply opening a new tab will _not_ be sufficient.)
#### scoop
| Install: | Upgrade: |
| ------------------ | ------------------ |
| `scoop install gh` | `scoop update gh` |
#### Chocolatey
| Install: | Upgrade: |
| ------------------ | ------------------ |
| `choco install gh` | `choco upgrade gh` |
#### Signed MSI
MSI installers are available for download on the [releases page][].
### Codespaces
### GitHub Codespaces
To add GitHub CLI to your codespace, add the following to your [devcontainer file](https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/adding-features-to-a-devcontainer-file):
@ -119,13 +57,13 @@ To add GitHub CLI to your codespace, add the following to your [devcontainer fil
### GitHub Actions
GitHub CLI comes pre-installed in all [GitHub-Hosted Runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners).
[GitHub-hosted runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners) have the GitHub CLI pre-installed, which is updated weekly.
### Other platforms
If a specific version is needed, your GitHub Actions workflow will need to install it based on the [macOS](#macos), [Linux & Unix](#linux--unix), or [Windows](#windows) instructions above.
Download packaged binaries from the [releases page][].
For information on all pre-installed tools, see [`actions/runner-images`](https://github.com/actions/runner-images)
#### Verification of binaries
### Verification of binaries
Since version 2.50.0, `gh` has been producing [Build Provenance Attestation](https://github.blog/changelog/2024-06-25-artifact-attestations-is-generally-available/), enabling a cryptographically verifiable paper-trail back to the origin GitHub repository, git revision, and build instructions used. The build provenance attestations are signed and rely on Public Good [Sigstore](https://www.sigstore.dev/) for PKI.
@ -157,29 +95,11 @@ There are two common ways to verify a downloaded release, depending on whether `
Verified OK
```
### Build from source
See here on how to [build GitHub CLI from source][build from source].
## Comparison with hub
For many years, [hub][] was the unofficial GitHub CLI tool. `gh` is a new project that helps us explore
For many years, [hub](https://github.com/github/hub) was the unofficial GitHub CLI tool. `gh` is a new project that helps us explore
what an official GitHub CLI tool can look like with a fundamentally different design. While both
tools bring GitHub to the terminal, `hub` behaves as a proxy to `git`, and `gh` is a standalone
tool. Check out our [more detailed explanation][gh-vs-hub] to learn more.
tool. Check out our [more detailed explanation](docs/gh-vs-hub.md) to learn more.
[manual]: https://cli.github.com/manual/
[Homebrew]: https://brew.sh
[MacPorts]: https://www.macports.org
[winget]: https://github.com/microsoft/winget-cli
[scoop]: https://scoop.sh
[Chocolatey]: https://chocolatey.org
[Conda]: https://docs.conda.io/en/latest/
[Spack]: https://spack.io
[Webi]: https://webinstall.dev
[releases page]: https://github.com/cli/cli/releases/latest
[hub]: https://github.com/github/hub
[contributing]: ./.github/CONTRIBUTING.md
[gh-vs-hub]: ./docs/gh-vs-hub.md
[build from source]: ./docs/source.md
[intake-doc]: ./docs/working-with-us.md

425
docs/install_linux.md
View file

@ -1,17 +1,18 @@
# Installing gh on Linux and BSD
Packages downloaded from https://cli.github.com or from https://github.com/cli/cli/releases
are considered official binaries. We focus on popular Linux distros and
the following CPU architectures: `i386`, `amd64`, `arm64`, `armhf`.
## Recommended _(Official)_
Other sources for installation are community-maintained and thus might lag behind
our release schedule.
### Debian
## Official sources
Debian packages are hosted on the [GitHub CLI marketing site](https://cli.github.com/) for various operating systems including:
### Debian, Ubuntu Linux, Raspberry Pi OS (apt)
- [Debian](https://www.debian.org/)
- [Raspberry Pi](https://www.raspberrypi.com/)
- [Ubuntu Linux](https://ubuntu.com/)
Install:
These packages are supported by the GitHub CLI maintainers with updates powered by [GitHub CLI deployment workflow](https://github.com/cli/cli/actions/workflows/deployment.yml).
To install:
```bash
(type -p wget >/dev/null || (sudo apt update && sudo apt install wget -y)) \
@ -25,64 +26,67 @@ Install:
&& sudo apt install gh -y
```
Upgrade:
To upgrade:
```bash
sudo apt update
sudo apt install gh
```
> [!NOTE]
> If errors regarding GPG signatures occur, see [cli/cli#9569](https://github.com/cli/cli/issues/9569) for steps to fix this.
### RPM
### Fedora, CentOS, Red Hat Enterprise Linux (DNF4 & DNF5)
RPM packages are hosted on the [GitHub CLI marketing site](https://cli.github.com) for various operating systems including:
Install from our package repository for immediate access to latest releases.
- [Amazon Linux 2](https://aws.amazon.com/amazon-linux-2/)
- [CentOS](https://www.centos.org/)
- [Fedora](https://fedoraproject.org/)
- [Red Hat Enterprise Linux](https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux)
- [openSUSE](https://www.opensuse.org/)
- [SUSE](https://www.suse.com/)
These packages are supported by the GitHub CLI maintainers with updates powered by [GitHub CLI deployment workflow](https://github.com/cli/cli/actions/workflows/deployment.yml).
#### DNF5
> [!IMPORTANT]
> **These commands apply to DNF5 only**. If you're using DNF4, please use [the DNF4 instructions](#dnf4).
To install:
```bash
# DNF5 installation commands
sudo dnf install dnf5-plugins
sudo dnf config-manager addrepo --from-repofile=https://cli.github.com/packages/rpm/gh-cli.repo
sudo dnf install gh --repo gh-cli
```
To upgrade:
```bash
sudo dnf update gh
```
#### DNF4
> [!IMPORTANT]
> **These commands apply to DNF4 only**. If you're using DNF5, please use [the DNF5 instructions](#dnf5).
To install:
```bash
# DNF4 installation commands
sudo dnf install 'dnf-command(config-manager)'
sudo dnf config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo
sudo dnf install gh --repo gh-cli
```
> [!NOTE]
> If errors regarding GPG signatures occur, see [cli/cli#9569](https://github.com/cli/cli/issues/9569) for steps to fix this.
### Fedora, CentOS, Red Hat Enterprise Linux - Community repository
Alternatively, install from the [community repository](https://packages.fedoraproject.org/pkgs/gh/gh/):
```bash
sudo dnf install gh
```
Upgrade:
To upgrade:
```bash
sudo dnf update gh
```
### Amazon Linux 2 (yum)
#### Amazon Linux 2 (yum)
Install using our package repository for immediate access to latest releases:
To install:
```bash
type -p yum-config-manager >/dev/null || sudo yum install yum-utils
@ -90,18 +94,15 @@ sudo yum-config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.re
sudo yum install gh
```
Upgrade:
To upgrade:
```bash
sudo yum update gh
```
> [!NOTE]
> If errors regarding GPG signatures occur, see [cli/cli#9569](https://github.com/cli/cli/issues/9569) for steps to fix this.
#### openSUSE/SUSE Linux (zypper)
### openSUSE/SUSE Linux (zypper)
Install:
To install:
```bash
sudo zypper addrepo https://cli.github.com/packages/rpm/gh-cli.repo
@ -109,50 +110,140 @@ sudo zypper ref
sudo zypper install gh
```
Upgrade:
To upgrade:
```bash
sudo zypper ref
sudo zypper update gh
```
> [!NOTE]
> If errors regarding GPG signatures occur, see [cli/cli#9569](https://github.com/cli/cli/issues/9569) for steps to fix this.
### Homebrew
## Manual installation
[Homebrew](https://brew.sh/) is a free and open-source software package management system that simplifies the installation of software on Apple's operating system, macOS, as well as Linux.
* [Download release binaries][releases page] that match your platform; or
* [Build from source](./source.md).
The [GitHub CLI formulae](https://formulae.brew.sh/formula/gh) is supported by the GitHub CLI maintainers with help from our friends at Homebrew with updated powered by [homebrew/hoomebrew-core](https://github.com/Homebrew/homebrew-core/blob/main/Formula/g/gh.rb).
## Unofficial, community-supported methods
To install:
The GitHub CLI team does not maintain the following packages or repositories and thus we are unable to provide support for those installation methods.
### Snap (do not use)
There are [so many issues with Snap](https://github.com/casperdcl/cli/issues/7) as a runtime mechanism for apps like GitHub CLI that our team suggests _never installing gh as a snap_.
### Arch Linux
Arch Linux users can install from the [extra repo][arch linux repo]:
```bash
sudo pacman -S github-cli
```shell
brew install gh
```
Alternatively, use the [unofficial AUR package][arch linux aur] to build GitHub CLI from source.
To upgrade:
```shell
brew upgrade gh
```
### Precompiled binaries
[GitHub CLI releases](https://github.com/cli/cli/releases/latest) contain precompiled binaries for `386`, `amd64`, `arm64`, and `armv6` architectures.
## Community _(Unofficial)_
> [!IMPORTANT]
> The GitHub CLI team does not maintain the following packages or repositories. We are unable to provide support for these installation methods or any guarantees of stability, security, or availability for these installation methods.
### Alpine Linux
The [GitHub CLI package](https://pkgs.alpinelinux.org/package/edge/community/x86_64/github-cli) is supported by the Alpine Linux community with updates powered by [alpine/aports](https://gitlab.alpinelinux.org/alpine/aports/-/tree/master/community/github-cli).
To install stable release:
```bash
apk add github-cli
```
To install edge release:
```bash
echo "@community http://dl-cdn.alpinelinux.org/alpine/edge/community" >> /etc/apk/repositories
apk add github-cli@community
```
### Android
Android 7+ users can install via [Termux](https://wiki.termux.com/wiki/Main_Page):
The [GitHub CLI package](https://packages.termux.dev/apt/termux-main/pool/main/g/gh/) is supported by the Termux community with updates powered by [termux/termux-packages](https://github.com/termux/termux-packages/tree/master/packages/gh).
To install and upgrade:
```bash
pkg install gh
```
### Arch Linux
The [GitHub CLI package](https://www.archlinux.org/packages/extra/x86_64/github-cli) is supported by the Arch Linux community with updates powered by [Arch Linux packaging](https://gitlab.archlinux.org/archlinux/packaging/packages/github-cli).
To install:
```bash
sudo pacman -S github-cli
```
To upgrade all packages:
```bash
sudo pacman -Syu
```
Alternatively, use the [unofficial AUR package](https://aur.archlinux.org/packages/github-cli-git) to build GitHub CLI from source.
### Conda
[Conda](https://docs.conda.io/en/latest/) is an open source package management system and environment management system for installing multiple versions of software packages and their dependencies and switching easily between them. It works on Linux, OS X and Windows, and was created for Python programs but can package and distribute any software.
The [GitHub CLI package](https://anaconda.org/conda-forge/gh) is supported by the Conda community with updates powered by [conda-forge/gh-feedstock](https://github.com/conda-forge/gh-feedstock#installing-gh).
To install:
```shell
conda install gh --channel conda-forge
```
To upgrade:
```shell
conda update gh --channel conda-forge
```
### Fedora Community
The [GitHub CLI package](https://packages.fedoraproject.org/pkgs/gh/gh/) is supported by the Fedora community with updates powered by [Fedora Project](https://src.fedoraproject.org/rpms/gh).
To install:
```bash
sudo dnf install gh
```
To upgrade:
```bash
sudo dnf update gh
```
### Flox
[Flox](https://flox.dev/) is a virtual environment and package manager all in one. With Flox you create environments that layer and replace dependencies just where it matters, making them portable across the full software lifecycle.
Flox relies upon the [GitHub CLI package](https://github.com/NixOS/nixpkgs/blob/master/pkgs/by-name/gh/gh/package.nix) supported by the [NixOS community](https://nixos.org/)
To install:
```shell
flox install gh
```
To upgrade:
```shell
flox upgrade toplevel
```
### FreeBSD
FreeBSD users can install from the [ports collection](https://www.freshports.org/devel/gh/):
The [GitHub CLI port](https://www.freshports.org/devel/gh/) is supported by the FreeBSD community with updates powered by [FreeBSD ports](https://cgit.freebsd.org/ports/tree/devel/gh).
```bash
cd /usr/ports/devel/gh/ && make install clean
@ -164,9 +255,55 @@ Or via [pkg(8)](https://www.freebsd.org/cgi/man.cgi?pkg(8)):
pkg install gh
```
### Funtoo
The GitHub CLI portage is supported by the Funtoo community with updates powered by [funtoo/dev-kit](https://github.com/funtoo/dev-kit/tree/1.4-release/dev-util/github-cli).
To install:
```bash
emerge -av github-cli
```
To upgrade:
```bash
ego sync
emerge -u github-cli
```
### Gentoo
The [GitHub CLI portage](https://packages.gentoo.org/packages/dev-util/github-cli) is supported by the Gentoo community with updates powered by [Gentoo portage](https://gitweb.gentoo.org/repo/gentoo.git/tree/dev-util/github-cli).
To install:
``` bash
emerge -av github-cli
```
To upgrade:
``` bash
emerge --sync
emerge -u github-cli
```
### Manjaro Linux
The [GitHub CLI package](https://manjaristas.org/branch_compare?q=github-cli) is the same package produced by the [Arch Linux community](#arch-linux)
To install and upgrade:
```bash
pamac install github-cli
```
### MidnightBSD
MidnightBSD users can install from [mports](https://www.midnightbsd.org/documentation/mports/index.html)
The [GitHub CLI port](https://www.midnightbsd.org/mports/devel/gh/README.html) is supported by the MidnightBSD community with updates powered by [MidnightBSD/mports](https://github.com/MidnightBSD/mports/tree/master/devel/gh).
To install:
```bash
cd /usr/mports/devel/gh/ && make install clean
@ -180,133 +317,111 @@ mport install gh
### NetBSD/pkgsrc
NetBSD users and those on [platforms supported by pkgsrc](https://pkgsrc.org/#index4h1) can install the [gh package](https://pkgsrc.se/net/gh):
The [GitHub CLI package](https://pkgsrc.se/net/gh) is supported by the NetBSD community with updates powered by [NetBSD/pkgsrc](https://github.com/NetBSD/pkgsrc/tree/trunk/net/gh).
To install:
```bash
pkgin install gh
```
To install from source:
```bash
cd /usr/pkgsrc/net/gh && make package-install
```
### OpenBSD
In -current, or in releases starting from 7.0, OpenBSD users can install from packages:
```
pkg_add github-cli
```
### Funtoo
Funtoo Linux has an autogenerated github-cli package, located in [dev-kit](https://github.com/funtoo/dev-kit/tree/1.4-release/dev-util/github-cli), which can be installed in the following way:
``` bash
emerge -av github-cli
```
Upgrading can be done by syncing the repos and then requesting an upgrade:
``` bash
ego sync
emerge -u github-cli
```
### Gentoo
Gentoo Linux users can install from the [main portage tree](https://packages.gentoo.org/packages/dev-util/github-cli):
``` bash
emerge -av github-cli
```
Upgrading can be done by updating the portage tree and then requesting an upgrade:
``` bash
emerge --sync
emerge -u github-cli
```
### Kiss Linux
Kiss Linux users can install from the [community repos](https://github.com/kisslinux/community):
```bash
kiss b github-cli && kiss i github-cli
```
### Nix/NixOS
Nix/NixOS users can install from [nixpkgs](https://search.nixos.org/packages?query=gh&sort=relevance&show=gh):
The [GitHub CLI package](https://search.nixos.org/packages?query=gh&sort=relevance&show=gh) is supported by the NixOS community with updates powered by [NixOS/nixpkgs](https://github.com/NixOS/nixpkgs/tree/master/pkgs/by-name/gh/gh).
To install:
```bash
nix-env -iA nixos.gh
```
### Flox
### OpenBSD
Flox users can install from the [official community nixpkgs](https://github.com/flox/nixpkgs).
The [GitHub CLI port](https://openports.pl/path/devel/github-cli) is supported by the OpenBSD community with updates powered by [OpenBSD ports](https://cvsweb.openbsd.org/ports/devel/github-cli/).
```bash
# To install
flox install gh
To install:
# To upgrade
flox upgrade toplevel
```shell
pkg_add github-cli
```
For more information about Flox, see [its homepage](https://flox.dev).
### openSUSE Tumbleweed
openSUSE Tumbleweed users can install from the [official distribution repo](https://software.opensuse.org/package/gh):
The [GitHub CLI package](https://software.opensuse.org/package/gh) is supported by the openSUSE community.
To install:
```bash
sudo zypper in gh
sudo zypper install gh
```
### Alpine Linux
Alpine Linux users can install from the [stable releases' community package repository](https://pkgs.alpinelinux.org/packages?name=github-cli&branch=v3.15).
To upgrade:
```bash
apk add github-cli
```
Users wanting the latest version of the CLI without waiting to be backported into the stable release they're using should use the edge release's
community repo through this method below, without mixing packages from stable and unstable repos.[^1]
```bash
echo "@community http://dl-cdn.alpinelinux.org/alpine/edge/community" >> /etc/apk/repositories
apk add github-cli@community
```
### Void Linux
Void Linux users can install from the [official distribution repo](https://voidlinux.org/packages/?arch=x86_64&q=github-cli):
```bash
sudo xbps-install github-cli
```
### Manjaro Linux
Manjaro Linux users can install from the [official extra repository](https://manjaristas.org/branch_compare?q=github-cli):
```bash
pamac install github-cli
sudo zypper update gh
```
### Solus Linux
Solus Linux users can install using [eopkg package manager](https://help.getsol.us/docs/user/package-management/basics/):
The GitHub CLI package is supported by the Solus Linux community with updates powered by [getsolus/packages](https://github.com/getsolus/packages/blob/main/packages/g/github-cli/).
To install:
```bash
sudo eopkg install github-cli
```
For more information about the `github-cli` package, see [the package definition](https://github.com/getsolus/packages/blob/main/packages/g/github-cli/package.yml) in the `getsolus/packages` repository.
### Spack
[releases page]: https://github.com/cli/cli/releases/latest
[arch linux repo]: https://www.archlinux.org/packages/extra/x86_64/github-cli
[arch linux aur]: https://aur.archlinux.org/packages/github-cli-git
[^1]: https://wiki.alpinelinux.org/wiki/Package_management#Repository_pinning
[Spack](https://spack.io/) is a flexible package manager supporting multiple versions, configurations, platforms, and compilers for supercomputers, Linux, and macOS.
The [GitHub CLI package](https://packages.spack.io/package.html?name=gh) is supported by the Spack community with updates powered by [spack/spack-packages](https://github.com/spack/spack-packages/tree/develop/repos/spack_repo/builtin/packages/gh).
To install:
```shell
spack install gh
```
To upgrade:
```shell
spack uninstall gh && spack install gh
```
### Void Linux
The [GitHub CLI package](https://voidlinux.org/packages/?arch=x86_64&q=github-cli): is supported by the Void Linux community with updates powered by [void-linux/void-packages](https://github.com/void-linux/void-packages/tree/master/srcpkgs/github-cli).
To install:
```bash
sudo xbps-install github-cli
```
### Webi
[Webi](https://webinstall.dev/) is a tool that aims to effortlessly install developer tools with easy-to-remember URLs from official builds quickly, without sudo or Admin, without a package manager, and without changing system file permissions.
The [GitHub CLI package](https://webinstall.dev/gh/) is supported by the Webi community with updates powered by [webinstall/webi-installers](https://github.com/webinstall/webi-installers/tree/main/gh).
To install:
```shell
curl -sS https://webi.sh/gh \| sh
```
To upgrade:
```shell
webi gh@stable
```
## Discouraged
> [!WARNING]
> The GitHub CLI team actively discourages use of the following methods of installation.
### Snap
The [GitHub CLI package](https://snapcraft.io/gh) has [so many issues with Snap](https://github.com/casperdcl/cli/issues/7) as a runtime mechanism for apps like GitHub CLI that our team suggests _never installing gh as a snap_.

123
docs/install_macos.md Normal file
View file

@ -0,0 +1,123 @@
# Installing gh on macOS
## Recommended _(Official)_
### Homebrew
[Homebrew](https://brew.sh/) is a free and open-source software package management system that simplifies the installation of software on Apple's operating system, macOS, as well as Linux.
The [GitHub CLI formulae](https://formulae.brew.sh/formula/gh) is supported by the GitHub CLI maintainers with help from our friends at Homebrew with updated powered by [homebrew/homebrew-core](https://github.com/Homebrew/homebrew-core/blob/main/Formula/g/gh.rb).
To install:
```shell
brew install gh
```
To upgrade:
```shell
brew upgrade gh
```
### Precompiled binaries
[GitHub CLI releases](https://github.com/cli/cli/releases/latest) contain precompiled binaries for `amd64` and `arm64` architectures along with a universal installer.
> [!NOTE]
> As of May 29th, Mac OS installer `.pkg` are unsigned with efforts prioritized in [`cli/cli#9139`](https://github.com/cli/cli/issues/9139) to support signing them.
## Community _(Unofficial)_
> [!IMPORTANT]
> The GitHub CLI team does not maintain the following packages or repositories. We are unable to provide support for these installation methods or any guarantees of stability, security, or availability for these installation methods.
### Conda
[Conda](https://docs.conda.io/en/latest/) is an open source package management system and environment management system for installing multiple versions of software packages and their dependencies and switching easily between them. It works on Linux, OS X and Windows, and was created for Python programs but can package and distribute any software.
The [GitHub CLI package](https://anaconda.org/conda-forge/gh) is supported by the Conda community with updates powered by [conda-forge/gh-feedstock](https://github.com/conda-forge/gh-feedstock#installing-gh).
To install:
```shell
conda install gh --channel conda-forge
```
To upgrade:
```shell
conda update gh --channel conda-forge
```
### Flox
[Flox](https://flox.dev/) is a virtual environment and package manager all in one. With Flox you create environments that layer and replace dependencies just where it matters, making them portable across the full software lifecycle.
Flox relies upon the [GitHub CLI package](https://github.com/NixOS/nixpkgs/blob/master/pkgs/by-name/gh/gh/) supported by the [NixOS community](https://nixos.org/)
To install:
```shell
flox install gh
```
To upgrade:
```shell
flox upgrade toplevel
```
### MacPorts
[MacPorts](https://www.macports.org/) is an open-source community initiative to design an easy-to-use system for compiling, installing, and upgrading either command-line, X11 or Aqua based open-source software on the Mac operating system.
The [GitHub CLI port](https://ports.macports.org/port/gh/) is supported by the MacPorts community with updates powered by [macports/macports-ports](https://github.com/macports/macports-ports/blob/master/devel/gh/Portfile).
To install:
```shell
sudo port install gh
```
To upgrade:
```shell
sudo port selfupdate && sudo port upgrade gh
```
### Spack
[Spack](https://spack.io/) is a flexible package manager supporting multiple versions, configurations, platforms, and compilers for supercomputers, Linux, and macOS.
The [GitHub CLI package](https://packages.spack.io/package.html?name=gh) is supported by the Spack community with updates powered by [spack/spack-packages](https://github.com/spack/spack-packages/tree/develop/repos/spack_repo/builtin/packages/gh).
To install:
```shell
spack install gh
```
To upgrade:
```shell
spack uninstall gh && spack install gh
```
### Webi
[Webi](https://webinstall.dev/) is a tool that aims to effortlessly install developer tools with easy-to-remember URLs from official builds quickly, without sudo or Admin, without a package manager, and without changing system file permissions.
The [GitHub CLI package](https://webinstall.dev/gh/) is supported by the Webi community with updates powered by [webinstall/webi-installers](https://github.com/webinstall/webi-installers/tree/main/gh).
To install:
```shell
curl -sS https://webi.sh/gh \| sh
```
To upgrade:
```shell
webi gh@stable
```

65
docs/install_source.md Normal file
View file

@ -0,0 +1,65 @@
# Installation from source
1. Verify that you have Go 1.24+ installed
```sh
$ go version
```
If `go` is not installed, follow instructions on [the Go website](https://golang.org/doc/install).
2. Clone this repository
```sh
$ git clone https://github.com/cli/cli.git gh-cli
$ cd gh-cli
```
3. Build and install
**Unix-like systems**
```sh
# installs to '/usr/local' by default; sudo may be required, or sudo -E for configured go environments
$ make install
# or, install to a different location
$ make install prefix=/path/to/gh
```
**Windows**
```pwsh
# build the `bin\gh.exe` binary
> go run script\build.go
```
There is no install step available on Windows.
4. Run `gh version` to check if it worked.
**Windows**
Run `bin\gh version` to check if it worked.
## Cross-compiling binaries for different platforms
You can use any platform with Go installed to build a binary that is intended for another platform
or CPU architecture. This is achieved by setting environment variables such as GOOS and GOARCH.
For example, to compile the `gh` binary for the 32-bit Raspberry Pi OS:
```sh
# on a Unix-like system:
$ GOOS=linux GOARCH=arm GOARM=7 CGO_ENABLED=0 make clean bin/gh
```
```pwsh
# on Windows, pass environment variables as arguments to the build script:
> go run script\build.go clean bin\gh GOOS=linux GOARCH=arm GOARM=7 CGO_ENABLED=0
```
Run `go tool dist list` to list all supported values of GOOS/GOARCH.
Tip: to reduce the size of the resulting binary, you can use `GO_LDFLAGS="-s -w"`. This omits
symbol tables used for debugging. See the list of [supported linker flags](https://golang.org/cmd/link/).

101
docs/install_windows.md Normal file
View file

@ -0,0 +1,101 @@
# Installing gh on Windows
## Recommended _(Official)_
### WinGet
[WinGet](https://learn.microsoft.com/en-us/windows/package-manager/winget/) is a command line tool enabling users to discover, install, upgrade, remove and configure applications on Windows 10, Windows 11, and Windows Server 2025 computers. This tool is the client interface to the Windows Package Manager service.
The [GitHub CLI package](https://winget.run/pkg/GitHub/cli) is supported by Microsoft with updates powered by [microsoft/winget-pkgs](https://github.com/microsoft/winget-pkgs/tree/master/manifests/g/GitHub/cli/).
To install:
```pwsh
winget install --id GitHub.cli
```
To upgrade:
```pwsh
winget upgrade --id GitHub.cli
```
> [!NOTE]
> The Windows installer modifies your PATH. When using Windows Terminal, you will need to **open a new window** for the changes to take effect. (Simply opening a new tab will _not_ be sufficient.)
### Precompiled binaries
[GitHub CLI releases](https://github.com/cli/cli/releases/latest) contain precompiled `exe` and `msi` binaries for `386`, `amd64` and `arm64` architectures.
## Community _(Unofficial)_
> [!IMPORTANT]
> The GitHub CLI team does not maintain the following packages or repositories. We are unable to provide support for these installation methods or any guarantees of stability, security, or availability for these installation methods.
### Chocolatey
The [GitHub CLI package](https://community.chocolatey.org/packages/gh) is supported by the Chocolatey community with updates powered by [pauby/ChocoPackages](https://github.com/pauby/ChocoPackages/tree/master/automatic/gh).
To install:
```pwsh
choco install gh
```
To upgrade:
```pwsh
choco upgrade gh
```
### Conda
[Conda](https://docs.conda.io/en/latest/) is an open source package management system and environment management system for installing multiple versions of software packages and their dependencies and switching easily between them. It works on Linux, OS X and Windows, and was created for Python programs but can package and distribute any software.
The [GitHub CLI package](https://anaconda.org/conda-forge/gh) is supported by the Conda community with updates powered by [conda-forge/gh-feedstock](https://github.com/conda-forge/gh-feedstock#installing-gh).
To install:
```shell
conda install gh --channel conda-forge
```
To upgrade:
```shell
conda update gh --channel conda-forge
```
### Scoop
The [GitHub CLI bucket](https://scoop.sh/#/apps?q=gh) is supported by the Scoop community with updated powered by [ScoopInstaller/Main](https://github.com/ScoopInstaller/Main/blob/master/bucket/gh.json).
To install:
```pwsh
scoop install gh
```
To upgrade:
```pwsh
scoop update gh
```
### Webi
[Webi](https://webinstall.dev/) is a tool that aims to effortlessly install developer tools with easy-to-remember URLs from official builds quickly, without sudo or Admin, without a package manager, and without changing system file permissions.
The [GitHub CLI package](https://webinstall.dev/gh/) is supported by the Webi community with updates powered by [webinstall/webi-installers](https://github.com/webinstall/webi-installers/tree/main/gh).
To install:
```shell
curl -sS https://webi.sh/gh \| sh
```
To upgrade:
```shell
webi gh@stable
```