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:
scoop bucket add github-gh https://github.com/cli/scoop-gh.git scoop install gh
brew install github
sudo apt install git && sudo dpkg -i gh_*_linux_amd64.deb
sudo yum localinstall gh_*_linux_amd64.rpm
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:
Simply press the Enter key to start the process as illustrated below:
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
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
GitHub CLI Command Structure
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:
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
# 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
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:
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:
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:
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:
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:
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 <number> && git pull
There are other highly useful
gh pr commands we won’t cover here, but I’ll mention them quickly:
gh pr view: display the title, body, and other information about a pull request.
gh pr status: show status of relevant pull requests.
gh pr ready: make a pull request as ready for review.
gh pr review: add a review to a pull request.
gh pr close: close a pull request.
gh pr reopen: reopen a pull request.
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:
gh issue list command that lists all issues. Below is an example screenshot of the command in use:
The rest of the
gh issue commands are quite similar to
gh pr commands. Below is a quick summary:
gh issue view: display the title, body, and other information about an issue.
gh issue status: show status of relevant issues.
gh issue close: close an issue.
gh issue reopen: reopen an issue.
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:
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:
--descstring: 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.