Tutorial

Taking a Look at the GitHub CLI Tool

Published on March 6, 2020
    author

    William Le

    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!

    What Does it Do?

    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, list, view, create]
    $ gh pr [status, list, view, checkout, create]
    $ gh repo [view, create, clone, fork]
    $ gh help
    

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

    $ gh repo fork --help
    

    It should be mentioned that gh 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. 💻

    Installing GitHub CLI

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

    $ brew install 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’re ready to rock! 🤘😤

    Issues and gh

    We’ll cover a few interesting commands just to whet our appetites. Let’s use the official React.js repo as a guinea pig to execute gh commands.

    Let’s clone, and navigate to the react repo:

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

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

    # Usage:
    #   gh issue [command]
    
    # Available Commands:
    #   create      Create a new issue
    #   list        List and filter issues in this repository
    #   status      Show status of relevant issues
    #   view        View an issue in the browser
    

    Hmm, let’s view all of the issues:

    $ gh issue list
    

    You should see an output:

    terminal output

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

    $ gh issue list --help
    

    You should see this documentation:

    # Usage:                                       
    #  gh issue list [flags]                      
    
    # Flags:                                       
    #  -a, --assignee string  Filter by assignee 
    #  -l, --label strings    Filter by label   
    #  -L, --limit int        Maximum number of issues to fetch
    #  -s, --state string     Filter by state: {open|closed|all}
    

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

    $ gh issue list --assignee gaearon
    

    He has 3 issues assigned to him. It must be nice being a senior dev…

    terminal output

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

    $ gh issue view 18085
    

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

    $ gh issue view 18085 --preview
    

    terminal output

    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.

    Pull Requests and gh

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

    • Viewing current PRs
    • Reading 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):

    # Usage:
    #   gh pr [command]
    
    # Available Commands:
    #   checkout    Check out a pull request in Git
    #   create      Create a pull request
    #   list        List and filter pull requests in this repository
    #   status      Show status of relevant pull requests
    #   view        View a pull request in the browser
    

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

    $ gh pr list
    

    Outputs:

    terminal output

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

    $ gh pr view 18212 --preview
    $ gh pr checkout 18212
    

    Outputs:

    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 checkout 18212
    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!

    Repos and gh

    And briefly, let’s see what gh repo can do:

    # Usage:                                     
    #   gh repo [command]
    
    # Available Commands:
    #   clone       Clone a repository locally
    #   create      Create a new repository
    #   fork        Create a fork of a repository.
    #   view        View a repository in the browser.
    

    If you’d like to start working on a new feature (or fix bugs) for the react repo, you can simply run:

    $ gh repo fork
    

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

    Wrap Up

    The stated goal of gh 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! 💥

    Check out the documentation website for GitHub CLI 🐙🐱

    Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

    Learn more about our products

    About the authors
    Default avatar
    William Le

    author

    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.

    Still looking for an answer?

    Ask a questionSearch for more help

    Was this helpful?
     
    Leave a comment
    

    This textbox defaults to using Markdown to format your answer.

    You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

    Try DigitalOcean for free

    Click below to sign up and get $200 of credit to try our products over 60 days!

    Sign up

    Join the Tech Talk
    Success! Thank you! Please check your email for further details.

    Please complete your information!

    Become a contributor for community

    Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

    DigitalOcean Documentation

    Full documentation for every DigitalOcean product.

    Resources for startups and SMBs

    The Wave has everything you need to know about building a business, from raising funding to marketing your product.

    Get our newsletter

    Stay up to date by signing up for DigitalOcean’s Infrastructure as a Newsletter.

    New accounts only. By submitting your email you agree to our Privacy Policy

    The developer cloud

    Scale up as you grow — whether you're running one virtual machine or ten thousand.

    Get started for free

    Sign up and get $200 in credit for your first 60 days with DigitalOcean.*

    *This promotional offer applies to new accounts only.