The Official Github CLI is Here

Learn all about the latest official GitHub CLI and how to use it in just five minutes

GitHub, the world’s most popular Git hosting provider has existed without an official CLI tool for years now. It’s quite surprising considering the fact GitHub itself is the most-used platform for open-source projects.

But one advantage of being part of the open-source ecosystem is that the community will build things when the need arises with or without official backing and that is exactly what happened with GitHub so far.

Hub is the most popular unofficial GitHub CLI that was being used widely. According to their official website:

“Hub is an extension to command-line Git that helps you do everyday GitHub tasks without ever leaving the terminal.”

And I must say, it has served its purpose well so far. But recently, GitHub has been on the fast-track for bringing out official tools and products and they are doing a pretty good job at it, thanks to all the big money and direction brought in through the Microsoft acquisition.

GitHub already had a desktop app with GUI and it was only a matter of time before they came with an official command-line tool. And finally, it has happened, behold the official GitHub CLI.

Github CLI

Github CLI is the company’s official attempt at “taking GitHub to the command line” and it is currently out in beta.

Yes, it’s not completely ready but given the high interest of developers and GitHub, I would say it’s only a matter of time before it ships out of beta. Before we jump to any more conclusions, let’s go through the tool and how it can be used for everyday tasks.

Installation

The installation is very simple and straightforward.

On macOS, gh is available via brew.

brew install github/gh/gh

For Windows, gh is available via three methods. One option is via [scoop](https://scoop.sh/) using the commands:

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

It’s available through Chocolately as well, just run:

choco install gh

And finally, if you need an MSI installer file, you can go to the releases page and download the required one.

Commands

For now, GitHub has released the beta version of the CLI with two major commands, issues and pull requests, since they’re some of the most used features by developers in the open-source community.

While hub already supports more commands, hub behaves as a proxy to Git and [gh](https://github.com/cli/cli) is a standalone tool.

Needless to say, it’s official so we can expect more commands, but let’s go through the existing commands first. All the commands in the CLI start with gh.

Issue

The issue command is used to deal with everything related to issues on GitHub. It has four subcommands create, list, status, and view. The syntax is gh issue <subcommand>.

Let’s take a look at the four commands:

create — It’s very easy to create an issue from the command line. You can either use the command directly with flags for title and body like this:

gh issue create --title "Issue title" --body "Issue body"

Entering Title and Body

Or enter the details in the interactive CLI. It also provides options to directly submit an issue or open its link in the browser for you to review and submit.

Submitting an issue from the CLI and opening the link in the browser

list — The list command is used to list the issue currently present in the repository. The command is gh issue list. It also has filters based on which you can list exactly what you need based on conditions like assignee, label, current state (open, closed). You can see both examples below.

Getting the list of issues without filter

Getting the list of issues with state (closed) filter

status — This command simply shows the status of issues that are relevant to the current user. The usage is as simple as the command: gh issue status.

Getting status of relevant issues

view — This command is more like a shortcut to quickly open up an issue in the browser. You can just enter the command followed by the issue number to open it up in the browser, e.g. gh issue view 6.

PR

pr stands for pull requests and it’s the second main command available in the CLI.

It helps you work with GitHub pull requests right from the command line. It also has the four subcommands create, list, status, view, and an additional subcommand checkout. The syntax is gh pr <subcommand>.

checkout — This command is used to check out a pull request from Git. You can check out using the pull request number or URL if you have it. The usage is gh pr checkout { <number> | <url>}. It will immediately check out to a new branch from the pull request.

pr checkout

create — As the name suggests, it is used to create a pull request from the CLI. The usage is gh pr create [flags]. This command has many useful flags like title, body, branch, etc. to add details in the pr and choose the branch you want to merge with. It also allows entering info using flags like:

gh pr create --title "Pull request title" --body "Pull request body"

Or you can use the interactive CLI. It also provides options to directly submit an issue or open its links in the browser for you to review and submit.

Creating a pr from the CLI

list — This command lists the pull requests in the current repository. The command is gh pr list. It also has filters that can be added as flags based on which you can list exactly what you need based on conditions like assignee, base branch, state (open, closed) etc. You can see both examples below:

listing pull requests in a repo

status — The status command shows the status of all relevant pull requests. The usage is gh pr status. It shows this information under categories, Current branch, Created by you, and Requesting a code review from you.

Pull Request Status

view — This command is also a shortcut to quickly open up a pull request in the browser. You can just enter the command followed by the issue number to open it up in the browser, e.g. gh pr view 6. You can also use the --preview flag to see a quick preview in the browser.

Conclusion

Well, that’s all for a gist, if you need more information or want to read the detailed documentation please visit the official page. I will add more commands to the article as and when they are released.