GitHub CLI

Use the gh command to create repositories, open and merge pull requests, manage issues, watch workflow runs and script GitHub from the terminal.

Lesson 20 of 30Advanced17 min read

Git works in the terminal, but many everyday GitHub tasks, such as opening a pull request, checking whether tests passed or creating an issue, normally mean switching to the browser. The GitHub CLI, a command called gh, brings those tasks into the terminal, right next to your Git commands.

With gh, you can create a repository and push to it in one command, open a pull request with a title and description taken from your commits, check out a teammate's pull request to test it, watch an Actions run finish, and open any page in the browser when you do want to see it. Because it's a command, it can also be used in scripts to automate repetitive work.

In this final GitHub lesson you'll install and sign in to gh, then use it for repositories, pull requests, issues, workflow runs and releases, and finish with aliases, JSON output and the gh api command for anything else.

Installing and signing in

Install GitHub CLI from cli.github.com, or with a package manager: winget install GitHub.cli on Windows, brew install gh on macOS. Then sign in:

Terminal
gh auth login

Choose GitHub.com, your preferred protocol (HTTPS or SSH) and Login with a web browser. gh shows a one-time code, opens the browser and stores the credential securely. It can also configure Git to use it, which solves the authentication problem for HTTPS pushes. Check with gh auth status.

Repositories

CommandWhat it does
gh repo createCreate a repository, interactively or with flags
gh repo clone owner/nameClone using just the short name
gh repo fork owner/name --cloneFork and clone in one step, with upstream set up
gh repo view --webOpen the current repository in the browser
gh browseOpen the current repository, or gh browse 14 for issue or PR 14

Run inside a repository, gh works out which GitHub repository you mean from its remotes, so you rarely need to type names.

Pull requests and issues

  • gh pr create --fill opens a PR from the current branch, using your commit messages for the title and body.
  • gh pr status shows your PRs, PRs waiting for your review and the current branch's checks.
  • gh pr checkout 42 and gh pr diff 42 help you review.
  • gh pr merge --squash --delete-branch merges and tidies up.
  • gh issue list --label bug, gh issue create and gh issue close 14 manage issues.

Most commands open an interactive prompt if you leave out options, so you don't need to remember every flag.

Actions, JSON output and the API

gh run list shows recent workflow runs, and gh run watch follows one live until it finishes. gh run view --log-failed prints just the failing step's log.

Many commands accept --json with field names, plus --jq to filter the result, which makes them easy to use in scripts. For anything without a dedicated command, gh api calls GitHub's REST API with your login already applied, for example gh api repos/samlee/portfolio.

GitHub CLI Syntax

Common gh commands

gh auth login
gh repo create <name> --public --source=. --push
gh repo clone <owner>/<repo>
gh pr create --fill
gh pr status
gh pr checkout <number>
gh pr merge <number> --squash --delete-branch
gh issue create --title "..." --label bug
gh run watch
gh browse
gh api <endpoint>

GitHub CLI Summary

  • gh is GitHub's official command-line tool; sign in once with gh auth login.
  • gh repo create, clone and fork manage repositories without the browser.
  • gh pr create --fill, checkout, status and merge cover the pull request cycle.
  • gh issue and gh run manage issues and Actions workflow runs.
  • --json, --jq and gh api let you script anything on GitHub.

GitHub CLI Examples

Each example shows the code, the output it produces and what each part does.

Example 1

Publish a local project in one command

Terminal
git init
git add .
git commit -m "First version"
gh repo create recipe-box --public --source=. --push
Output
Initialized empty Git repository in /c/Users/sam/recipe-box/.git/
[main (root-commit) 1a2b3c4] First version
 6 files changed, 214 insertions(+)
✓ Created repository samlee/recipe-box on GitHub
✓ Added remote https://github.com/samlee/recipe-box.git
✓ Pushed commits to https://github.com/samlee/recipe-box.git
Line-by-line explanation
  1. Lines 1 to 3An ordinary local repository with one commit.
  2. Line 4Creates the GitHub repository, adds it as origin and pushes, replacing several steps from the push and pull lesson.
Example 2

A full pull request cycle

Terminal
git switch -c add-ratings
git commit -am "feat: add star ratings to recipes"
git push -u origin add-ratings
gh pr create --fill
gh pr checks --watch
gh pr merge --squash --delete-branch
Output
Creating pull request for add-ratings into main in samlee/recipe-box
https://github.com/samlee/recipe-box/pull/47
All checks were successful
✓ test   32s
✓ Squashed and merged pull request #47 (feat: add star ratings to recipes)
✓ Deleted branch add-ratings and switched to branch main
Line-by-line explanation
  1. Line 4--fill uses the commit message as the PR's title and body.
  2. Line 5Waits for the Actions checks and shows the result.
  3. Line 6Squash merges, deletes the branch locally and on GitHub, and switches back to main.
