GitHub CLI: A Guide to GitHub from the Command Line

Share this article

A Quickstart Guide to GitHub CLI

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.

Frequently Asked Questions (FAQs) about GitHub CLI

What is GitHub CLI and why should I use it?

GitHub CLI is a command-line interface that brings GitHub functionality to your terminal. It allows you to run your entire GitHub workflow from the terminal, from issues through releases, without needing to switch between different applications and websites. This can significantly streamline your workflow, especially if you’re already comfortable using the command line. It also provides more flexibility and control than the web interface.

How do I install GitHub CLI?

GitHub CLI is available for Windows, macOS, and Linux. You can download the appropriate version for your operating system from the GitHub CLI website. Once downloaded, you can install it by following the instructions provided. For most systems, this will involve running a simple install command in your terminal.

How do I authenticate with GitHub CLI?

After installing GitHub CLI, you’ll need to authenticate it with your GitHub account. You can do this by running the command ‘gh auth login’. You’ll be prompted to enter your GitHub username and password, and then to choose an authentication method. You can choose either HTTPS or SSH, depending on your preference.

How can I create a new repository using GitHub CLI?

To create a new repository with GitHub CLI, you can use the ‘gh repo create’ command. You’ll be prompted to enter a name for your new repository, and to choose whether to make it public or private. You can also choose to add a README file, a .gitignore file, and a license.

How do I clone a repository using GitHub CLI?

Cloning a repository with GitHub CLI is as simple as running the ‘gh repo clone’ command, followed by the URL of the repository you want to clone. This will create a local copy of the repository on your machine, which you can then work on.

How can I create and manage issues using GitHub CLI?

GitHub CLI allows you to create and manage issues directly from your terminal. You can create a new issue with the ‘gh issue create’ command, which will prompt you to enter a title and body for your issue. You can also list all open issues with the ‘gh issue list’ command, and view details of a specific issue with the ‘gh issue view’ command.

How do I create a pull request using GitHub CLI?

To create a pull request with GitHub CLI, you first need to push your changes to a branch on your GitHub repository. You can then run the ‘gh pr create’ command. You’ll be prompted to enter a title and body for your pull request, and to choose the branch you want to merge your changes into.

Can I use GitHub CLI to manage releases?

Yes, GitHub CLI provides commands for managing releases. You can create a new release with the ‘gh release create’ command, which will prompt you to enter a tag, a title, and a description for your release. You can also list all releases with the ‘gh release list’ command, and view details of a specific release with the ‘gh release view’ command.

How can I customize my GitHub CLI experience?

GitHub CLI provides several ways to customize your experience. You can set configuration variables with the ‘gh config set’ command, which can change the behavior of certain commands. You can also create aliases for commonly used commands with the ‘gh alias set’ command.

Where can I find more information about using GitHub CLI?

The official GitHub CLI manual is a great resource for learning more about what you can do with GitHub CLI. It provides detailed explanations of all commands, along with examples of how to use them. You can access the manual by running the ‘gh help’ command, or by visiting the GitHub CLI website.

Michael WanyoikeMichael Wanyoike
View Author

I write clean, readable and modular code. I love learning new technologies that bring efficiencies and increased productivity to my workflow.

Command lineCommand Line InterfaceCommand line toolsgithubGitHub CLI
Share this article
Read Next
Get the freshest news and resources for developers, designers and digital creators in your inbox each week
Loading form