Getting started with Github CLI

GitHub (GH from now) just released their first stable version of their CLI , the tool for managing and interacting with your GH repositories from your terminal. No more back & forth between the terminal & web browser for creating PRs, forking repositories, and whatnot. And if you or your company uses GH as their issue tracking tool, even better!

I started to play with it as I find it useful to have an uninterrupted workflow entirely in my terminal. Usually, I have to fork repositories, create feature branches, do my stuff, commit-push, and then create PR to the original repository. Now I want to share my experience with you.

Let's get hands on! Let's start by trying to create a repository in our GH account. We do so with the command git repo.

ocalderon@pop-os:~$ gh repo create main-repo

However, since we haven't authenticated in our CLI, we will get a message indicating to do so.

ocalderon@pop-os:~$ gh repo create main-repo
Welcome to GitHub CLI!
To authenticate, please run 'gh auth login'.
You can also set the GITHUB_TOKEN environment variable, if preferred.

Running the command gh auth login will get us through a simple process to authenticate via web browser or using a generated token from GH webpage.

ocalderon@pop-os:~$ gh auth login
? What account do you want to log into? GitHub.com
- Logging into github.com
? How would you like to authenticate? Login with a web browser
! First copy your one-time code: 0123-ABCD
- Press Enter to open github.com in your browser... 

Going with the web option will generate a unique code that we have to paste in the GH webpage that is opened by the command.

Then we review the permissions to give to the application, and we are in!

✓ Authentication complete. Press Enter to continue...
? Choose default git protocol SSH
- gh config set -h github.com git_protocol ssh
✓ Configured git protocol
✓ Logged in as ocalde

Now that we authenticated through gh, we can try again to create our repository. It will ask us some questions, like repository visibility, or if we want to clone it in our current repository.

ocalderon@pop-os:~$ gh repo create main-repo
? Visibility Private
? This will create 'main-repo' in your current directory. Continue?  Yes
✓ Created repository ocalde/main-repo on GitHub
? Create a local project directory for ocalde/main-repo? Yes
Initialized empty Git repository in /home/ocalderon/main-repo/.git/
✓ Initialized repository in './main-repo/'

And that's it. You can check in your GH account to see that the repository has been created successfully.

Now, let's suppose we want to propose some changes in airbnb/javascript repository, created by Airbnb about Javascript best practices. For doing this, we need to fork the repository, do some changes, and then create a PR. We can do that from our terminal entirely, using gh.

We start by trying to fork the repository, using gh repo.

ocalderon@pop-os:~$ gh repo fork airbnb/javascript
? Would you like to clone the fork? Yes
Cloning into 'javascript'...
The authenticity of host 'github.com (140.82.112.3)' can't be established.
RSA key fingerprint is ....
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added 'github.com,0.0.0.0' (RSA) to the list of known hosts.
git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.
Please make sure you have the correct access rights
and the repository exists.
failed to clone fork: exit status 128

This happens because we haven't configured any SSH keys in our GH account. You can follow these steps to generate your SSH key , and configure it in your account.

Once we are done with that, we can try again to fork the repo (we will be asked for the passphrase which we used to generate our SSH key):

ocalderon@pop-os:~$ gh repo fork airbnb/javascript
- Forking airbnb/javascript...
! ocalde/javascript already exists
? Would you like to clone the fork? Yes
Cloning into 'javascript'...
Warning: Permanently added the RSA host key for IP address '0.0.0.0' to the list of known hosts.
remote: Enumerating objects: 7862, done.
remote: Total 7862 (delta 0), reused 0 (delta 0), pack-reused 7862
Receiving objects: 100% (7862/7862), 3.13 MiB | 3.60 MiB/s, done.
Resolving deltas: 100% (4231/4231), done.
Updating upstream
From github.com:airbnb/javascript
 * [new branch]      gh-pages   -> upstream/gh-pages
 * [new branch]      master     -> upstream/master
 * [new branch]      shar--eslint-config-airbnb-prettier -> upstream/shar--eslint-config-airbnb-prettier
 * [new branch]      travis     -> upstream/travis
✓ Cloned fork

Repository forked and cloned! We then can create a feature branch, do some changes, commit & push them, and once we are ready, we can create a PR, with gh pr.

ocalderon@pop-os:~$ gh pr create -B master -H ocalde:feature-branch 
Creating pull request for feature-branch into master in airbnb/javascript
? Title Some suggestions for Javascript documentation
? Body <Received>
? What's next? Submit
https://github.com/airbnb/javascript/pull/0000

Like previous commands, we are asked for information like PR title, body (we can specify these when typing the gh pr command). Also, I used -B and -H to specify the base & head branches, although I think it can ask for it as well if it isn't clear.

If everything goes right, the PR is created automatically, and the command output gives you the URL to check it.

And this is just a sample of what you can do using GH CLI. As I mentioned earlier, you can also handle the workflow of working with issues inside GH, and a lot of other things. You can check https://cli.github.com/manual/ for a complete reference of all the available commands.