CI/CD / Development

Introducing the GitHub CLI

21 Feb 2020 10:32am, by

Developers across the globe depend upon GitHub. It houses their repositories and serves as a version control system for individuals and teams. And although GitHub has a user-friendly web-based GUI (as well as numerous third-party desktop clients), many developers tend to spend a good amount of their development time working from within the Command Line Interface (CLI).

Given that, it makes perfect sense GitHub would finally begin work on a tool to make it easier to work with GitHub from the command line. That tool is the GitHub CLI and it’s now in beta. At the moment the tool is somewhat limited to what it can do (as it is in beta), but I would imagine a whole host of features will eventually make its way in. Currently, you can:

  • Create and view issues.
  • Create, view, and checkout pull requests.

So, yes, GitHub CLI isn’t quite as feature-rich as you might expect, but give it time and it will be.

I’m going to walk you through the process of installing GitHub CLI on Ubuntu Desktop Linux 19.10. Since this is a command line only tool, you can install it on just about any flavor of Linux (be it desktop or server). Currently, GitHub has released .deb, .rpm, .msi binary installers as well as the source code. Do note, however, in order for the gh command to properly function, it does require an available web browser. If you ssh into a server and attempt to work with the gh command, you’ll find yourself limited in what you can do. Because of that, you’ll probably want to be using this new tool on the desktop.

Let’s install.

Installation

The installation of the GitHub CLI is quite simple. Download the .deb file to your ~/Downloads directory. Once the file has downloaded, open a terminal window, change into the ~/Downloads directory with the command cd ~/Downloads. Once in that directory, install the application with the command:

sudo dpkg -i gh*.deb

After the installation completes, you’re ready to go. You can check out the (surprisingly limited) help by issuing the command:

gh help

This will list out the available commands and flags (Figure 1).

Figure 1: The gh help command in action.

Using the GitHub CLI

Using the GitHub CLI isn’t all that challenging. The first thing you must do is locate and clone a project. Say, for instance, you want to help improve the GitHub CLI itself. Head over to the project page and you’ll see the Clone or download button. Click that button to reveal the cloning address for the project (Figure 2).

Figure 2: The address for cloning the project.

Next we have to clone the project. At the moment, the gh command doesn’t have the ability to clone projects, so we’ll have to make use of the git command. Installing the GitHub CLI should install git along with it. If, however, that doesn’t happen, you can install git with the command:

sudo apt-get install git

With git ready, clone the GitHub CLI project with the command:

git clone https://github.com/cli/cli.git

Before you continue on, you need to authorize the gh. Issue the command:

gh issue list

You will be prompted to hit Enter on your keyboard, which will open your default browser and require you to log into your GitHub account (if you haven’t). If you’ve already logged into your GitHub account, you will be instructed that the authorization is complete and you can close the web browser tab.

Back at the command prompt, change into the cloned directory with the command:

cd cli

Issue the command:

gh issue list

All of the current issues associated with the gh project will be listed (Figure 3).

Figure 3: All of the issues associated with the GitHub CLI project.

You can also filter the issues. Say you want to view only those issues tagged “needs-user-input”. You can filter out everything but those issues with the command:

gh issue list --label needs-user-input

The results will list out only what you’re looking for (Figure 4).

Figure 4: Filtering out issues.

Once you find an issue you might want to work on, you can view the details of the issue with the command:

gh issue view NUMBER

Where NUMBER is the number associated with the issue. Say, for example, you’re pretty certain you can fix issue number 514. View the details with the command:

gh issue view 514

The above command will open your default web browser to display the details of the issue in question. It would be nice, at this stage of the usage, if everything could be contained with the command line, but I’m sure the developers have a reason for opening the issue in a browser.

If you find this is definitely an issue you can work on, leave the browser tab open and create a pull request with the command:

gh pr create

You will be asked for your username and password for GitHub (Figure 5).

Figure 5: Authenticating to your GitHub account.

Once you’ve authenticated, your pull request will complete. You can view the status of your work with the command:

gh pr status

Once your pull request has been reviewed, you’ll see it listed as Checks passing (with a number associated with your request), which means you can then check out your pull ready to check out the pull request with the command:

gh pr checkout NUMBER

Where NUMBER is the number associated with your pull request.

With the pull request checked out, you can get to work on the issue.

And that is how you install and use the new GitHub CLI tool. I have a feeling this command-line utility will quickly become the de facto standard for working with GitHub repositories.

Feature image by Michael Gaida from Pixabay.

A newsletter digest of the week’s most important stories & analyses.

View / Add Comments

Please stay on topic and be respectful of others. Review our Terms of Use.