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.
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
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:
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
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
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-repois the name of the repo we're creating
--privateindicates that we would like the repo to be private
-g VisualStudioindicates that we would like a
.gitignorefile to be created using the
VisualStudiotemplate. Note you can also use
--gitignore VisualStudioif you prefer more descriptive arguments
-ytells the CLI to skip the final confirmation steps and to clone the repository locally after finishing. Note you can also use
--confirmif you prefer more descriptive arguments
The GitHub docs are excellent and contain a full list of supported arguments for
gh repo create.
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 email@example.com.