The Essential GitHub CLI Commands

Camille Clarret -

Last September, GitHub launched GitHub CLI 1.0 and brought GitHub to the terminal.

GitHub CLI is GitHub command-line interface. It brings pull requests, issues, and other GitHub concepts to the terminal next to where you are already working with Git and your code — according to its documentation.

In this article, you will find basic and useful commands that you need to know to enjoy your journey on the terminal.

Before starting to use GitHub CLI, you need to have a GitHub account and link Git to it. You can set up Git with this documentation and getting started with GitHub here.

Getting Started

First, open your terminal and pick a project. To get help with any command, use the help command:

$ gh help [command] [flags]

There are five core commands and a few more additionals ones. This post will focus on gist, issue, repo (repository), and pr (pull request).

Managing Gists

Gists allow you to share code, notes, and snippets quickly with other people — publicly or privately. You can take advantage of this feature in GitHub CLI.

To create your gist from the file my_mergify_gist.py in your current folder:

$ gh gist create my_mergify_gist.py
- Creating gist my_mergify_gist.py
✓ Created gist my_mergify_gist.py
https://gist.github.com/4b5ba0b5daabf386ee01bc37ab667e58

You can share the printed link with anyone so they can read your gist. Your gist is private by default. If you want to create a public gist, use the --public flag:

$ gh gist create --public my_mergify_gist.py
- Creating gist my_mergify_gist.py
✓ Created gist my_mergify_gist.py
https://gist.github.com/4b5ba0b5daabf386ee01bc37ab667e58

You can list all your gist:

$ gh gist list
4b5ba0b5daabf386ee01bc37ab667e58 my_mergify_gist1.py	 1 file public about 1 hour ago
4b5ba0b5daabf386ee01bc37ab667e59 my_mergify_gist2.py	 1 file secret about 2 hour ago

You can also apply filters on this list using the --limit int argument (default to 10) along with the --public and --secret flags.

You can display a specific gist from its ID or URL:

$ gh gist view 4b5ba0b5daabf386ee01bc37ab667e58
pull_request_rules:
  - name: automatic merge for main when CI passes and 2 reviews
    conditions:
      - "#approved-reviews-by>=2"
      - check-success=Travis CI - Pull Request
      - base=main
    actions:
      merge:
        method: merge

Finally, you can delete a specific gist using its ID or URL:

$ gh gist delete 4b5ba0b5daabf386ee01bc37ab667e58

Managing Issues

Issues are suitable for collecting user feedback, report software bugs, and organizing tasks you'd like to accomplish in a repository. Here is how to manage your issues in GitHub CLI.

Creating an issue:

$ gh issue create --title "Is it a bug?" --body "the behavior’s description"
Creating issue in CamClrt/MergifySuperRepository
https://github.com/CamClrt/MergifySuperRepository/issues/1

Listing all the repository’s issues:

$ gh issue list
Showing 1 of 1 open issue in CamClrt/MergifySuperRepository
#1  Is it a bug?    about 2 minutes ago

Using different flags, you can apply filters on this list. You can even open your browser with --web to list the issue(s) as well.

Displaying the status of your issues:

$ gh issue status
Relevant issues in CamClrt/MergifySuperRepository
Issues assigned to you
There are no issues assigned to you
Issues mentioning you
There are no issues mentioning you
Issues opened by you
#1  Is it a bug?    about 3 minutes ago

Finally, closing an issue:

$ gh issue close 1
✓ Closed issue #1 (Is it a bug?)

Managing Repositories

Repositories are the basis of everything regarding developing projects, sharing code, and discussing them with contributors or colleagues. Here is how to manage your repositories in GitHub CLI.

Create a public repository:

$ gh repo create MergifySuperRepository
? Visibility Public
? This will create the "MergifySuperRepository" repository on GitHub. Continue? Yes
✓ Created repository CamClrt/MergifySuperRepository on GitHub
? Create a local project directory for "CamClrt/MergifySuperRepository"? Yes
Initialized empty Git repository in /Users/cam/Documents/sandbox/MergifySuperRepository/.git/
✓ Initialized repository in "MergifySuperRepository"

Thanks to the interactive interface, you can determine if your future repository will be private or public, created in the current directory or not, without opening a browser.

Cloning or forking repositories with GitHub CLI are also accessible as child's play.

$ gh repo clone Mergifyio/mergify-engine
Cloning into 'mergify-engine'...
remote: Enumerating objects: 56847, done.
remote: Counting objects: 100% (3416/3416), done.
remote: Compressing objects: 100% (849/849), done.
remote: Total 56847 (delta 2393), reused 3148 (delta 2202), pack-reused 53431
Receiving objects: 100% (56847/56847), 227.99 MiB | 16.25 MiB/s, done.
Resolving deltas: 100% (38429/38429), done.
Updating files: 100% (686/686), done.

Forking a repository:

$ gh repo fork Mergifyio/react-crisp
✓ Created fork CamClrt/react-crisp
? Would you like to clone the fork? Yes
Cloning into 'react-crisp'...
remote: Enumerating objects: 246, done.
remote: Counting objects: 100% (143/143), done.
remote: Compressing objects: 100% (110/110), done.
remote: Total 246 (delta 84), reused 42 (delta 21), pack-reused 103
Receiving objects: 100% (246/246), 281.45 KiB | 756.00 KiB/s, done.
Resolving deltas: 100% (128/128), done.
Updating upstream
From github.com:Mergifyio/react-crisp
* [new branch]      master     -> upstream/master
✓ Cloned fork

