How to use GitHub CLI

It doesn’t matter whether you’re a beginner or expert in software development, all developers need to understand and learn how to use the world’s leading software development platform, GitHub. Until GitHub CLI Beta was released, GitHub could only be accessed via browser or application.

But now, you don’t need to use a browser to check the small changes made in the repository. Using GitHub command-line tool, gh, you can directly interact with GUI GitHub from your local terminal.

What is GitHub CLI?

Almost all developers use Git for project collaboration and GitHub for code hosting. But there is no command-line tool to perform GitHub functions from a terminal.

You may argue that there is already a CLI tool Hub for the same. But let me clarify that Hub is the wrapper that brings additional Git features to facilitate a better GitHub experience. Whereas GitHub CLI is a standalone tool that takes a different approach than Hub and lets you execute GitHub web app events.

Before we begin the tutorial, let’s first install the GitHub CLI.

How To Install GitHub CLI?

At the time of writing this article, GitHub CLI is available in beta version v5.5.0 for macOS, Windows, and Linux.

To install the GitHub CLI, you can run the command:

on macOS

brew install github/gh/gh

on Windows

scoop bucket add github-gh https://github.com/cli/scoop-gh.git
scoop install gh
or
choco install gh

on Linux

You can download the pre-built binary files from here.

Create And View Issues Using GitHub CLI

To report bugs or enhancements in the project, you create an issue and track the status.

gh provides commands to view all information related to the issue. You can check all the available commands to manipulate with issues.

$ gh issue
Commands related to issues
Commands related to issues

If you want to create an issue, you first need to go to your project folder and run the command:

$ gh issue create

It will prompt for the inputs about the title and body of the issue.

Create issue
Create an issue

After entering the data, you can choose an option to submit the issue either from a terminal or browser.

Opening issue in browser from terminal
An issue in a browser opened from terminal

Moreover, you can also create an issue by entering the title and body using flags.

Create issue using flags
Create an issue using flags

After that, you can list all issues and view their status using the command:

$ gh issue list

You can also filter the list of issues passing the flags such as assignee, label, state, and a number of issues as an argument for opening a particular issue.

$ gh issue list [flags]
List issues using filter tag
List issues using filter tag

Here’s the list of flags you can use to filter issues:

-a, --assignee string   Filter by assignee
-B, --base string       Filter by base branch
-l, --label strings     Filter by label
-L, --limit int         Maximum number of items to fetch (default 30)
-s, --state string      Filter by state: {open|closed|merged|all} (default "open")

Now, as we’ve created and viewed all the issues, there is also a need to resolve these issues. Hence, if someone fixes or updates the issue, we can check the changes made to any issue using various flags such as URL or number.

$ gh issue status
View issue status
View issue status

Here, you can see minimal information about the issues. But if you want more information to read and also add a modification, you can open the issue in the browser directly from the terminal using the command:

$ gh issue view [issue-number or url]

You can also use preview flag “–preview” or “-p” for viewing the content in a local terminal.

Preview issue content
Preview issue content

Create, View And Checkout Pull Requests Using GitHub CLI

Another GUI functionality of GitHub that you can manipulate using gh CLI tool is the Pull request.

You can contribute to other repository or work on a new version by creating a new branch and pull request to merge the new changes into the main branch.

To perform this action, you can now use the gh pr command with a filter directly from your local terminal.

For the demo, I’m creating a new branch ui, and switching to a new branch to create a pull request for ui into the master branch.

To create and switch to a new branch, you can use the command:

$ gh pr checkout [branch-name]
Checkout pr branch
Checkout to the PR branch

Now you can make some changes to the new branch. After the file modification, create pull request using gh pr command to merge into the master branch:

$ gh pr create
Create pull request
Create a pull request

Also, if you want to enter the title and body in the command, you can use the flags “-t” for a title and “-b” for body text.

Create pull request using flags
Create pull request using flags

Now, as you have opened the pull request, the repository owner can check the list of the pull requests along with filter using the flags.

$ gh pr list [flags]
List pull requests using flags
List pull requests using flags

Furthermore, if you want to check whether your PR is merged or requires modifications, you can use the following command to check the status of PR:

$ gh pr status [flags]
Check pull request status
Check pull request status

Moving forward, for the modification or display of PR content, you can open PR either in the browser or terminal.

$ gh pr view
View pull request
View pull request

A Way Forward

GitHub CLI is currently in the development stage, hence, we can expect more features to be added before the first version release.

Apart from the issues and pull requests, it would be great if GitHub adds commands to connect with the project board and GitHub actions.