Github CLI: An Introduction
Published: 2020-09-22 11:47:04

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][installations-page]
#### Windows
MSI installers are available for download on the [releases page][releases].
```sh
# Via Scoop
scoop bucket add github-gh https://github.com/cli/scoop-gh.git
scoop install gh

# Via Chocolatey
choco install gh
```

#### Mac OS
```sh
# Via Homebrew
brew install gh

# Via MacPorts
sudo port install gh
```

#### Linux
```sh
# 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][linux-install]

### Getting Started
Check version to ensure it installed correctly. You should get response as below
```sh
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
```sh
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:
```sh
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
```sh
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`:
```sh
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][manual] for more.

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


[installations-page]: https://github.com/cli/cli#installation
[releases]: https://github.com/cli/cli/releases/latest
[linux-install]: https://github.com/cli/cli/blob/trunk/docs/install_linux.md
[manual]: https://cli.github.com/manual/