How to use the GitHub CLI app on Windows and WSL

Microsoft-owned GitHub is the biggest code-sharing platform on the planet and while using it through the web browser is simple, when you're interacting with your code and local files you're more than likely using a terminal.

That's where GitHub CLI comes in. An official tool made by GitHub, it's good to use both on Windows 10 and Windows 11 in PowerShell or within the Windows Subsystem for Linux (WSL). Once you're familiar with it, it could speed up a number of areas of your GitHub workflow.

Here's how to install it, get set up and carry out some basic processes.

Set up a GitHub account before anything else

You don't need a GitHub account to browse code and clone repos, but it's still worth signing up. Only with your own account and repo space can you store your own files and fork other projects, follow other members, and star repos for easy access later on. It's completely free to use and doesn't require you to have a Microsoft Account.

A GitHub account also allows you to make use of the oft-overlooked GitHub CLI terminal application, which due to some changes in how GitHub allows accounts to be authenticated, is actually something you should have. More on that later.

You don't have to interact with GitHub through the terminal, but in many cases, it's the most efficient workflow.

Installing GitHub CLI onto Windows or WSL

The GitHub CLI tool is an official GitHub application, and if you're going to be using GitHub, it's well worth having. For one, it gets around using personal access tokens with Git to push local repositories up to GitHub, as you can use the GitHub CLI application to authenticate your whole system.

To install the GitHub CLI on Windows you can use the Windows Package Manager again by entering this into PowerShell.

winget install github.cli

Alternatively, you can grab it directly from GitHub and it's also available through the Scoop and Chocolately package managers, too. 

On WSL, the process is a little more involved, but GitHub has full documentation you can follow. Since most people using WSL are likely to have Ubuntu or Debian installed as they're officially distributed through the Microsoft Store, you can use the following commands in your WSL terminal to install it.

curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpgecho "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/nullsudo apt updatesudo apt install gh

As with Git, the WSL installation of the GitHub CLI is separate from the Windows installation you would use in PowerShell. The two operate the same way, but if you switch between WSL and PowerShell, you'll need to have it installed in both locations.

How to set up GitHub CLI and authenticate your account

The GitHub CLI, unlike Git, can use your account login and password for authentication with the added bonus of then also allowing Git to push to your GitHub repositories. To authenticate GitHub CLI, open up your terminal and follow these steps. Again, all the steps are the same whether you use Windows or WSL.

1. In the terminal enter gh auth login
2. Choose GitHub.com.
3. Select HTTPS as the protocol.

4. Type Y to authenticate with your GitHub credentials
5. Hit Enter to login with a web browser.

6. Note down the one-time code you're presented with, and press Enter.
7. A browser will now open, and you'll need to log into GitHub if you aren't already.
8. Enter the one-time code in the box.

You'll now be logged into the GitHub CLI client. To see the full list of commands available simply type:

gh --help

Using GitHub CLI

There is a basic command template for using GitHub CLI that looks like this:

gh [command] [sub-command] [flags] 

All commands you enter will begin with "gh" in order to trigger GitHub CLI. There are a number of commands to use, but here are some examples of how you would carry out some basic functions.

Create a new GitHub repository

GitHub CLI gives you the ability to create a new remote repository without having to first go to the GitHub website and then link it back to your local machine. To do so you need to have Git initialized in your local directory and then navigate there in the terminal. Then enter:

gh repo create

You'll be asked to give it a name, an optional description, its visibility and to confirm you want to create an "origin" Git remote in your local directory. Once all are completed, you can go check out your new repo on the GitHub website. You can open up this or any of your other GitHub repos from their local directories by entering:

gh browse

Clone or fork a GitHub repository

Most of the time you'll use the "git clone" command to clone a local copy of a GitHub repository, but you can do the same using the GitHub CLI tool using this command.

gh repo clone [user/repo name or URL]

So, for example, to clone Microsoft Visual Studio you would simply enter:

gh repo clone microsoft/vscode

The end result is the same as using Git, and a new directory will be created on your local machine with all contents of the remote repository contained within. You can also use GitHub CLI to clone repos with the full URL if you have that instead, and using the same command without the username will allow you to clone your own repos easily.

gh repo clone [your repo name]

You can also use GitHub CLI to fork a repository and clone a local copy if you wish. You don't have to clone it, however, but it's a quick way to achieve both goals with one command.

gh repo fork [user/repo name or URL]

For example:

gh repo fork microsoft/winget-pkgs

Once you hit Enter, you'll be asked whether you want to clone the fork or not.

The GitHub CLI tool also has an easy way to find repos you might want to clone, assuming you know the organization or username. For example, to see all Microsoft repositories on GitHub you might enter:

gh repo list microsoft

Creating a new issue

Creating issues is a key part of the GitHub process, and you can do that right from the command line using this command.

gh issue create

The tool will then ask you to give your issue a title, followed by opening a text editor, such as Nano in WSL, to fill out the body of the issue, then the option to submit or to continue in the browser. It's really straightforward, and the prompts will guide you at every step.

Viewing and closing issues

To get a full list of the available tools for the issue in question use this command: 

gh issue --help

One of the most common you'll want to use is viewing issues and then closing them if dealt with. To view all issues for your GitHub repository, enter this command.

gh issue list

You'll now be given a printout of all issues submitted to that repository. To close off issues that have been dealt with, take note of the issue number and enter this command.

gh issue close 1

You'll be given a confirmation that the issue has closed, and to confirm you can run the list command again, and it should be gone.

Creating a pull request

There are a number of options you have when creating pull requests in GitHub CLI, but the basic template is as follows.

gh pr create [subcommand] 

At any time, you can add "--help" to the above to get a full breakdown of all available options. If you wanted to create a pull request and continue it on the web, for example, you would enter:

gh pr create -w

Pull requests behave in exactly the same way as on the web, so naturally won't work if you're on the master branch.

There's a lot more to GitHub CLI than we've talked about here, but hopefully, this gets you pointing in the right direction, particularly if you're a beginner to using GitHub at all. We have a full beginner's guide to GitHub that's a good companion to this, but once you're comfortable with the basics there's a lot to explore. Most of GitHub's main features can be interacted with using the CLI tool.

If at any point you need a bit more information, the "--help" flag after a command is your friend, as it'll break down everything you can do with every possible command available in GitHub CLI.