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.

Dive deeper into GitHub CLI in this YouTube walkthrough

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

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"

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"

Or, you can use the short form

gh issue list -a "n8ebel"

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

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"

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"

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

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

gh issue list -l "enhancement"

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"

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"

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

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"

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

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"

We could create an alias like so

alias listbugs='gh issue list --label "bug"'

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

listbugs

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"'

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

listmybugs

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

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"

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"

Or, you can use the short form

gh pr list -a "n8ebel"

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

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"

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"

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

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

gh pr list -l "enhancement"

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"

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"

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

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"

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

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"

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"

We could create an alias like so

alias listprs='gh pr list --label "bug"'

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

listprs

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

alias listmyprs='gh pr list -a "<your username>"'

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

listmyprs

FAQ

More GitHub Resources

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

• Manually Trigger A GitHub Actions Workflow
• Manually Trigger Android Build Tasks Using GitHub Actions
• Trigger A GitHub Actions Workflow Using Postman