PathPath
Cute octopus put together model airplain with glue

Building Custom GitHub CLI Commands

Updated:

When I first started learning the GitHub CLI, I found that creating some commands was straightforward, while others required a bit of trial and error. Let’s walk through a few examples to help make your future workflow hacking easier. In the previous lesson, we discussed command building basics and in this lesson we’ll add onto those skills.

Creating a New PR

Scenario: You’ve made code changes and committed them on a feature branch. Now, you’re ready to create a new PR.

A good first step is to identify the top-level command that aligns with your task. In this case, gh pr seems promising for working with pull requests. Delving deeper, we find the create subcommand, offering ample configurability.

Try:

Start with gh pr create. You’ll encounter an interactive shell UI that asks a few questions:

First, select the repository. Simply hit Enter on your desired option. Entering gh pr in the terminal

Next, you’ll be prompted to provide a title for your PR. Interactive UI for creating a PR title

After entering the title, you’re given the option to write a description. Pressing the “e” key opens your editor to write the PR description. Alternatively, hitting Enter skips this step and moves directly to pushing the PR.

Interactive UI for creating a PR description

As shown below, I have my editor set up to open a new document in VS Code. Editing, saving, and closing this document will save your draft. Don’t worry if yours doesn’t look like mine; I’ll cover more on this later.

Using code --wait as a PR editing tool.

After closing the temporary document, the terminal will display the “What’s Next” section. Here, you can finalize your PR, such as submitting it as a draft.

Submitting your PR as a draft interactive UI

You’ll then see a confirmation with details about your newly created draft PR.

Confirmation displayed once the PR has been submitted

We can further interact with the PR using the gh pr view command, adding the PR number.

  • View PR in the terminal: gh pr view 73
  • View PR in the default web browser (using the -w flag): gh pr view 73 -w

Try experimenting with additional flags As shown in the Aliases chapter, we can further refine the command by taking advantage of the flags shown within the documentation, for example pr create --draft --assignee @me.

Searching an External Repo with the GitHub CLI

Next, let’s explore a more advanced command that involves using variables and searching GitHub for a specific repo with additional filters.

Scenario: We’ll search the GitHub CLI repo for open issues containing the phrase “auth token” and tagged with the “help wanted” label.

When uncertain about how to execute a specific task in the GitHub CLI, the website can be a useful resource for visualizing ideas.

Below is an image showing the filtered search based on our scenario.

Using the filtered search within the browser to visualize what the command should do

Try:

Let’s break down the process to put together an initial command.

  1. To retrieve all issues in cli/cli, we need to narrow down the owner and repository. Note: You can find the owner and repository identifiers in the GitHub URL, like github.com/owner/repo.
  2. According to the documentation on searching issues, we can use --owner=cli and --repo=cli flags to specify our search.
  3. Our initial command is gh search --owner=cli --repo=cli.

Initial run of gh search issues command showing 3906 results

Now, let’s refine the search with additional flags from the documentation.

First, we’ll add the “help wanted” label using --label. Since the label consists of two words, we enclose it in quotes: --label="help wanted". The command gh search issues --owner=cli --repo=cli --label="help wanted" gives us a more focused list of issues.

Refined search results using help wanted label flag

Lastly, let’s refine this one more time by adding our phrase into the search. According to the documentation, our structure should look like this gh search issues [<query>] [flags]. So let’s try it out gh search issues auth token --owner=cli --repo=cli --label="help wanted"

Finally, let’s refine the search further by including the phrase “auth token”. Based on the documentation, our command format is gh search issues [<query>] [flags]. Let’s try gh search issues auth token --owner=cli --repo=cli --label="help wanted".

Running the full command to see an accurate listing of issues that match our search criteria

In this guide, we explored practical applications of the GitHub CLI, focusing on creating a new Pull Request (PR) and searching within an external repository. Now, we’re ready to examine how we can store commands for reuse using aliases.

Micheal England

Article by Micheal England.

Looking for My Next Role


Seeking a skilled JS, Node, or React developer? Connect with me on LinkedIn. Let's discuss how I can contribute to your team's success!
Connect