GitHub CLI
GitHub’s official command-line client for repositories, issues, pull requests, releases, Actions, and API requests.
Why consider GitHub CLI?
GitHub CLI (gh) is GitHub's official open-source command-line tool that brings pull requests, issues, releases, and other GitHub workflows directly into the terminal alongside git.
Learn GitHub CLI by building
Practical setup notes, real use cases, and copy-ready examples in one focused guide.
In this guide4 sections
What gh Does and the Problem It Solves
gh is GitHub's official command-line tool. It brings pull requests, issues, and other GitHub concepts to the terminal next to where you are already working with git and your code. Before gh existed, switching between the terminal and a browser was required for common tasks such as opening a pull request, reviewing an issue, or checking workflow run status. gh removes that context switch by exposing GitHub operations as shell commands.
The tool supports GitHub.com, GitHub Enterprise Cloud, and GitHub Enterprise Server 2.20+. It runs on macOS, Windows, and Linux. The project is free and open source, distributed under the MIT License.
Installing gh
The official site at cli.github.com lists package-manager commands for each platform. Install from a verified source to ensure you receive signed packages and automatic updates.
macOS — Homebrew
brew install ghWindows — WinGet
winget install --id GitHub.cli --source wingetAfter installation on Windows, open a new terminal window (not just a new tab) for the PATH change to take effect.
Linux — Debian, Ubuntu, Raspberry Pi
The Debian packages are hosted on the GitHub CLI marketing site and signed with published PGP keys. Run the following to add the repository and install:
(type -p wget >/dev/null || (sudo apt update && sudo apt install wget -y)) \ && sudo mkdir -p -m 755 /etc/apt/keyrings \ && out=$(mktemp) && wget -nv -O$out https://cli.github.com/packages/githubcli-archive-keyring.gpg \ && cat $out | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \ && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \ && sudo mkdir -p -m 755 /etc/apt/sources.list.d \ && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \ && sudo apt update \ && sudo apt install gh -yTo upgrade later: sudo apt update && sudo apt install gh.
Linux — Fedora, RHEL (DNF5)
sudo dnf install dnf5-pluginssudo dnf config-manager addrepo --from-repofile=https://cli.github.com/packages/rpm/gh-cli.reposudo dnf install ghFor DNF4 and other distributions, see the Linux installation docs. Pre-built binaries for all platforms are also available on the releases page.
Authenticating and Typical Workflows
After installation, authenticate with your GitHub account:
gh auth loginThe command starts an interactive prompt that guides you through choosing GitHub.com or a GitHub Enterprise Server hostname, then authenticates via browser or a personal access token.
Once authenticated, common tasks become single commands:
gh pr create— open a new pull request from the current branch, with an interactive editor for title and bodygh pr list— list open pull requests for the current repositorygh pr review— add a review comment or approve a PR without leaving the terminalgh issue create— file a new issuegh issue list— view open issuesgh run list— see recent workflow runsgh run watch— stream live output from a running Actions jobgh repo clone OWNER/REPO— clone a repository and configureghas the git credential helper automaticallygh api— make authenticated calls to the GitHub REST or GraphQL API, useful for scripting
The manual at cli.github.com/manual documents every command, flag, and environment variable. The --help flag on any subcommand prints usage inline.
Scripting, Extensions, and Enterprise Considerations
gh is useful beyond interactive use. The gh api command accepts --jq for filtering JSON responses and --template for Go template formatting, enabling lightweight scripts without a separate API client. Combined with gh auth token, which prints the current token to stdout, gh can feed credentials into tools that accept tokens from environment variables.
Extensions can be installed from any GitHub repository using gh extension install OWNER/REPO. The extension system lets teams distribute custom subcommands written in any language without modifying the core binary.
For GitHub Enterprise Server, set the target host during gh auth login or configure the GH_HOST environment variable. Connectivity to the Enterprise Server instance is required; gh does not proxy through GitHub.com.
The project repository is at github.com/cli/cli and accepts contributions through the process described in the contributing guide.
Related tools
More options with a similar category or technology profile.
diskus
Minimal, fast alternative to du -sh written in Rust using multi-threaded directory traversal.
peco
Simplistic interactive filtering tool for Unix pipelines, process lists, and file trees.
Dapr CLI
Command-line tool for managing Dapr distributed application runtime environments and sidecars.
Freeze
Generate beautiful image screenshots and SVGs of code snippets and terminal outputs.