Then, listing the repository of an account:

$ gh repo list CamClrt 
Showing 22 of 22 repositories in @CamClrt
CamClrt/MergifySuperRepository							public 19m
CamClrt/react-crisp React implementation for Crisp public, 			   fork 1h
CamClrt/mergify.io mergify.io 						 private, fork  1h
CamClrt/mergify-engine Engine for Mergify					public, fork   1h

You can filter this list down using the --archived, --no-archived, or --source flags.

Managing Pull Requests

Finally, pull requests could be the most important tool because you use them every day. Pull requests allow collaboration on GitHub. When working on a project with others, pull requests help you proposing your changes without infringing on the production code.

Creating a pull request with a specific title and body:

$ gh pr create --title "feat: my_super_feature" --body "all the details"
? Where should we push the 'other_branch' branch? CamClrt/MergifySuperRepository
Creating pull request for other_branch into main in CamClrt/MergifySuperRepository
To github.com:CamClrt/MergifySuperRepository.git
864bdab..ef1c1d6  HEAD -> other_branch
Branch 'other_branch' set up to track remote branch 'other_branch' from 'origin'.
https://github.com/CamClrt/MergifySuperRepository/pull/1

Listing all the pull requests in the repository:

$ gh pr list
Showing 6 of 6 open pull requests in Mergifyio/mergify-engine
#2530  chore(deps): bump httptools from 0.1.1 to 0.2.0    dependabot/pip/httptools-0.2.0
#2512  chore(deps): bump websockets from 8.1 to 9.0.1    dependabot/pip/websockets-9.0.1
#2498  feat(squash): add squash command                                CamClrt:MRGFY-284
#2434  chore(deps): bump hyperframe from 5.2.0 to 6.0.1  dependabot/pip/hyperframe-6.0.1
#1978  chore(deps): bump starlette from 0.13.6 to 0.14.2 dependabot/pip/starlette-0.14.2
#1766  chore(deps): bump idna from 2.10 to 3.1                   dependabot/pip/idna-3.1

As mentioned before, this command allows you to apply a large number of filters like --assignee, --base, --label, and more.

Displaying the status of your pull requests:

$ gh pr status
Relevant pull requests in Mergifyio/mergify-engine
Current branch
#2498  feat(squash): add squash command [CamClrt:MRGFY-284]
× 2/11 checks failing
Created by you
#2498  feat(squash): add squash command [CamClrt:MRGFY-284]
× 2/11 checks failing
Requesting a code review from you
You have no pull requests to review

Getting a pull request to inspect it:

$ gh pr checkout 2530
remote: Enumerating objects: 5, done.
remote: Counting objects: 100% (5/5), done.
remote: Compressing objects: 100% (3/3), done.
remote: Total 3 (delta 2), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (3/3), 813 bytes | 116.00 KiB/s, done.
From https://github.com/Mergifyio/mergify-engine
* [new branch]        dependabot/pip/httptools-0.2.0 -> upstream/dependabot/pip/httptools-0.2.0
Switched to a new branch 'dependabot/pip/httptools-0.2.0'

Displaying Continuous Integration (CI) status for a specific pull request:

$ gh pr checks 1234
X  Queue: Embarked in merge train                         https://github.com/Mergifyio/mergify-engine/pull/2530/checks?check_run_id=2525903923
X  Rule: automatic merge from dependabot (queue)          https://github.com/Mergifyio/mergify-engine/pull/2530/checks?check_run_id=2525902842
X  docs                                           5m12s   https://github.com/Mergifyio/mergify-engine/runs/2525901911
X  heroku                                         1m36s   https://github.com/Mergifyio/mergify-engine/runs/2525902069
X  pep8                                           5m11s   https://github.com/Mergifyio/mergify-engine/runs/2525902163
X  py39                                           10m13s  https://github.com/Mergifyio/mergify-engine/runs/2525902250
X  requirements                                   1m14s   https://github.com/Mergifyio/mergify-engine/runs/2525902308
✓  Analyze (python)                               7m19s   https://github.com/Mergifyio/mergify-engine/runs/2525901762
✓  CodeQL                                         3s      https://github.com/Mergifyio/mergify-engine/runs/2525958205
✓  GitGuardian Security Checks                    1s      https://dashboard.gitguardian.com
✓  Semantic Pull Request                                  https://github.com/probot/semantic-pull-requests
✓  Summary                                                https://github.com/Mergifyio/mergify-engine/pull/2530/checks?check_run_id=2525902741
✓  docker                                         2m13s   https://github.com/Mergifyio/mergify-engine/runs/2525901769
GitHub CLI has fancy colours

Thanks to GitHub CLI, you will be able to significantly reduce your back and forth between the GitHub graphical interface and your terminal. This comfort and this gain in time will allow you to focus more on what matters most in your daily work life.

Going Further

This article is a short overview of what you can do with GitHub CLI. For more commands, flags, and other pieces of information, you can read the GitHub CLI documentation.

Can you optimize even more your workflow? Definitely, by installing the Mergify app from the GitHub marketplace. Mergify helps you save time by automatically prioritizing, merging, commenting, rebasing, updating, labeling, backporting, closing, and assigning your pull requests.

Leveraging Mergify is a perfect way to optimize even more your GitHub workflow. If you are curious about optimizing your workflow, you should read How Mergify Can Help With GitHub Pull Request Automation.

To use Mergify for free for open-source projects, so sign up here today. If your project isn’t open-source, you can still try it for free for 14 days!