DEV Community

goobar profile image Nate Ebel
Nate Ebel for goobar

Posted on • Originally published at goobar.io on

GitHub CLI – GitHub From The Command Line

#github #programming #versioncontrol #tips

GitHub recently announced GitHub CLI; a first-party command line tool for interfacing with GitHub from the command line.

With GitHub CLI, developers can check the status of GitHub issues and pull requests, search for a specific issue or PR, create/fork a repo, or create new issues and pull requests right from the command line.

In this post, we’ll walk through some common daily developer workflows. As we do, we’ll focus in on how we might manage our issues and pull requests using GitHub CLI.

What Is GitHub CLI?

So we’re all on the same page, we’ll start with a short overview of GitHub CLI. If you’re already familiar with it, jump ahead to the next section.

GitHub CLI is best described as “GitHub from the command line.”

Currently, GitHub CLI is at version v0.6.3 and consists of a focused set of functionality around three GitHub artifacts:

  • Issues
  • Pull Requests
  • Repositories

With GitHub CLI, developers can perform the following commands in relation to this different artifacts:

  • create
  • list
  • status
  • view
  • checkout (pull requests only)
  • clone (repo only)
  • fork (repo only)

As mentioned previously, in this post, we’re only going to focus on commands related to issues and pull requests.

How to Install GitHub CLI?

To install GitHub CLI on your development machine, check out the installation guide found on GitHub. You can also follow along with the tutorial on my YouTube channel.

GitHub CLI is available across MacOS, Windows, and various Linux distros, so you shouldn’t have a problem getting the tool up and running on your machine.

Using GitHub CLI To Manage GitHub Issues

If working with GitHub Issues is a regular part of your development flows then GitHub CLI likely has several helpful commands for you. Let’s walk through what a typical work day might look like and highlight some examples of using GitHub CLI to work with issues on GitHub.

List Issues With GitHub CLI

Let’s imagine we are just sitting down at our computer for the day, and we want to list out the open GitHub Issues for our project.

gh issue list
Enter fullscreen mode Exit fullscreen mode

If we want to list out ALL of the issues we could use the “state” flag

gh issue list --state "all"gh issue list -s "all"
Enter fullscreen mode Exit fullscreen mode

Now, maybe we’ve realized that is too many issues to sort through, so we decide we only want to list out your currently assigned issues.

gh issue list --assignee "n8ebel"
Enter fullscreen mode Exit fullscreen mode

Or, you can use the short form

gh issue list -a "n8ebel"
Enter fullscreen mode Exit fullscreen mode

Check Issue Status With GitHub CLI

Next, we want to check in on the status of a couple of the issues we created yesterday. Maybe we don’t remember their exact numbers, but since we created them, we can use the status command to list them at the terminal

gh issue status
Enter fullscreen mode Exit fullscreen mode

This will give us a list of issues that are assigned to us, mentioning us, or that were opened by us.

After checking in on these issues, we still can’t find the issue we’re looking for, so we might want to check whether it was closed or not.

gh issue list --state "closed"gh issue list -s "closed"
Enter fullscreen mode Exit fullscreen mode

That’s great! Our issue has been closed, so now we’re ready to find our next task. We could start looking for new tasks by listing out issuses filtered by different labels.

To list out all of our open bugs, we could filter by the “bug” label defined in our GitHub repo

gh issue list --label "bug"gh issue list -l "bug"
Enter fullscreen mode Exit fullscreen mode

If you’re unsure of what labels are available for the open issues, you could first check by listing all the open issues again

gh issue list
Enter fullscreen mode Exit fullscreen mode

Now, we can see there is also an enhancement label we can search for

gh issue list -l "enhancement"
Enter fullscreen mode Exit fullscreen mode

View Issues With GitHub CLI

Once we’ve found an issue we want to fix, we might want to assign that issue to ourselves. Currently, we can’t do that directly from the command line, but we can quickly open the issue from the command line using the “view” command.

gh issue view "15"
Enter fullscreen mode Exit fullscreen mode

This will open the issue in a web browser where you can then assign it to yourself.

After assigning any issues to yourself, you can double check your assignments from the command line by listing out open bugs assigned to you.

gh issue list -a "n8bel" -l "bug"
Enter fullscreen mode Exit fullscreen mode

Create Issues With GitHub CLI

Now, we just have one last command to explore.

As we’re working on our assigned issues, imagine we find an additional bug we need to report.

We can use the gh issue create command to create a new GitHub Issue directly from the command line.

gh issue create
Enter fullscreen mode Exit fullscreen mode

Using this command as is will kick off an interactive terminal workflow to select any available GitHub Issue template, and then fill in the title and issue description. You’ll finally then have the option to submit the issue, open it the browser, or cancel.

If you’d like to simplify things a bit, you can specify the issue with the command using additional flags

 gh issue create -t "Sample Issue Title" -b "Sample issue description"
Enter fullscreen mode Exit fullscreen mode

If you still prefer to create your issue from the web, you could use the following command to open up a browser window and jump right into the issue creation workflow in your repo

gh issue create --web
Enter fullscreen mode Exit fullscreen mode

Helpful GitHub CLI Aliases

So with these various command and flag variation, we have quite a few options for creating, listing, and viewing our GitHub Issues.

We can make these commands even easier to work with by creating some command line aliases for them.

For example, when listing out all bugs, instead of using this full command

gh issue list --label "bug"
Enter fullscreen mode Exit fullscreen mode

We could create an alias like so

alias listbugs='gh issue list --label "bug"'
Enter fullscreen mode Exit fullscreen mode

