Examples

GitHub CLI usage examples

Checking out a pull request locally

Using pull request number

You can check out any pull request, including from forks, in a repository using its pull request number

// Checking out a pull request locally
~/Projects/my-project$ gh pr checkout 12
remote: Enumerating objects: 66, done.
remote: Counting objects: 100% (66/66), done.
remote: Total 83 (delta 66), reused 66 (delta 66), pack-reused 17
Unpacking objects: 100% (83/83), done.
From https://github.com/owner/repo
 * [new ref]             refs/pull/8896/head -> patch-2
M       README.md
Switched to branch 'patch-2'

~/Projects/my-project$

Using other selectors

You can also use URLs and branch names to checkout pull requests.

// Checking out a pull request locally
~/Projects/my-project$ gh pr checkout branch-name
Switched to branch 'branch-name'
Your branch is up to date with 'origin/branch-name'.
Already up to date.

~/Projects/my-project$

Cloning a repository

Using OWNER/REPO syntax

You can clone any repository using OWNER/REPO syntax.

# Cloning a repository
~/Projects$ gh repo clone cli/cli
Cloning into 'cli'...
~/Projects$ cd cli
~/Projects/cli$

Using other selectors

You can also use GitHub URLs to clone repositories.

# Cloning a repository
~/Projects/my-project$ gh repo clone https://github.com/cli/cli
Cloning into 'cli'...
remote: Enumerating objects: 99, done.
remote: Counting objects: 100% (99/99), done.
remote: Compressing objects: 100% (76/76), done.
remote: Total 21160 (delta 49), reused 35 (delta 18), pack-reused 21061
Receiving objects: 100% (21160/21160), 57.93 MiB | 10.82 MiB/s, done.
Resolving deltas: 100% (16051/16051), done.

~/Projects/my-project$

Creating issues and pull requests

Interactively

# Create a pull request interactively
~/Projects/my-project$ gh pr create
Creating pull request for feature-branch into main in owner/repo
? Title My new pull request
? Body [(e) to launch nano, enter to skip]
http://github.com/owner/repo/pull/1
~/Projects/my-project$

# Create an issue interactively
~/Projects/my-project$ gh issue create
Creating issue in owner/repo
? Title My new issue
? Body [(e) to launch nano, enter to skip]
http://github.com/owner/repo/issues/1
~/Projects/my-project$

With flags

# Create a pull request using flags
~/Projects/my-project$ gh pr create --title "Pull request title" --body "Pull request body"
http://github.com/owner/repo/pull/1
~/Projects/my-project$

# Create an issue using flags
~/Projects/my-project$ gh issue create --title "Issue title" --body "Issue body"
http://github.com/owner/repo/issues/1
~/Projects/my-project$

In the browser

// Quickly navigate to the pull request creation page
~/Projects/my-project$ gh pr create --web
Opening https://github.com/owner/repo/pull/branch in your browser.
~/Projects/my-project$

// Quickly navigate to the issue creation page
~/Projects/my-project$ gh issue create --web
Opening https://github.com/owner/repo/issues/new in your browser.
~/Projects/my-project$

Working with forks

This command will automatically create a fork for you if you're in a repository that you don't have permission to push to.

Forking repositories

With no arguments

Inside a git repository, and without any arguments, we will automatically create a fork on GitHub on your account for your current directory. It will then prompt if you want to set an upstream remote.

# Create a fork for the current repository.
~/Projects/cli$ gh repo fork
- Forking cli/cli...
✓ Created fork user/cli
? Would you like to add a remote for the fork? Yes
✓ Renamed origin remote to upstream
✓ Added remote origin
~/Projects/cli$

With arguments

If you pass a repository in OWNER/REPO format, `gh` will automatically create a fork on GitHub on your account and ask if you want to clone it. This works inside or outside of a git repository.

# Create a fork for another repository.
~/Projects$ gh repo fork cli/cli
- Forking cli/cli...
✓ Created fork cli/cli
? Would you like to clone the fork? Yes
Cloning into 'cli'...
✓ Cloned fork
~/Projects$ cd cli
~/Projects/cli$

Using flags

Use flags to skip prompts about adding a git remote for the fork, or about cloning the forked repository locally.

# Skipping remote prompts using flags
~/Projects/cli$ gh repo fork --remote=false
- Forking cli/cli...
✓ Created fork user/cli
~/Projects/cli$

# Skipping clone prompts using flags
~/Projects$ gh repo fork cli/cli --clone=false
- Forking cli/cli...
✓ Created fork user/cli
~/Projects$

