Exploring the New GitHub CLI

Github just released it’s own Command-Line Interface (CLI) so developers can now do everyday GitHub tasks from the terminal. Yay! This means no more squiggling around the UI. With this new CLI, you can now view, create, clone, or fork repositories, create, view, and edit gists, you can also work with pull requests and issues right from the terminal.

Isn’t that awesome?

The motive behind this CLI is to move all of the developer workflow right to the terminal where we were already working with git. Now you might ask, will it replace the git CLI? The answer is no. The CLI is meant to integrate well with git, which means your trusty old git isn’t going anywhere. Rather this was one of the motives behind the creation of the GitHub CLI, bringing all your tools to one place to avoid context switching.

But wait! doesn’t something like this already exists? Yes, yes it does. A GitHub wrapper called hub which is an open-source extension to command-line git, maintained by a GitHub employee, that lets you do everyday GitHub tasks without ever leaving the terminal. Sounds pretty familiar eh? Hub already offers a lot of the things that the Github CLI brings to the table.

So why is GitHub Reinventing the Wheel?

The GitHub team mentions that the primary reason they didn’t build on top of hub was that they didn’t want to wrestle with the 10 odd years of design decisions that hub went through which weren’t really focused on GitHub workflows. They also didn’t want to change hub significantly because that might upset the already established user base which used hub on a daily basis. They addressed this in a lot more detail in their docs.

So enough talk, let’s see how it actually works. By the end of this article, you should be well on your way to integrating the GitHub CLI in your workflow.

Installation

The first step is installing the CLI. To do that simply follow the install instructions for your operating system given on their official page.

Setting Up

After installing, the next thing that you have to do is authenticate your Github account. Do that by entering the following command:

gh auth login

You’ll be asked to select the type of account that you want to login with, select accordingly. After that, you will be given a secret code that you’ll need to enter in the prompted browser window.

Successful login should look something like this:

If you need to refresh your credentials anytime, you can do it by:

gh auth refresh

Check your authentication by:

gh auth status

Set Your Editor

You can set your editor of choice to open files for cases when gh will prompt you to edit a file. Set it by entering:

gh config set editor editorName

Replace editorName with the name of your editor like emacs, vim, nano etc.

Get Tab Completions For gh Commands

You might have noticed that your usual tab completions don’t work, to get it to work, paste the following code in your ~/.bash_profile:

eval "$(gh completion -s bash)"

Reload your terminal and boom! you can tab-complete now.

Repositories

Now let’s learn creating, forking, cloning, and viewing repositories.

Creating repositories

There are various ways of creating a repository using gh.

Make sure you are logged in and are navigated into the projects directory, then enter:

gh repo create

This will create a repository with the name of your directory under your account.

1. With a specific name:

gh repo repoName

replace repoName with the name that you want to give to your repository.

2. Under an organization:

gh repo create orgName/repoName

Replace orgName with the name of your organization and repoName with the name of the repository as usual.

Set Flags For Additional Options

You can also set flags in the command to give additional features to your repository like making it public or private.

Here is a list of all the flags that you can give to your repo:

-y, --confirm              Confirm the submission
  -d, --description "string"   Description of your repo
      --enable-issues        Allow people to add issues(default value is true)
      --enable-wiki          Enable wiki in the new repository (default true)
  -h, --homepage "string"      Repository home page URL
      --internal             Make the repository internal
      --private              Make the repository private
      --public               Make the repository public
  -t, --team "string"          The name of the organization team to be granted access
  -p, --template "string"      Make the new repository based on a template repository

So for example if I want to create a repository with the name of Python under the organization Monty and I want to set it to private with issues disabled, I would enter:

gh repo create Monty/Python --private --enable-issues=false

As simple as that.

Cloning Repositories

You can clone repositories more simply in gh by using its unique owner/repo syntax:

gh repo clone owner/repo

Replace owner with the account name of the owner and repo with the repository name.

You can also clone repositories using Github URLs like before:

gh repo clone <code class="markup--code markup--pre-code"><a href="https://github.com/cli/cli" data-href="https://github.com/cli/cli" class="markup--anchor markup--pre-anchor" rel="noopener" target="_blank">https://github.com/cli/cli</a></code>

Forking Repositories

You can fork repositories in 3 ways:

1. Without Giving Arguments:

gh repo fork

This will create a fork of the repository that you are currently navigated into on your Github account.

2. Giving Arguments:

