Getting Started with GitHub CLI
How to Install GH CLI
Before we can use the CLI we have to get it installed on our machines.
Refer to this README for specific installation instructions for your OS including Windows and MacOS.
Personally, Pop!_OS (Linux) is my preferred OS so I'll be sharing the Linux instructions.
For me getting started was as simple as running a few commands in the terminal!
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
Note: This should work for most Debian based distros like Ubuntu and Pop!_OS
Next you can confirm your installation by running the gh command with the --version flag
gh --version
Let's Create a Repo!
Once the CLI is installed we can easily create a repo on GitHub directly within a project on our local machine.
While this works for any project that can be managed with GitHub, I'm gonna run through the steps to quickly get a React application created with CRA and pushed up to GitHub.
First we need to create a project in whatever directory we would like:
# change directory to where you want to generate the project
cd whatever/path/you/like/
# generate a react application in that directory
npx create-react-app my-project
# change directory into the new project
cd my-project/
Now that we have a project set up we and because CRA initializes a local git repo for us, all we have to do is create a GitHub repo to host our project.
But First, Authentication
We are ready to leverage the GitHub CLI, but before we can reap the benefits of this tool, we need to authenticate with GitHub.
Check out all the documentation here
Run this command to login to GH from your terminal:
gh auth login
You'll be prompted to select either GitHub.com or GitHub Enterprise Server
GitHub.com should be selected by default, just hit enter.
Next, it will ask how you would like to authenticate.
Here you can paste in a token, if you've already set up SSH access for your device, by selecting the Paste an authentication token option.
Otherwise, you can select the default Login with a web browser option and it will give you an access code and open up your default web browser. That's the option I'll be selecting for this tutorial.
Hit enter and you will be presented with a one-time access code that you will need to copy. Copy it and then press enter and your browser will open up to a screen so you can paste in your code.
After you enter your code, you will then have to authorize the cli application to give it full access to your GitHub.
Once you click authorize, back in the terminal, it will ask if you want to use https or ssh, I would just select https for now. It just means you'll have to type your login/password when you push up your repo.
Once you've selected https you're done and you are now ready to use the GitHub CLI
Back to our project
At this point we should have the GitHub CLI installed and we should have authenticated our device with our account on GitHub.
We can finally create a repo from our terminal, and perform many other GitHub tasks!
Checkout the docs for this feature
Let's prepare our local repo, so it is ready to be pushed up to GitHub. Likely, there will be nothing to commit, that's okay. This is just a precautionary step.
git add .
git commit -m "initial commit"
Now we can create a remote GitHub repo to host our project.
gh repo create my-project
You will then be prompted to select either Public, Private, or Internal. Go ahead and select the default Public option.
It will then warn you that it will create your 'my-project' repo with your current directory go ahead and type in Y and press enter.
You should now see something like this:
✓ Created repository yourusername/my-project on GitHub
✓ Added remote https://github.com/yourusername/my-project.git
The gh repo create command should have already configured our remotes for us so all we need to do is push our code up:
# git defaults to the "master" branch we can change it
# before we push up our project
git checkout -b main
# this will be our default branch on GitHub
git push origin main
After issuing the push command, simply login with your GitHub credentials and we are done!
Go to GitHub to check out the repo you just created from your terminal!
Conclusion
The GitHub CLI is an awesome tool that makes things like creating repos and submitting PRs a breeze, all from your terminal! I highly suggest you take a look at the documentation for a deeper dive into its capabilities.
I hope you have found this article to be helpful, let me know what I can improve upon or if you have any issues getting up and running with GitHub CLI!
Top comments (3)
But, why use
gh? Just save a few click?Why not as convenient as git cz?
Really, it depends on whichever workflow you prefer, considering that the cli tool simply enables a developer to leverage quite a bit of GitHub's in-browser functionality right from the terminal. I find that by using GitHub's CLI tool, I save a lot more than just a few clicks.
I'm not familiar with cz as much but from looking at the repo, cz is more of a robust wrapper around git commit functionality that helps enforce commit convention. The separation is that cz is more "git specific" as gh is specific to GitHub functionality, so I don't see any reason why you couldn't use both in conjunction if you are hosting your repo on GitHub.
Very useful post !