Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 36 ยท Getting Started

The GitHub CLI (gh)

Use the gh command-line tool to sign in, create and clone repositories, open and review pull requests, manage issues, run API calls and write your own aliases.

The website is great for browsing, but many tasks are quicker from the terminal: create a repository, check out someone's pull request, see why a build failed. GitHub's official command-line tool, gh, brings those features to your shell. It is a separate program from git: git manages commits and branches, gh talks to GitHub's services (repositories, pull requests, issues, workflows, releases).

Install it from cli.github.com or your package manager (winget install GitHub.cli, brew install gh, apt install gh), then check with gh --version.

Signing in

Terminal
gh auth login

The command asks which host (GitHub.com), which protocol (HTTPS or SSH), and how to authenticate (a browser flow or a pasted token). If you pick HTTPS it also configures Git to use gh as a credential helper, which solves the password problem from Authentication. Useful companions:

Terminal
gh auth status     # who am I signed in as, with which scopes?
gh auth refresh    # add scopes later
gh auth logout

Repositories

Terminal
gh repo create weather-cli --public --clone      # new repo, cloned into ./weather-cli
gh repo create my-project --private --source=. --push   # publish the current folder
gh repo clone octo-org/hello-world               # like git clone, no URL needed
gh repo view --web                               # open this repo in the browser
gh repo fork octo-org/hello-world --clone        # fork, then clone your fork

gh repo fork also adds an upstream remote when you clone from inside the original (more in Forks and Upstream).

Pull requests

You will see these again in the pull request chapter. The most used ones:

Terminal
git switch -c fix-typo
# ...edit and commit...
git push -u origin fix-typo
gh pr create --fill                 # title/body from your commits
gh pr create --title "Fix typo" --body "Closes #12" --reviewer ada --label docs
gh pr list --state open             # pull requests in this repo
gh pr view 42 --comments            # read one, including discussion
gh pr checkout 42                   # fetch and switch to someone's pull request
gh pr diff 42                       # unified diff in the terminal
gh pr checks 42                     # CI status
gh pr merge 42 --squash --delete-branch

Issues, releases and workflows

Terminal
gh issue create --title "Crash on empty input" --label bug
gh issue list --assignee @me
gh issue close 17 --comment "Fixed in #42"
gh release create v1.0.0 --generate-notes
gh run list                         # recent workflow runs
gh run watch                        # follow the current run live
gh workflow run build.yml           # trigger a workflow that has workflow_dispatch

Scripting with output formats

gh is designed to be scripted. Most list commands accept --json with a list of fields, --jq to filter, and --template for custom text:

Terminal
gh pr list --json number,title,author --jq '.[] | "\(.number)  \(.title)  (\(.author.login))"'
gh issue list --label bug --json number,title --limit 100

The --jq flag uses a built-in jq engine, so you do not need jq installed. Because of the JSON option, results are easy to feed into other tools.

JS Stand-in: what --json and --jq do

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The raw API

When there is no dedicated command, gh api calls any REST or GraphQL endpoint with your credentials:

Terminal
gh api repos/octo-org/hello-world/languages
gh api repos/{owner}/{repo}/issues --method POST -f title="Bug" -f body="Details"
gh api graphql -f query='{ viewer { login } }'

and are filled from the current directory's remote. More on the API later in the track.

Aliases and extensions

Create your own shortcuts, much like Git aliases:

Terminal
gh alias set mine 'pr list --author @me'
gh mine

Extensions are programs named gh-something that add commands (gh extension search, gh extension install owner/gh-name). Review an extension's source before installing it, since it runs with your credentials.

JS Stand-in: a tiny command dispatcher

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Which command checks out someone else's pull request number 42 locally?

    gh pr checkout fetches the pull request branch and switches to it.
  2. 2. What does gh pr create --fill do?

    --fill takes the title and body from your commits instead of prompting.
  3. 3. How can you filter gh output without installing jq?

    gh bundles a jq engine reachable through --jq.

Summary

  • gh is GitHub's official CLI; it complements git rather than replacing it.
  • gh auth login signs you in and can configure Git's credentials.
  • Common nouns: repo, pr, issue, release, run, workflow, api.
  • --json, --jq and gh api make GitHub scriptable; aliases and extensions add your own commands.

Next: README, License and .gitignore