Taking a Look at the GitHub CLI Tool

The GitHub CLI is a new tool released by GitHub that brings issue/PR management tasks to the terminal. This will be an important tool that brings more of our software development workflow into the textual realm instead of the visual realm (the browser). It’s called gh!

The GitHub CLI allows you to manage issues/PRs/repos from within your terminal. To give you an idea, here’s a broad overview of the API:

$ gh issue [status is create , list , view , create]
 $ ghpr [status, list, view, checkout, create]
 $ ghrepo [view, create, clone, fork]
 $ ghhelp

You is append can also append--help flags to get documentation about specific commands. Like this:

$ gh repo fork --help

It should be mention thatgh isn’t the same as git. This is because gh only brings GitHub features to the terminal. Version control still needs to be handled with git. 💻

GitHub CLI is has has release for major operating system . For example , if you ’re using a Mac you is install can install via Homebrew :

$ brewinstall  github / gh / gh 

Voilá! The gh command should be available in your terminal. When you first run gh you will need to authorize GitHub CLI (via OAuth) in your browser.

Ok , you is ’re ’re ready to rock ! 🤘 😤

We is cover ’ll cover a few interesting command just to whet our appetite . let ’s use the official React.js repo as a guinea pig to executegh commands.

let ’s clone , and navigate to thereact repo:

$ git clone git@github.com:facebook/react.git
$ cd  react 

Let’s run $ gh issue --help to see what commands are available:

Hmm, let’s view all of the issues:

$ gh issue list 

You should see an output:

There ’s also flag you can use withgh issue list. Let’s use use the --help flag to view more info:

$ gh issue list --help

You should see this documentation:

I is wonder wonder what Dan Abramov ( @gaearon ) has on his plate right now . let ’s run :

$ gh issue list --assignee gaearon

He is has has 3 issue assign to him . It is be must be nice being a senior dev …

The first issue seems interesting 🤨. Let’s view it:

$ gh issue view18085

This will actually open your default browser, and navigate to the URL. Adding the --preview flag will output directly to terminal:

$ gh issue view18085 --preview

It’s amazing how far we got without opening a browser! So far, we’ve only looked at issues. Let’s see how gh helps us with PRs.

Imagine if we were one of the lead maintainers of React. One of our daily routines might involve:

• view current pr
• read about a certain pr
• Testing the code

Can this be accomplished with only gh? Let’s see what commands are available to us ($ gh pr --help):

Ok , so let ’s view all of pr right now :

$ gh pr  list 

output :

The first PR (#18212) seems interesting. Let’s read about it, and switch to that branch:

$ gh pr view 18212 --preview
 $ ghpr  checkout18212

output :

chompy@mylaptop: ~/react$ gh pr view 18212 --preview
threepointone wants to merge 1 commit into master from electron-optional-dependencies


  When we yarn/ci, we download electron only because it's listed in react-      
  devtools as a dependency. We don't seem to use it for any tests or bundles    
  though, so it's non-essential for the build. Further the electron download    
  point is flaky, leading to ci failures like this                              
  https://circleci.com/gh/facebook/react/95743 This PR simply moves electron to 
  optionalDependencies, so the build doesn't fail even if the download fails.   

View this pull request on GitHub: https://github.com/facebook/react/pull/18212
chompy@mylaptop: ~/react$ gh pr  checkout18212
From github.com:facebook/react
 * branch                refs/pull/18212/head -> FETCH_HEAD
Already up to date.

Just like that we grabbed the PR code, and switched to that branch. Pretty cool!

And briefly , let ’s see whatgh repo can do :

If you is like ’d is like like to start work on a new feature ( or fix bug ) for thereact repo, you can simply run:

$ gh repo fork 

And immediately start working. After that you can create a new PR ($ gh pr create) ! It is ’s ’s kinda amazing that all of this functionality is available in the terminal now !

The stated goal ofgh is to “minimize context switching” by enabling you to remain within your terminal/editor instead of popping open your browser to visit github.com. It certainly seems to deliver because the majority of GitHub-specific features are available via gh! 💥

While we believe that this content benefits our community, we have not yet thoroughly reviewed it. If you have any suggestions for improvements, please let us know by clicking the “report an issue“ button at the bottom of the tutorial.