That way, when we want to list all bugs we can simply type:

listbugs
Enter fullscreen mode Exit fullscreen mode

Another example would be to use the following alias to list all bugs assigned to you.

alias listmybugs='gh issue list -a "<your username>" -l "bug"'
Enter fullscreen mode Exit fullscreen mode

With this alias in place, we can search for all bugs assigned to you like this:

listmybugs
Enter fullscreen mode Exit fullscreen mode

Managing Pull Requests With GitHub CLI

Now, let’s explore the use of GitHub CLI for managing pull requests. Again, let’s walk through an imaginary workday and see where this tool make help us.

List Pull Requests

Once again, we sit down at our computer for the day, and we want to list the open pull requests for our project.

gh pr list
Enter fullscreen mode Exit fullscreen mode

If we want to list out ALL of the pull requests, both open and closed, we could use the “state” flag

gh pr list --state "all"gh pr list -s "all"
Enter fullscreen mode Exit fullscreen mode

Now, maybe we’ve realized that is too many PRs to sort through, so we decide we only want to list out your currently assigned issues.

gh pr list --assignee "n8ebel"
Enter fullscreen mode Exit fullscreen mode

Or, you can use the short form

gh pr list -a "n8ebel"
Enter fullscreen mode Exit fullscreen mode

Check Pull Request Status

Next, we want to check in on the status of a couple of the PRs we created yesterday. Maybe we don’t remember their exact numbers, but since we created them, we can use the status command to list them at the terminal

gh pr status
Enter fullscreen mode Exit fullscreen mode

This will give us a list of PRs that are assigned to us, mentioning us, or that were opened by us.

After checking in on these PRs, we still can’t find the pull request we’re looking for, so we might want to check whether it was closed or not.

gh pr list --state "closed"gh pr list -s "closed"
Enter fullscreen mode Exit fullscreen mode

That’s great! Our PR has been closed, so now we’re ready to find our next task. We could start looking for new tasks by listing out pull requests filtered by different labels.

To list out all of our open bug fix PRs, we could filter by the “bug” label defined in our GitHub repo

gh pr list --label "bug"gh pr list -l "bug"
Enter fullscreen mode Exit fullscreen mode

If you’re unsure of what labels are available for the open issues, you could first check by listing all the open PRs again

gh pr list
Enter fullscreen mode Exit fullscreen mode

Now, we can see there is also an enhancement label we can search for

gh pr list -l "enhancement"
Enter fullscreen mode Exit fullscreen mode

View Pull Request

Once we’ve found a PR we want to review, we might want to assign that PR to ourself. Currently, we can’t do that directly from the command line, but we can quickly open the PR from the command line using the view command.

gh pr view "14"
Enter fullscreen mode Exit fullscreen mode

This will open the pull request in a web browser where you can then assign it to yourself, review it, etc.

You can double check your assigned pull requests from the command line by listing out PRs assigned to you.

gh pr list -a "n8bel" -l "bug"
Enter fullscreen mode Exit fullscreen mode

Create Pull Request

As we’re working on our assigned issue, at some point, we’re going to want to create a new pull request based on our local changes.

We can use the gh pr create command to create a new pull request directly from the command line.

gh pr create
Enter fullscreen mode Exit fullscreen mode

Using this command as is will kick off an interactive terminal workflow to fill in the title and issue description. You’ll finally then have the option to submit the PR, open it the browser, or cancel.

If you’d like to simpify things a bit, you can specificy the PR info with the command using additional flags

gh pr create -t "Sample Issue Title" -b "Sample issue description"
Enter fullscreen mode Exit fullscreen mode

If you still prefer to create your PR from the web, you could use the following command to open up a browser window and jump right into the PR creation workflow in your repo

gh pr create --web
Enter fullscreen mode Exit fullscreen mode

At some point, we’re going to want to test a PR locally. This generaly requires looking up the PR, checking the branch it’s on, then checking it out locally.

Using GitHub CLI we can streamline this process using the pr checkout command

gh pr checkout "14"
Enter fullscreen mode Exit fullscreen mode

This will checkout the branch associated with PR 14 so you’re ready to start testing.So with these various command and flag variation, we have quite a few options for creating, listing, and viewing our GitHub pull requests.

We can make these commands even easier to work with by creating some command line aliases for them.

For example, when listing out all PRs, instead of using this full command

gh pr list --label "bug"
Enter fullscreen mode Exit fullscreen mode

We could create an alias like so

alias listprs='gh pr list --label "bug"'
Enter fullscreen mode Exit fullscreen mode

That way, when we want to list all bug related PRs we can simply type

listprs
Enter fullscreen mode Exit fullscreen mode

Another example would be to use the following alias to list all PRs assigned to you

alias listmyprs='gh pr list -a "<your username>"'
Enter fullscreen mode Exit fullscreen mode

With this alias in place, we can search for all PRs assigned to you like so

listmyprs
Enter fullscreen mode Exit fullscreen mode

More GitHub Resources

Check out the follow articles for more ways to leverage GitHub in your development workflows.

Subscribe for more software development posts, videos, and resources

The post GitHub CLI – GitHub From The Command Line appeared first on goobar.io.

Top comments (0)

Read next

anogneva profile image

Code of game engine written in Java: what does it hide?

Anastasiia Ogneva -

zhukmax profile image

Empowering Web Privacy with Rust: Building a Decentralized Identity Management System

Max Zhuk -

rym_michaut profile image

11 Python Newsletters You Need to Subscribe to in 2024

Rym -

shaharke profile image

Schema Extension and Reuse

Shahar Kedar -