Programming

GitHub CLI: A Guide to GitHub from the Command Line

    Michael Wanyoike
    Share

    In this quickstart guide, you’ll learn GitHub CLI. Find out what the GitHub CLI tool is used for, how to set it up, and how to use it.

    If you’re already familiar with Git commands, you’re obviously aware that you need to switch to the web browser in order to perform various actions on your GitHub repository. With the new GitHub CLI tool, you can execute many of these actions without leaving the command-line interface.

    GitHub CLI Setup

    To get started, simply visit the installation page and find instructions on how to install GitHub CLI for your operating system. For Windows and macOS, you can use package managers to install and keep GitHub CLI up to date. For Linux users, you’ll need to download the package from the latest release page. There are Signed MSI installers for Windows users too, but be aware you have to re-download and update the tool manually if you opt for this. The easiest way for Windows users is to use the scoop package manager.

    Below are snapshots of install instructions for each supported platform:

    • Windows:

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

    • macOS:

      brew install github

    • Debian/Ubuntu Linux:

      sudo apt install git && sudo dpkg -i gh_*_linux_amd64.deb

    • Fedora/Centos Linux:

      sudo yum localinstall gh_*_linux_amd64.rpm

    • Arch Linux:

      yay -S github-cli

    On Windows, I would recommend the use of the Git Bash terminal. This interface will allow you to access common Linux commands and Bash features such as autocompletion. It’s also officially supported by Visual Studio Code via terminal integration.

    After installing GitHub CLI, you’ll need to authenticate your account. Running any command will trigger this authentication process. For example, try gh repo view cli/cli. For first-time users, you’ll be prompted with the following:

    GitHub authentication

    Simply press the Enter key to start the process as illustrated below:

    Gitub authorization

    Once you provide your password, you’ll get a “Successfully authenticated GitHub CLI” message. You’re now able to interact with the GitHub platform via the command-line terminal. The next step is to implement autocomplete, which is optional. Simply add this line to your ~/.bash_profile:

    eval "$(gh completion -s bash)"

    You can also run the above command in your current terminal to get the autocomplete feature without restarting your terminal. To confirm it’s working, type gh repo, then press tab twice. It should show you four different commands you can append to the current repo command.

    GitHub CLI Command Structure

    The gh command structure is tree-like and easy to remember. There are basically two levels of commands. The first level only consists of six commands:

    • config
    • repo
    • issue
    • pr
    • gist
    • credits

    Each command has a second level of command where you can specify the operation you want to perform — such as gh repo view or gh pr list. The credits command has no second-level command, though. When executed, it simply lists the names of a repository’s contributors. Here’s a quick example you can try out yourself:

    $ gh credits cli/cli

    We’ll look at the rest of the commands in more detail in the upcoming sections.

    GitHub Repository Commands

    Cloning a repo with the gh command is easier than using the git command. To clone, all you have to do is execute the command in the following format:

    gh repo clone OWNER/REPO

    This format makes it easier to clone from memory. You no longer need to type or copy-paste the long Git URL to clone. Below is an example:

    $ gh repo clone tailwindcss/tailwindcss

    You can also fork existing repositories to your account easily from the command line. Try:

    $ gh repo fork cli/cli

    During the forking process, the tool will ask you if you want to clone as well. If you say “yes”, it will do the cloning, set up the remote upstream branch and perform an update for you automatically. That’s pretty convenient. You can confirm this by checking the repository’s config via your command line: git config -e. Below is how my output looks:

    [core]
    repositoryformatversion = 0
    filemode = false
    bare = false
    logallrefupdates = true
    symlinks = false
    ignorecase = true
