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.
First, open your terminal and pick a project. To get help with any command, use the
$ gh help [command] [flags]
There are five core commands and a few more additionals ones. This post will focus on
repo (repository), and
pr (pull request).
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
$ 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
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
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?)
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
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
--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
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.
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.