The all-new GitHub CLI has shipped! This now brings the power of GitHub to your terminal, on Windows, macOS, and Linux. GitHub is giving us the following capabilities:

  • Run your entire GitHub workflow from the terminal, from issues through releases
  • Call the GitHub API to script nearly any action, and set a custom alias for any command
  • Connect to GitHub Enterprise Server in addition to GitHub.com


Install GitHub CLI

Following these links to install on Windows, macOS, and Linux.

Windows

On Windows, the gh CLI can be installed via an MSI file.

Getting Started with GitHub CLI 1
MSI install of GitHub CLI

Chocolatey Package:

Getting Started with GitHub CLI 2
Choco install of GitHub CLI
choco install gh

macOS

Home Brew


brew install gh

Linux

GitHub has published detailed instructions for different distros. TDLR installs below.

Debian/Ubuntu distros

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-key C99B11DEB97541F0
sudo apt-add-repository -u https://cli.github.com/packages
sudo apt install gh
Getting Started with GitHub CLI 3
gh installed on WSL in Windows Terminal

Fedora distros

sudo dnf config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo
sudo dnf install gh

Command Structure

After running the install, I then ran my first ever gh command from WSL running in Windows Terminal.

Getting Started with GitHub CLI 4
first ever gh on WSL in Windows Terminal

The GitHub CLI seems to follow the standard for most command tools where the binary is called with a set of commands and subcommands along with flags that can be passed:

gh <command> <subcommand> [flags]

The tool lists the following as CORE COMMANDS:

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

There are also 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

Connecting gh to GitHub

With the gh CLI now installed, I need to authenticate to my GitHub account. One of the additional commands listed above was auth. I ran the following command to understand how to get connected.

gh auth --help
Getting Started with GitHub CLI 5
gh auth –help command

I can see now that I need to use the auth command with the login subcommand.

gh auth login --help
Getting Started with GitHub CLI 6
gh auth login –help command

From the help, I see that the gh CLI supports an interactive login, so I run the following command and I will then have to select GitHub.com as my connection and to Login with a web browser.

gh auth login
Getting Started with GitHub CLI 7
Select github.com and web browser

The gh CLI tells me to copy a code and press Enter.

Getting Started with GitHub CLI 8
Copy the auth code

The web brower will then open to a GitHub.com page where, the code must be used to activiate the session, and then the gh CLI must be authorized by you to access your GitHub page.

Getting Started with GitHub CLI 9
Enter Code
Getting Started with GitHub CLI 10
Authorize gh CLI
Getting Started with GitHub CLI 11
gh CLI connected to GitHub account

You will need to make one further selection in the terminal window and that is to use HTTPS or SSH for your commands. I selected HTTPS. And with that I’m connected and ready to use the CLI!

Getting Started with GitHub CLI 12
ch CLI connected to my account

gh CLI first commands

GitHub has an extensive CLI command reference to help with getting started. I ran a few commands against the build5nines/az-kung-fu repo just to get a feel of using gh.

gh repo view build5nines/az-kung-fu
Getting Started with GitHub CLI 13

Next, I listed the issues on the repo:

gh issue list --repo build5nines/az-kung-fu
Getting Started with GitHub CLI 14
List issues on repo

I then opened a new issue:

gh issue create --repo build5nines/az-kung-fu --title "Find Image missing list versions of images" --body "We are missing a command in this sample that lists all of the images a user has access to in the Azure Marketplace."
Getting Started with GitHub CLI 15
Create new Issue on repo

The issue can now be seen on GitHub

Getting Started with GitHub CLI 16
New Issue on GitHub.com

Well, I hope you enjoy getting started with the gh CLI! I’m going to be using this a lot in the future as I can see some awesome features here! Here is the CLI command reference.

Thanks,

@deltadan


Microsoft MVP

Dan Patrick is the Chief Infrastructure Architect for Solliance and a 15 year veteran at Microsoft. He has an extensive background in IT Infrastructure and Operations. Dan has both architected and lead teams building and supporting some of the largest service providers in North America with as many 15,000 Windows Servers and 120 million endpoints. Dan has worked with Azure IaaS solutions extensively since 2012. He has a passion for Virtualization with deep experience leveraging Hyper-V, Vmware, and Citrix. He is also a Clustering specialist focusing on large host clusters and SQL Always On Availability Groups. Recently Dan, authored the Networking, Azure Active Directory and Containers portion of the 70-533 Exam Reference for Microsoft Press. You can follow him on Twitter @deltadan