Example 3

JSON output for scripts

Terminal
gh issue list --label bug --json number,title --jq '.[] | "#\(.number) \(.title)"'
gh api repos/samlee/recipe-box --jq '.stargazers_count'
Output
#52 Search ignores capital letters
#49 Basket shows NaN when empty
18
Line-by-line explanation
  1. Line 1List open bug issues as JSON, then format each one as a line of text.
  2. Line 2Call the API for the repository's details and print just its star count.

Common GitHub CLI Mistakes

Running gh outside a repository

Don't
cd ~
gh pr list      # no git remotes found
Do
cd ~/projects/recipe-box
gh pr list
# or: gh pr list --repo samlee/recipe-box

Creating a PR before pushing

Don't
git switch -c fix-nav
git commit -am "Fix nav"
gh pr create --title "Fix nav" --body "Fixes the menu on mobile" --head fix-nav
Do
git push -u origin fix-nav
gh pr create --fill

The branch must exist on GitHub. If you leave out --head, gh offers to push it for you.

Merging without checking the result

Don't
gh pr create --fill && gh pr merge --admin --squash
Do
gh pr create --fill
gh pr checks --watch
gh pr merge --squash

--admin skips protection rules. Wait for checks and reviews instead.

GitHub CLI in Real Projects

gh in daily work

Many developers keep gh pr status as their morning check of what needs reviewing, and use gh pr checkout to test teammates' work without copying branch names. Maintainers script gh to label issues, close stale pull requests or gather release statistics, and it's preinstalled on GitHub Actions runners, so workflows can use the same commands you use at your desk.

GitHub CLI FAQ

How do I sign in to gh without a browser?

Pipe a personal access token into gh auth login --with-token, for example gh auth login --with-token < token.txt. Or set the GH_TOKEN environment variable, which gh uses automatically, which suits servers and scripts.

How do I switch between two GitHub accounts in gh?

Sign in to both with gh auth login, then run gh auth switch to change the active account. gh auth status shows which accounts are signed in and which one is active.

How do I make gh clone with SSH instead of HTTPS?

Run gh config set git_protocol ssh. After that, gh repo clone and gh repo fork set up SSH remote URLs. You can also choose the protocol when you first run gh auth login.

Can I use gh inside GitHub Actions?

Yes. gh comes installed on GitHub-hosted runners. Give it a token through the GH_TOKEN environment variable, usually GH_TOKEN: ${{ github.token }}, and make sure the workflow's permissions allow what the commands need.

How do I open the current repository in my browser from the terminal?

Run gh browse inside the repository. Add a path such as gh browse src/app.js to open a file, gh browse 42 to open issue or pull request 42, or --settings to open the settings page.

GitHub CLI Exercises

Answer each one and check it instantly. If you get stuck, open the hint before the answer.

Fill in the blankseasy

Complete the command that signs GitHub CLI in to your account.

gh auth
Multiple choiceeasy

Which command opens a pull request using your commit messages?

Multiple choicemedium

What does gh pr checkout 42 do?

Multiple choicemedium

Which command follows a running Actions workflow until it finishes?

Multiple choicehard

How can you call a GitHub API endpoint that has no dedicated gh command?

GitHub CLI Quiz

5 questions to check what you learned.

  1. What is gh?

    • A newer version of Git
    • GitHub's official command-line tool for working with GitHub
    • A Git alias
    • A text editor

  2. What does gh repo create name --source=. --push do?

    • Clones a repository
    • Deletes the remote
    • Creates a fork
    • Creates a GitHub repository from the current folder, adds the remote and pushes

  3. What does gh browse do inside a repository?

    • Opens the repository on GitHub in your web browser
    • Lists files
    • Searches all of GitHub
    • Downloads a release

  4. Why use --json with gh commands?

    • It makes output colourful
    • It's required for all commands
    • It speeds up pushes
    • It gives structured output that scripts can read and filter

  5. Why avoid gh pr merge --admin in normal work?

    • It deletes the repository
    • It bypasses branch protection, skipping required reviews and checks
    • It only works on forks
    • It doesn't merge anything

Related GitHub topics

08Pull RequestsPropose changes from a branch, review them, respond to feedback and merge with a pull request.15GitHub ActionsAutomate testing, checks and deployments with GitHub Actions workflows written in YAML.16ReleasesPublish versions of your project with GitHub Releases: tags, semantic version numbers, release notes, downloadable files and automation.
Esc
↑↓ to navigateEnter to open