Github CLI: An Introduction

Earlier this year, Github announced the beta version of Github CLI, a new command-line tool for developers. This tool, according to the team, is supposed to reduce context switching and help the developer run their entire workflow right from the terminal. Cool right? #LetsTalkAboutIt

Scenario

In your local repository, you use git in the terminal for staging, committing, and pushing changes to your remote repository. Once you're done, you then switch to Github in the browser for tasks like managing issues, pull requests, etc

Now imagine having to do this about fifty times a day (or even more), coupled with the stress from the actual job - coding and debugging. Now that's something

Enter Github CLI

Github CLI offers a solution to this problem. You can perform all the browser-related tasks and even more, right in the terminal - you don't have to switch. In addition, you get access to an API that you can use to customize your experience. But enough of the chit chat. Let's dive into using gh

Installation

Detailed installation instructions are available in the README

Windows

MSI installers are available for download on the releases page.

# Via Scoop
scoop bucket add github-gh https://github.com/cli/scoop-gh.git
scoop install gh

# Via Chocolatey
choco install gh

Mac OS

# Via Homebrew
brew install gh

# Via MacPorts
sudo port install gh

Linux

# Debian, Ubuntu Linux (apt)
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-key C99B11DEB97541F0
sudo apt-add-repository https://cli.github.com/packages
sudo apt update
sudo apt install gh

For other Linux distros, please visit the install instructions page

Getting Started

Check version to ensure it installed correctly. You should get response as below

gh version

# gh version 1.0.0 (2020-09-16)
# https://github.com/cli/cli/releases/tag/v1.0.0

Authentication

gh auth login

The authentication process is quite smooth. The first prompt asks you to choose between Github and Github Enterprise. Then you will choose either to authenticate via the web browser or paste in a GitHub token (if you have a GITHUB_TOKEN environment variable set, it will be used).

Commands

The commands are pretty straight forward and easy to understand and use

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

ENVIRONMENT VARIABLES
  See 'gh help environment' for the list of supported environment variables.

LEARN MORE
  Use 'gh <command> <subcommand> --help' for more information about a command.
  Read the manual at https://cli.github.com/manual

FEEDBACK
  Open an issue using 'gh issue create -R cli/cli'

Let's take the repo subcommand, for instance:

gh repo --help
Work with GitHub repositories

USAGE
  gh repo <command> [flags]

CORE COMMANDS
  clone:      Clone a repository locally
  create:     Create a new repository
  fork:       Create a fork of a repository
  view:       View a repository

INHERITED FLAGS
  --help   Show help for command

ARGUMENTS
  A repository can be supplied as an argument in any of the following formats:
  - "OWNER/REPO"
  - by URL, e.g. "https://github.com/OWNER/REPO"

EXAMPLES
  $ gh repo create
  $ gh repo clone cli/cli
  $ gh repo view --web

LEARN MORE
  Use 'gh <command> <subcommand> --help' for more information about a command.
  Read the manual at https://cli.github.com/manual

Cloning a repository https://github.com/OWNER/REPO:

gh repo clone OWNER/REPO

# if you own the repo, all you need is the repo name
gh repo clone REPO

Let's explore the alias subcommand

gh alias --help
Aliases can be used to make shortcuts for gh commands or to compose multiple commands.

Run "gh help alias set" to learn more.


USAGE
  gh alias [flags]

CORE COMMANDS
  delete:     Delete an alias
  list:       List your aliases
  set:        Create a shortcut for a gh command

INHERITED FLAGS
  --help   Show help for command

LEARN MORE
  Use 'gh <command> <subcommand> --help' for more information about a command.
  Read the manual at https://cli.github.com/manual

Let's set an alias il for listing issues on a repo and use it to access issues list on my repo wesscoby/wesscoby:

gh alias set il 'issue list' 

# - Adding alias for il: issue list
# ✓ Added alias.

~                                                                              
gh alias list

# co:  pr checkout
# il:  issue list


gh il --repo wesscoby/wesscoby

# Showing 2 of 2 open issues in wesscoby/wesscoby

#3  Fix Portfolio links     about 3 days ago
#2  Resume Download Link 

As you can see, the tool is very well documented, providing rich user experience.
You can also access the docs website for more.

Conclusion

This is indeed a great tool made by developers for developers like myself, who enjoy working in the terminal.