How and why to start with GitHub CLI
The GitHub CLI package is a command-line tool for using GitHub features on your computer. You can easily access to GitHub from your computer’s command line instead of using browser.
In this tutorial we are going to install and configure the GitHub CLI on a Windows terminal. if you are a Mac or Linux user the installation process for both is pretty much straight forward from the official documentation under the installation section here. We then will setup and configure it to create authentication between your GitHub account and the installed CLI.
Introduction
For many years, hub was the unofficial GitHub CLI tool. gh is a new project that represents official GitHub CLI tool and to what is could look like with a fundamentally different design. While both tools bring GitHub to the terminal, hub behaves as a proxy to git, and gh is a standalone tool. Check out our more detailed explanation to learn more about their differences.
GitHub CLI provides an access to the Issues and Pull Requests and almost every operation and features that was previously accessible via the GUI of GitHub website trough terminals with a simple command called gh.
You can use the following GitHub features with the GitHub CLI.
- View, create, clone, and fork repositories
- Create, close, and list issues and pull requests
- Get, view, diff, and merge pull requests
- Create, edit, list, and view gists
Installing GitHub CLI
First we need a package-installer that offers this GitHub CLI. gh is available via WinGet, scoop, Chocolatey, and as downloadable MSI installers for each release available on the releases page.
Scoop and Chocolate each offers an update command that could be life saver in the feature on every release but WinGet does not have a specialized upgrade command yet, but the install command should work for upgrading to a newer version of GitHub CLI.
I’m going to use Snoop and to install it simply run this command inside Windows PowerShell:
λ Invoke-Expression (New-Object System.Net.WebClient).DownloadString('https://get.scoop.sh')# or shorterλ iwr -useb get.scoop.sh | iex
After that, we can use Scoop to install gh for us running:
λ scoop bucket add github-gh https://github.com/cli/scoop-gh.git
λ scoop install gh
Installing 'gh' (1.4.0) [64bit]
gh_1.4.0_windows_amd64.zip (5.6 MB) [=========================================================================] 100%
Checking hash of gh_1.4.0_windows_amd64.zip ... ok.
Extracting gh_1.4.0_windows_amd64.zip ... done.
Linking ~\scoop\apps\gh\current => ~\scoop\apps\gh\1.4.0
Creating shim for 'gh'.'gh' (1.4.0) was installed successfully!
To update in the feature you can use
scoop update ghI actually had to use this only hours after initially install it with version 1.4.0 in the middle of this article and GitHub just announced releasing a new version of GitHub CLI 1.5.0.
Configuring the GitHub CLI?
In order to be able to use GitHub CLI you need to authenticate with your GitHub account. Run this command to start with gh:
gh auth login
? What account do you want to log into? [Use arrows to move, type to filter]
> GitHub.com GitHub Enterprise Server
It asks you to determine which service you want to login, the personal and Enterprise choices are available, to use it with your account select GitHub.com by passing Enter.
What account do you want to log into? GitHub.com
- Logging into github.com
? How would you like to authenticate? [Use arrows to move, type to filter]
> Login with a web browser Paste an authentication token
To login with web browser simply press enter, or build your personal token using this manual from GitHub documentation. Personal access tokens (PATs) are an alternative to using passwords for authentication to GitHub when using the GitHub API or the command line. Once you have a token, you can enter it instead of your password when performing Git operations over HTTPS.
Login with web browser:
How would you like to authenticate? Login with a web browser
! First copy your one-time code: XXXX-XXXX
- Press Enter to open github.com in your browser...
It will open a GitHub page and ask you to enter your password and then redirects to https://github.com/login/device
Enter your one-time code and accept the authentication for GitHub CLI .
Now you can see the massage on the terminal
Authentication complete. Press Enter to continue...Choosing git protocol
Next you will ask for the method you want to access GitHub
Choose default git protocol [Use arrows to move, type to filter]
> HTTPS SSH
I am going to use SSH protocol for this purpose. HTTPS is much more secure but inevitably less efficient too. Requires quite some configuration. You’ll also need a trusted TLS certificate. On the other hand SSH Keys do not provide access to your GitHub account, so your account cannot be hijacked if your key is stolen.
? Choose default git protocol SSH
- gh config set -h github.com git_protocol ssh
✓ Configured git protocol
✓ Logged in as YOU!That’s it, You can use it now with finding an open source project you want to contribute, use gh to clone the repository, quickly view the details of any repo, Create a branch, make several commits to fix the bug described in the issue, and use gh to create a pull request to share your contribution.
Creating a Pull Request with GitHub CLI
In a collaborative ecosystem each individual creates it’s own fork from a repository to start working on features and issues of that. He or she then pushes their work to their own forke in order to make a pull request to the upstream repository. Traditionally we had to go ti GitHub website push our for PR to the upstream repo.
Now using GitHub CLI you can check out a pull request locally with:
gh pr checkout <PR-number>This will create a local branch with the changes included in the PR. Similarly, you can create a pull request using:
gh pr createAfter running this command, GitHub CLI will gather title and description from the command line and create the PR remotely.
The other useful gh pr commands are:
- gh pr view: display the title, body, and other information about a pull request.
- gh pr status: show status of relevant pull requests.
- gh pr ready: make a pull request as ready for review.
- gh pr review: add a review to a pull request.
- gh pr close: close a pull request.
- gh pr reopen: reopen a pull request.
Conclusion
Having access to everything that previously was offered with the GUI or with hub the unofficial GitHub CLI is in many ways beneficial, beyond just to avoid switching between Contexts, it provides an enrichening power over the development process using customized automations to deal with time consuming and problematical operation. It also offers special security settings to for more control over accessing the private resources from within the command line under it’s Enterprise versions.
After GitHub CLI announced it’s Beta release in early 2020, today they released version 1.5.0, short after adding the UI component of it’s own inside the GUI within the clone tab as a new feature to clone repositories using gh. Hopefully it motivate you to install and use it inside the terminal.
For the complete list of GitHub CLI commands visit https://cli.github.com/manual/index
