Getting started with the GitHub CLI

GitHub Nov 29, 2021

Since moving the majority of our source code from Azure DevOps over to GitHub we've started to work with the awesome GitHub CLI. In this post we'll discuss how to get started and how to create a new repository using our newly discovered command line skills.

Installation

The first thing we need to do is to get the CLI installed. At the time of writing support is available for macOS, Linux and Windows and each OS supports a number of ways of installing the CLI. For this post we're going to focus on a Windows 11 install using WinGet.

You can find the full and up to date list of tools which can be used to install the CLI at GitHub's official installation documentation.

On Windows 11 installing with WinGet is as simple as opening a PowerShell prompt and typing:

winget install --id GitHub.cli

The winget command locates the CLI and downloads the most recent MSI directly from GitHub. The installer then kicks in automatically and all you need to do is click on Yes when the User Account Control (UAC) popup appears asking for permissions to install.

All commands in the CLI begin with gh so to confirm the install has completed successfully you can issue the following command:

gh --version

This will display the installed version number however if it doesn't work you may need to restart your command prompt before it picks up the new gh commands.

Authenticating with GitHub

Now we have the CLI installed the next thing we need to do is to authenticate to GitHub with the following command:

gh auth login

This will initially ask us what kind of account we want to log in to, either GitHub.com or GitHub Enterprise Server. In my case it's GitHub.com which is the default so I'm going to leave it there and hit Enter.

Next up we have to decide whether we want to connect over HTTPS or SSH. At the time of writing GitHub recommends connecting over HTTPS. There is nothing wrong with SSH, however HTTPS is less overhead in terms of managing keys and it's also less likely to be blocked by a firewall or proxy. I'm happy to go with the default so I've left it there and hit Enter.

Now we are asked if we want to authenticate Git using our GitHub credentials which is a yes for us so I've entered Y.

Now we are presented with two potential methods of completing the authentication, either via a web browser or by pasting in a person access token (PAT). I'm going to stick with the web browser option as it's cleaner.

The CLI now displays a one-time code and asks you to press Enter to open github.com in your browser. If you're already logged in to github.com you're taken straight to the Device Activation page where you can enter the one-time code however if you're not signed in then you'll find yourself at the GitHub login page where you can log in as usual.

After entering the one-time code you'll need to confirm that you authorise GitHub and after you've done that the CLI will have completed authentication and you can press Enter one final time.

Creating a new repository

Next up we're going to create a new repository using our authenticated CLI. To do that we need to use the gh repo create [name] command where the [name] is replaced with the name of our new repository. In this case I'm going to call it cli-test-repo making the command:

gh repo create cli-test-repo

Note that by default this will create the repository against your personal GitHub account. If you need to create the repo within an organisation you can append the organisation name onto the front of the repository name e.g.

gh repo create organisation-name/cli-test-repo

Similar to when we authenticated the gh repo create command launches an interactive wizard which takes us through a few questions we need to answer about our repository.

Firstly we need to decide if it's public, private or internal. I'm going to select Private and press Enter.

Next we're asked if we would like to add a .gitignore. In this case I'm going to say yes and then select VisualStudio from the presented list. It's a long list so it's good to see that you can start to type at this point the list will auto filter.

Now we have to decide if we would like to add a licence. I'm going to select no but if you do select yes you are presented with a list of licences to choose from in the same way as we choose a .gitignore above.

Finally we need to confirm that we're happy to create the repository and whether we would like to take a clone to our local machine. It's a yes to both of those for us.

If we decide not to clone the repository at this point we can do it an any point by using the gh repo clone command e.g.

gh repo clone cli-test-repo

Issuing a single command

While the interactive wizard is very good we can leverage the arguments of the repo create command to pass values in rather than being asked a series of questions. Using arguments we can condense the wizard steps into a single command:

gh repo create cli-test-repo --private -g VisualStudio -y

Lets break this down one argument at a time:

  • cli-test-repo is the name of the repo we're creating
  • --private indicates that we would like the repo to be private
  • -g VisualStudio indicates that we would like a .gitignore file to be created using the VisualStudio template. Note you can also use --gitignore VisualStudio if you prefer more descriptive arguments
  • -y tells the CLI to skip the final confirmation steps and to clone the repository locally after finishing. Note you can also use --confirm if you prefer more descriptive arguments

The GitHub docs are excellent and contain a full list of supported arguments for gh repo create.

Summary

In this post we talked through how to get started with the GitHub CLI and how to create your first repository.

Any questions or comments please don't hesitate to get in touch at hello@sidebytes.com.

Tags

Andy Macdonald

Andy has been involved in the software industry for over 20 years as a developer, architect and team leader.

Great! You've successfully subscribed.
Great! Next, complete checkout for full access.
Welcome back! You've successfully signed in.
Success! Your account is fully activated, you now have access to all content.