Skip to content
Get packs

Guide · Open source

How to use cli: GitHub CLI (gh) for pull requests and issues

Updated · written with AI from the project's own documentation and checked against our catalogue data

cli/cli is GitHub's official command line tool, run as the command gh. It brings pull requests, issues and other GitHub concepts into your terminal, next to git and your code. This guide explains what it is, how to install it, how to install the agent skill, and who should use it.

GitHub CLIcli/cli · ★ 46.8k · MIT

Quick start

  1. 1Install git. gh lists git as a prerequisite, so make sure git is installed first.
  2. 2Install gh for your platform. Use Homebrew on macOS, WinGet on Windows, or a Linux package for your distribution. Precompiled binaries are on the releases page.
  3. 3Confirm the command runs. Open a new terminal and run gh to check that the command is available.
  4. 4Install the agent skill (optional). Run gh skill install cli/cli gh --scope user if you use coding agents.
  5. 5Open the manual. Read the usage instructions at cli.github.com/manual for the commands you need.

What is the GitHub CLI and who is it for?

GitHub CLI, or the gh CLI, is GitHub on the command line. It lets you do common GitHub tasks without switching to the browser. The README says it is supported on macOS, Windows and Linux, and works with GitHub.com, GitHub Enterprise Cloud and supported GitHub Enterprise Server versions.

It fits developers who already work in the terminal and use GitHub daily, people who review or open pull requests often from the command line, and teams that want GitHub tasks scripted or automated.

  • Best for: developers who already work in the terminal and use GitHub daily
  • Best for: people who review or open pull requests often from the command line
  • Best for: teams that want GitHub tasks scripted or automated
  • Not for: people who do not use GitHub, since the tool only works with GitHub services
  • Not for: users who prefer a graphical interface over the terminal

Install gh on macOS, Windows or Linux

Install GitHub CLI with a package manager or a precompiled binary. The README lists Homebrew for macOS, WinGet for Windows, and Debian, Raspberry Pi, Ubuntu, Amazon Linux, CentOS, Fedora, openSUSE, RHEL and SUSE packages for Linux & Unix. Precompiled binaries are on the releases page, and build from source is also documented.

The prerequisite listed for this tool is git. Install git first, then follow the platform guide for your system.

  • macOS: Homebrew or precompiled binaries (docs/install_macos.md)
  • Linux & Unix: Debian/Ubuntu/Raspberry Pi, RPM-based distributions, or precompiled binaries (docs/install_linux.md)
  • Windows: WinGet or precompiled binaries (docs/install_windows.md)
  • Build from source: docs/install_source.md

Install the gh agent skill

An agent skill is available for driving gh from coding agents. The README says to install or update it with the built-in gh skill command. User scope is recommended.

Run the install command once, and run the update command after a gh release to refresh the skill.

# Install the skill (user scope recommended) gh skill install cli/cli gh --scope user # Update the skill after a `gh` release gh skill update gh

Check that a downloaded release is genuine

Since version 2.50.0, gh has produced Build Provenance Attestations, which give a verifiable record of the origin repository, git revision and build instructions. If gh is already installed, the README shows you can verify a new release with the gh at verify command. Otherwise you can use Sigstore cosign with the attestation file from the cli/cli attestations page.

Verification is optional, but it is the documented way to confirm a downloaded binary matches the official build.

$ gh at verify -R cli/cli gh_2.62.0_macOS_arm64.zip

Use gh in GitHub Codespaces and GitHub Actions

To add GitHub CLI to a Codespace, add the feature shown below to your devcontainer file. GitHub-hosted runners in GitHub Actions have the GitHub CLI pre-installed, and it is updated weekly. If a workflow needs a specific version, it must install that version itself using the platform instructions.

"features": { "ghcr.io/devcontainers/features/github-cli:1": {} }

How does gh differ from hub?

hub was for many years the unofficial GitHub CLI tool. According to the README, hub behaves as a proxy to git, while gh is a standalone tool. Both bring GitHub to the terminal. The project's own comparison page explains the design differences in more detail.

If you already rely on hub, read the comparison before switching so you know which commands map across.

What people use it for

  • Opening and reviewing pull requests without leaving the terminal
  • Checking and creating issues from the command line
  • Scripting or automating GitHub tasks for a team
  • Driving gh from coding agents through the agent skill
  • Adding GitHub CLI to a Codespace or using it in GitHub Actions workflows

Frequently asked questions

Is GitHub CLI free to use?

The source is the cli/cli README, which states the project is licensed under MIT. The MIT licence is an open-source licence, so check the LICENSE file in the repository for the full terms.

What do I need before installing gh?

The listed prerequisite is git. The README also says gh is supported on macOS, Windows and Linux, and works with GitHub.com, GitHub Enterprise Cloud and supported GitHub Enterprise Server versions.

Does gh work with GitLab or Bitbucket?

No. The tool only works with GitHub services, so it is not for people who do not use GitHub.

How do I install gh on macOS?

The README points to Homebrew or precompiled binaries from the releases page. The macOS install guide in the docs folder covers both options.

What is the difference between gh and hub?

hub acts as a proxy to git, while gh is a standalone tool. The README describes hub as the unofficial GitHub CLI for many years, and gh as the newer official project.

How do I verify that a gh download is genuine?

Use gh at verify with the release file if gh is already installed. Otherwise, use Sigstore cosign with the attestation file from the cli/cli attestations page.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

GitHub CLI suits developers who live in the terminal, review pull requests often, or want GitHub tasks scripted. If you do not use GitHub, prefer a graphical interface, or run on a platform outside macOS, Windows and Linux, pick a different tool.

Install options & downloads