[remote "origin"]
    url = https://github.com/brandiqa/cli.git
    fetch = +refs/heads/*:refs/remotes/origin/*
[branch "trunk"]
    remote = origin
    merge = refs/heads/trunk
[remote "upstream"]
    url = https://github.com/cli/cli.git
    fetch = +refs/heads/*:refs/remotes/upstream/*

    For this project, trunk is the default branch. You’ll need to use the git command to sync your forked repo as usual. In the case of the cli repo:

    # Make sure you’re in the default branch
$ git checkout trunk

# Fetch updates
$ git fetch upstream

# Merge
$ git merge upstream/trunk

# Update your remote repo
$ git push

    You can also view the description and README of a project hosted on GitHub using the gh repo view command. Try this command:

    $ gh repo view facebook/react

    So far, you’ve learned how you can clone, fork and view using the gh repo commands. Let’s create a new GitHub repository from the command line. First, we need to create a new project. Let’s quickly generate a Next.js project. When asked, use the “default starter app” template:

    $ npx create-next-app example-next
...
# navigate to project folder after creation process is completed
$ cd example-next

    You’ll find that the local Git repo for the project has already been initialized. To create a repo from the command line, just run the following:

    $ gh repo create --public
✓ Created repository brandiqa/example-next on GitHub
✓ Added remote https://github.com/brandiqa/example-next.git

# Push your project code to your new remote repository
$ git push -u origin master

    If you don’t specify the --public option, a private repository will be created by default. Here’s a full list of flags you can specify:

     -d, --description string    Description of repository
      --enable-issues        Enable issues in the new repository (default true)
      --enable-wiki          Enable wiki in the new repository (default true)
  -h, --homepage string      Repository home page URL
      --public               Make the new repository public (default: private)
  -t, --team string          The name of the organization team to be granted access

    If you’d like to create the repo under a different organization, you’ll need to use the following to create the repo syntax: gh repo create org/repo.

    Pull Request Commands

    Creating a pull request (PR) for your team to review can now be done on the terminal. Right after you’ve committed a feature or bug branch, you can do execute gh pr create. This will create the pull request interactively:

    Creating a pull request

    Here’s the full output:

    $ gh pr create
Creating pull request for feature-1 into master in brandiqa/example-next
? Title Updated Home Page Title
? Body <Received>
? What is  next? Submit
Enumerating objects: 7, done.
Counting objects: 100% (7/7), done.
Delta compression using up to 8 threads
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 398 bytes | 398.00 KiB/s, done.
Total 4 (delta 2), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (2/2), completed with 2 local objects.
remote:
remote: Create a pull request for 'feature-1' on GitHub by visiting:
remote:      https://github.com/brandiqa/example-next/pull/new/feature-1
remote:
To https://github.com/brandiqa/example-next.git
* [new branch]      HEAD -> feature-1
Branch 'feature-1' set up to track
remote branch 'feature-1' from 'origin'.
https://github.com/brandiqa/example-next/pull/1

    You can also run the create command with flags like this:

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

    To confirm the pull request has been created on GitHub platform, you can execute the command gh pr list to list all pull requests. Below is the output:

    $ gh pr list
Showing 1 of 1 pull request in brandiqa/example-next
#1  Updated Home Page Title  feature-1

    For a more active project such as TailwindCSS, you’ll get a longer list of active PRs:

    PR list

    The columns as shown above are:

    • PR number
    • PR description
    • PR branch

    You can use the command gh pr checkout <number> to checkout a pull request. This command will pull the remote feature branch and switch to it. While there, you can also do a gh pr diff to view what’s changed:

    checkout diff

    Let’s take a look at the gh pr merge command. As you’re probably aware, GitHub checks for vulnerabilities in your code and provides solutions via bump pull requests. Here’s an example:

    GitHub security bumps

    Merging these PRs one by one might be cumbersome for you, especially on a slow internet connection. However, you can hasten the process using the terminal via the gh pr merge command. Below is a screenshot of the command in action:

    pr merge

    After doing a merge, it’s best to do a pull right after. If you want to do all that in a single step without running the command interactively, you can use flags:

    gh pr merge -m -d &lt;number&gt; &amp;&amp; git pull

    There are other highly useful gh pr commands we won’t cover here, but I’ll mention them quickly:

    Issue Commands

    Issues are how we keep track of bugs, tasks and feature requests on a GitHub project repository. We can use the command gh issue create to create a new issue via the terminal:

    Creating an issue

    There’s also gh issue list command that lists all issues. Below is an example screenshot of the command in use:

    GitHub issue list

    The rest of the gh issue commands are quite similar to gh pr commands. Below is a quick summary:

    Gist Commands

    Creating a gist on GitHub can now easily be done via the console terminal using the command gh gist create <file>. Here’s an example of the command with the --public flag option:

    Creating a gist

    By default, a private gist will be created if you don’t specify the --public flag. Here is a link to the gist I just created. It contains a list of common Linux command aliases that I use on a regular basis.

    There are no other gist commands, but there’s one more flag I haven’t mentioned:

    • -d, --desc string: a description for this gist.

    GitHub CLI Summary

    I hope you’ve learned how to use the new gh command-line tool. I would recommend you integrate the tool into your workflow and make it a habit, as it clearly does save some time managing your repository. Please do note that the tool is still under development and new commands may appear after this article has been published. You can refer to the manual for new features and information on using the existing tools.

    The one command I haven’t covered is gh config. That’s because there’s not much documentation about using it at the time of writing. Keep an eye on the manual and the release page for the latest updates.