gh repo fork user/repo

Replace user with the username and repo with the repo name.

3. With Flags:

You can provide flags like ‘ — remote’ and ‘ — clone’ to skip prompts. The flags take a value either true or false.

gh repo fork user/repo --clone=true --remote=true

This will also clone the forked repository and also set an upstream remote, all in one line.

Viewing Repositories

Now let’s talk about viewing repositories. You can view the description and README of any Github repository right in your terminal:

gh repo view user/repo

This will look something like this:

Pretty neat!

You can also choose to view the repo in your browser by providing the ‘ — web’ or the ‘ -w’ flag.

gh repo view user/repo --web

Providing no arguments will open the repo that you are currently in:

gh repo view

Gists

We can view, list, create, and edit gists.

Creating Gists

To create a gist write:

gh gist create --public example.cpp

The public flag will make the gist public. Keep in mind that the default value is private so in the absence of a flag, your gist will be private.

To give a description to the gist use the -d flag:

gh gist create --public example.cpp -d "An example program in c++"

Add multiple files in your gist by separating them with a whitespace:

gh gist create example.cpp app.js hello.py

You can also write a gist in the terminal by using a hyphen (-) in place of the file name:

gh gist create -

Listing your Gists

To view all your gists enter:

gh gist list

You can also give flags like “ — public” or “ — secret” to list only your public gists or secret gists.

Editing Gists

You can edit gists using the command:

gh gist edit gistID

or alternatively

gh gist edit gistURL

Needless to say, in the above commands replace ‘gistID’ with your, well… gist ID and “gistURL” with the URL of your gist.

You can get your gist id by first listing the gist by:

gh gist list

And then copying the 32 character code displayed there or you can copy the code from the URL of your gist, it would be the last part of your URL.

But here’s something tricky...

although I recommend using gistID because of its simplicity, if you plan to use the gist URL, simply copying and pasting the URL of your gist won’t work, it will give you a 404 something like this:

Four Oh Four

To make it work you need to remove your username from the URL and then run the command.

If done correctly, your gist should be opened in the editor that you set earlier.

Viewing a gist

You can view a gist using:

gh gist view gistID

or

gh gist view gistURL

If you want to view it raw without rendering markdown put the “ — raw” flag at the end. View the gist in a browser by the “ — web” flag.

Pull Requests

Now we are going to tackle working with pull requests using gh. Make sure that you are navigated into the project directory.

Note: As a general rule of thumb use the flag “-R owner/repo” or “ — repo owner/repo” with all of the commands below if you want to select a repository other than the one that you are navigated into. 

Listing Pull Requests

You can list pull requests on a project by using:

gh pr list

This will list all your open pull requests.

If you want to list the closed or merged pull requests, you can do so by adding the ‘ — state “string”’ flag as shown below:

gh pr list --state closed

To see all of the pull requests give the argument ‘all’ to the ‘state’ flag:

gh pr list --state all

Here are some very useful flags that you can use with this command:

<code class="markup--code markup--pre-code">-a, --assignee string     Show all pull requests by an assignee<br>  -B, --base string       Filter by base branch<br>  -l, --label strings     Filter by labels<br>  -L, --limit int         Maximum number of items to fetch (default 30<br>  -s, --state string      Filter by state: {open|closed|merged|all} (default "open")<br>  -w, --web               Open the browser to list the pull requests</code>

Viewing Pull Requests

Quickly view a pull request’s information:

gh pr view

Using this without any arguments will display the pull requests on the current branch that you are navigated into. Use git checkout first to checkout to a branch name and view its pull request.

You can give the pull request number or a URL or a branch to view a specific pull request:

gh pr view 5

gh pr view master

gh pr view urlOfPullRequest

Creating a Pull Request

To create a pull request on a repository enter:

gh pr create

Make sure that you are in the project directory and are navigated to the branch that you want to push to the origin master.

The above command will display some prompts asking you to specify the title and body of your pull request. If the branch isn’t pushed to a git remote or some files in the branch haven’t been pushed then you will be prompted to enter the location where you want the branch to be pushed, gh will also give you an option to fork the base repository.

If you don’t want to create a pull request interactively then you can give flags with the command to provide the information there:

gh pr create --title "Bumped to 2.0" --body "Updated the version"

Assign the pull request to someone:

gh pr create --assignee username

Request a pr review from someone:

gh pr create --reviewer username

Select a branch in which you want your code to be merged:

gh pr create --base branchName

Here are all of the flags that you can use while creating a pull request:

-a, --assignee login   Assign people by their login
  -b, --body string      Body for the pull request
  -d, --draft            Mark pull request as a draft
  -f, --fill             Skip the prompt for title/body and use commit info
  -H, --head branch      The branch that contains commits for your pull request (default: current branch)
  -l, --label name       Add labels by name
  -m, --milestone name   Add the pull request to a milestone by name  -p, --project name     Add the pull request to projects by name
-t, --title string     Give the pull request a title.
  -w, --web              Create the pr in a web browser

Checking Out Pull Requests

If you want to test a pull request to make sure that it works fine and doesn’t break anything before merging it into master you can do it easily using this command:

gh pr checkout prURL or branch or prNumber

You can either provide the URL of the pull request or the number of the pull request or the branch.

This will navigate you to the branch of the pull request with all the files loaded in your working directory and ready to go. From here you can test to your heart’s content. You can do a quick ‘ls’ command to view the contents of the pull request.

To go back to the master branch simply use git checkout.

git checkout master

You can choose to merge or close the pull request from there.

Merging a Pull Request

If you want to merge the pull request after testing it then you can use:

gh pr merge prNumber or prURL or branch

This will merge the pull request into the origin master branch, and will by default delete the head branch of the pull request from both the local and the remote repositories. If you want to retain the branch use:

gh pr merge prNumber --delete-branch=false

Here are some more flags that you can use with pr merge:

-m, --merge           Merge the commits with the base branch
  -r, --rebase          Rebase the commits onto the base branch
  -s, --squash          Squash the commits into one commit and merge it into the base branch

Closing a Pull Request

If you want to close a pull request you can use:

gh pr close prNumber or prURL or branchName

If you want to delete the branch of the pull request from the local and the remote repository then use the “ — delete-branch” flag.

Viewing Changes in a Pull Request

You can view the changes proposed by the pull request by:

gh pr diff prNumber or prURL or branchName

Check the Status of a Pull Request

Check the status of the pull requests in your current branch:

gh pr status

This command will also show you the status of your open pull requests created by you and also the status of the pull requests that you have to review.

Something like this:

Mark a pull request ready for review

gh pr ready prURL or prNumber of branch

Reopen a closed pull request

gh pr reopen prNumber or prURL or branch

Review a pull request

gh pr review prNumber or prURL or branch

The flags here are:

-a, --approve           Approve the pull request
  -b, --body string       Specify the body of a review
  -c, --comment           Comment on a pull request
  -r, --request-changes   Request changes on a pull request

Issues

The last thing in this tutorial that we are going to learn is working with issues.

Listing the Issues

gh issue list    //list all issues

You can put flags to filter the results.

-a, --assignee string    Filter by assignee
  -A, --author string      Filter by author
  -l, --label strings      Filter by labels
  -L, --limit int          Maximum number of issues to fetch (default 30)
      --mention string     Filter by mention
  -m, --milestone number   Filter by milestone number or `title`
  -s, --state string       Filter by state: {open|closed|all} (default "open")
  -w, --web                Open the browser to list the issue(s)

Viewing an issue

gh issue view issueNumber or issueURL

Creating an issue

To create an issue interactively with prompts use:

gh issue create

To skip the prompts you can use the following flags

-a, --assignee login   Assign people by their login
  -b, --body "string"      Add the body of the issue
  -l, --label name       Add labels by name
  -m, --milestone name   Add the issue to a milestone by name
  -p, --project name     Add the issue to projects by name
  -t, --title "string"     Supply a title.
  -w, --web              Create an issue in the browser

View the Status of Issues in a Repository

gh issue status

Closing and Reopening an issue

gh issue close issueNumber or issueURL

gh issue reopen issueNumber or issueURL

Getting Help

If you forget any command or its flags or if you want to consult the documentation quickly then you can always use the “ — help” flag to view the documentation of the command in the terminal itself.

Conclusion

I found the CLI to be intuitive and quite easy to use, I guess its time to say goodbye to the UI for good. By now you should be ready to integrate the Github CLI into your day-to-day workflow and perform all of your UI actions in the terminal. I have tried my best to cover all of the use cases that one might run into but still if you have any questions feel free to hit me up. Wish you a happy and productive coding journey :)

Link to the official CLI manual.

Fork me on Github :)️