Using lists of issues or pull requests in a repository

Default behavior

You will see the most recent 30 open items.

# Viewing a list of open pull requests
~/Projects/my-project$ gh pr list

Pull requests for owner/repo

#14  Upgrade to Prettier 1.19                           prettier
#14  Extend arrow navigation in lists for MacOS         arrow-nav
#13  Add Support for Windows Automatic Dark Mode        dark-mode
#8   Create and use keyboard shortcut react component   shortcut

~/Projects/my-project$

# Viewing a list of open issues
~/Projects/my-project$ gh issue list

Issues for owner/repo

#14  Update the remote url if it changed  (bug)
#14  PR commands on a detached head       (enhancement)
#13  Support for GitHub Enterprise        (wontfix)
#8   Add an easier upgrade command        (bug)

~/Projects/my-project$

Filtering with flags

You can use flags to filter the list for your specific use cases.

# Viewing a list of closed pull requests assigned to a user
~/Projects/my-project$ gh pr list --state closed --assignee user

Pull requests for owner/repo

#13  Upgrade to Electron 7         electron-7
#8   Release Notes Writing Guide   release-notes

~/Projects/my-project$

# Viewing a list of closed issues assigned to a user
~/Projects/my-project$ gh issue list --state closed --assignee user

Issues for owner/repo

#13  Enable discarding submodule changes  (bug)
#8   Upgrade to latest react              (upgrade)

~/Projects/my-project$

Viewing the status of your relevant work

Pull requests

# Viewing the status of your relevant pull requests
~/Projects/my-project$ gh pr status
Current branch
  #12 Remove the test feature [user:patch-2]
   - All checks failing - Review required

Created by you
  You have no open pull requests

Requesting a code review from you
  #13 Fix tests [branch]
  - 3/4 checks failing - Review required
  #15 New feature [branch]
   - Checks passing - Approved

~/Projects/my-project$

Issues

# Viewing issues relevant to you
~/Projects/my-project$ gh issue status
Issues assigned to you
  #8509 [Fork] Improve how Desktop handles forks  (epic:fork, meta)

Issues mentioning you
  #8938 [Fork] Add create fork flow entry point at commit warning  (epic:fork)
  #8509 [Fork] Improve how Desktop handles forks  (epic:fork, meta)

Issues opened by you
  #8936 [Fork] Hide PR number badges on branches that have an upstream PR  (epic:fork)
  #6386 Improve no editor detected state on conflicts modal  (enhancement)

~/Projects/my-project$

Viewing a pull request, issue or repository

In terminal

By default, we will display items in the terminal.

# Viewing a pull request in terminal
~/Projects/my-project$ gh pr view 21
Pull request title
opened by user. 0 comments. (label)

  Pull request body

View this pull request on GitHub: https://github.com/owner/repo/pull/21
~/Projects/my-project$

# Viewing an issue in terminal
~/Projects/my-project$ gh issue view 21
Issue title
opened by user. 0 comments. (label)

  Issue body

View this issue on GitHub: https://github.com/owner/repo/issues/21
~/Projects/my-project$

# Viewing a repository in terminal
~/Projects/my-project$ gh repo view owner/repo
owner/repo
Repository description

  Repository README

View this repository on GitHub: https://github.com/owner/repo/
~/Projects/my-project$

In the browser

Quickly open an item in the browser using --web or -w

# Viewing a pull request in the browser
~/Projects/my-project$ gh pr view 21 --web
Opening https://github.com/owner/repo/pull/21 in your browser.
~/Projects/my-project$

# Viewing an issue in the browser
~/Projects/my-project$ gh issue view 21 --web
Opening https://github.com/owner/repo/issues/21 in your browser.
~/Projects/my-project$

# Viewing a repository in the browser
~/Projects$ gh repo view owner/repo --web
Opening https://github.com/owner/repo/ in your browser.
~/Projects$

With no arguments

We will display the pull request of the branch you're currently on.

# Viewing the pull request of the branch you're on
~/Projects/my-project$ gh pr view
Pull request title
opened by user. 0 comments. (label)

  Pull request body

View this pull request on GitHub: https://github.com/owner/repo/pull/21
~/Projects/my-project$

We will display the repository you're currently in.

# Viewing the repository you're in
~/Projects/my-project$ gh repo view
owner/my-project
Repository description

  Repository README

View this repository on GitHub: https://github.com/owner/repo/
~/Projects/my-project$