How the Github CLI Saves Me Time Every Day

What if I told you it's possible to manage your GitHub repository within the CLI? No more pointing and clicking on a user interface, just commands. That would mean faster work with less context-switching, right? Brace yourself. GitHub's official command line is right here for you.

Triaging issues, creating or checking out pull requests, releasing packages, forking repos, even creating gists can now be done from your terminal. And we all know its power and how fast it can be. Using GitHub CLI has been a real win for my workflow. Want to learn more? It all happens down here. 👇

Getting started

First things first, installing GitHub CLI. If you're a macOS user, run brew install gh. If you're a Windows user, you can install it via scoop or Chocolatey. As for Linux, you have great installation instructions here: Installing gh on Linux.

It's installed? Good. As said previously, GitHub CLI aims at managing your workflow directly from the terminal. But it needs to have access to your account for that:

gh auth login

You'll be prompted to configure your preferred Git protocol, pick whatever suits you here. If you choose SSH, make sure you added a SSH key to your account.

Finally, set your preferred editor. In my case, I mostly work with VS Code. Thus, I ran:

gh config set editor "code --wait"

Note: The --wait option is essential here. Indeed, when you are prompted to enter a longer message (such as a pull request's body), the CLI needs to have a signal you're done, such as closing a VS Code window.

You're now good to go.

Commands

What can GitHub CLI do for you? Good question. As with most CLIs, you have a dedicated help command for that:

➜ gh help
Work seamlessly with GitHub from the command line.

USAGE
  gh <command> <subcommand> [flags]

CORE COMMANDS
  gist:       Create gists
  issue:      Manage issues
  pr:         Manage pull requests
  release:    Manage GitHub releases
  repo:       Create, clone, fork, and view repositories

ADDITIONAL COMMANDS
  alias:      Create command shortcuts
  api:        Make an authenticated GitHub API request
  auth:       Login, logout, and refresh your authentication
  completion: Generate shell completion scripts
  config:     Manage configuration for gh
  help:       Help about any command

FLAGS
  --help      Show help for command
  --version   Show gh version

EXAMPLES
  $ gh issue create
  $ gh repo clone cli/cli
  $ gh pr checkout 321

...

That's quite helpful. Most of the time, you'll use core commands. Use the --help option to know what you can do with each of them. Here's an example with the issue command:

➜ gh issue --help
Work with GitHub issues

USAGE
  gh issue <command> [flags]

CORE COMMANDS
  close:      Close issue
  create:     Create a new issue
  list:       List and filter issues in this repository
  reopen:     Reopen issue
  status:     Show status of relevant issues
  view:       View an issue

FLAGS
  -R, --repo OWNER/REPO   Select another repository using the OWNER/REPO format

INHERITED FLAGS
  --help   Show help for command

ARGUMENTS
  An issue can be supplied as argument in any of the following formats:
  - by number, e.g. "123"; or
  - by URL, e.g. "https://github.com/OWNER/REPO/issues/123".

EXAMPLES
  $ gh issue list
  $ gh issue create --label bug
  $ gh issue view --web

...

Now, I don't want to explain to you each command. On the official GitHub CLI website, you can find a well-explained manual of all these commands. Instead, I'm going to show you examples of how this CLI can improve your workflow in your everyday developer's life.

Examples

Create a PR

Let's say you work on a brand new feature for your company or open-source project. You finished the work and want to create a PR on GitHub. Usually, you would have gone to github.com to open the PR, right? Well, now, you can do exactly the same with gh pr create:

➜ gh pr create
? Where should we push the 'feat/signup' branch? company/repo

Creating pull request for feat/signup into master in company/repo

? Title feat(signup): Add signup screen
? Body <Received>
? What's next?  [Use arrows to move, type to filter]
> Submit
  Continue in browser
  Add metadata
  Cancel

As you can see, this command is interactive. I provided the title, the body in VS Code, and then submitted the PR in a snap.

Suppose you were to provide some metadata such as the reviewers, assignees, or labels. In that case, you could also do it by selecting Add metadata:

? What's next? Add metadata
? What would you like to add?  [Use arrows to move, space to select, <right> to all, <left> to none, type to filter]
  [ ]  Reviewers
> [x]  Assignees
  [ ]  Labels
  [ ]  Projects
  [ ]  Milestone

See relevant pull requests

It's common for a developer to have many tasks at once: your review is requested on a piece of code, you fix a bug while waiting for a review on one of your feature PRs. In that case, you may want to know the statuses to know your next actions:

> gh pr status

Relevant pull requests in company/repo

Current branch
  #234  fix(homepage): Avatar is not shown if account created with Google [fix/avatar]
  - Checks pending - Review required

Created by you
  #234  fix(homepage): Avatar is not shown if account created with Google [fix/avatar]
  - Checks pending - Review required
  #224  feat(signup): Add signup screen [feat/signup]
  ✓ Checks passing - Review required

Requesting a code review from you
  #231  docs(onboarding): Add docs on how to deploy on production [docs/onboarding]
  ✓ Checks passing

How convenient this command is. I know at a glance what's going on with your PRs:

• Current branch: I'm working on a fix
• Created by you: My fix has some checks pending, and I didn't get any reviews yet. I also have another opened PR that passes the checks, but I haven't received any reviews.
• Requesting a code review from you: A PR on documentation has passed the checks and I need to give my review.

If I were to review the docs PR, I could simply type gh pr view 231, and view the PR on the terminal or on the web using the --web option.

Waiting for Travis

Let's say your PR is already opened and you got some review comments. You worked through your comments, pushed your code, and wanted to know if you can merge the PR. Maybe you've set up Travis CI, and you're waiting for the build to pass:

> gh pr checks

➜ gh pr checks
All checks were successful
0 failing, 1 successful, and 0 pending checks

✓  Travis CI - Pull Request  5m26s  https://travis-ci.com/github/comp...

(Let's be honest, one of our favorite tasks, as developers, is to wait for Travis, isn't it? 😄)

If everything's OK, you can also merge the PR right from your terminal:

gh pr merge

Testing a colleague's changes

Developers, when reviewing code, tend to focus on the code only. It's indeed faster, but perhaps it's worth it to check out the changes live. It allows you to have a better vision of what the code really implies and its value.

Now, you can check out your colleague's branch with GitHub CLI. Use the pr checkout along with the pull request's number, and you're good to go:

gh pr checkout 6838

As a front-end developer, I often use it to make sure the UI changes properly work.

Note that you can find an example of this command on GitHub directly:

src="/save-time-github-cli/github-open.png"
alt="A screenshot of GitHub's button open with"
/>

Your next issue

You're maintaining an open-source project, and you want to know what's the next thing you can work on. Then, you can browse your issues with the issue command:

> gh issue list

Showing 15 of 15 open issues in testing-library/eslint-plugin-testing-library

#227  [await-async-utils] false p...  (bug)                           about 23 days ago
#222  [await-async-query] Support...  (help wanted)                   about 1 month ago
#219  feature request: no-await-f...                                  about 1 month ago
#202  Support eslint fix command ...  (enhancement)                   about 2 months ago
#198  Move custom render function...  (BREAKING CHANGE)               about 18 days ago
#187  Autogenerate configs from r...                                  about 3 months ago
:

Maybe you don't have much time and you want to fix a bug. Then, filter them with the --label option:

> gh issue list --label bug

Showing 2 of 2 issues in testing-library/eslint-plugin-testing-library that match your search

#227  [await-async-utils] false positive pr...  (bug)  about 23 days ago
#141  Lint RenderResult when returned from ...  (bug)  about 2 months ago

There are lot of other filtering options. Don't hesitate to run gh issue list --help to know more.

Quick approval

Someone at your company spotted a bug in production and needs to quickly ship a small fix. Let's say its PR is the number #211. You can approve it in just two commands:

1. Visualize the changes: gh pr diff 211
2. Approve the PR gh pr review 211 --approve

Your colleague gets a fast approval and you don't fully interrupt your workflow. I call that a win-win.

Contributing to an open-source project

At the time of writing, it's the 2020 edition of Hacktoberfest. Maybe you want to make a contribution to open-source. Usually, that includes forking a repo:

➜ gh repo fork organization/repo
- Forking organization/repo...
✓ Created fork user/organization/repo
? Would you like to clone the fork? Yes
Cloning into 'repo'...
...
✓ Cloned fork

Some maintainers label issues as good first issue for the newcomers. Then, you can search through them from the CLI:

gh issue list --label "good first issue"

Note: if you're considering contributing to a project? Please don't spam them with meaningless contributions such as adding "Amazing project" next to a title or similar. Open source maintainers are working hard on their beloved repos. ❤️

Using both GitHub and GitHub CLI

As you can see, GitHub CLI is powerful and can improve your workflow. It has already become a tool I'm using every day. Approving a pull request, finding an issue on which I can work, quickly see if a build pass, it's a real time-saver, and it has become a tool I'm using every day.

It doesn't mean you should use only GitHub CLI as of now. Don't forget the UI. For example, I still find it useful to do a complete review or browsing issues. Use what suits your needs best.