The GitHub CLI (gh cli) is a command line tool that allows you to interact with GitHub without ever leaving your terminal. It's an open source tool that allows you to view and manage issues, pull requests, releases, and more. In this post, we'll cover 10 tips for using the GitHub CLI, but first, how do you install it?
Installing the GitHub CLI 🛠️
I'm using MacOS, so I'll be using Homebrew to install the GitHub CLI. If you're using Windows or Linux, you can find instructions for installing the GitHub CLI here.
brew install gh
Once you've installed the GitHub CLI, you'll need to authenticate with GitHub. You can do this by running the following command:
gh auth login
This will open a browser window and prompt you to login to GitHub. Once you've logged in, you'll be prompted to authenticate with GitHub. Once you've authenticated, you'll be able to use the GitHub CLI. 🎉
CLI Syntax and Usage 📝
The CLI follows a very specific syntax. It generally works as, "gh" "feature" "then what you want to do with the feature" then “any flags associated with the feature” - everything you want to do with the cli takes on this format.
For example, if you wanted to clone a repository using the gh cli, it would be gh repo clone <repo to be cloned>
Let's take a look at some practical tips when using the GitHub CLI.
1. Create a new repository and clone it locally 🎉
You can create a new repository using the gh repo create command. This command will prompt you for the name of the repository, the description, and the visibility. You can also specify the name of the repository as an argument to the command.
You can also create a new repository and clone it locally at the same time by using the --clone flag. Here's what this will look like:
gh repo create your-new-repo --public --clone
The repo was created here and all you need to do now is to push your changes and you're good.
2. Create issues 📝
We can create issues for this repository right from the command line with the gh cli. This command will prompt you for the title and body of the issue. You can also specify the title and body as arguments to the command.
gh issue create -t "issue title" -b "issue body content" -a "assignee"
You can also edit, transfer, delete, close, and reopen issues with the gh cli. You can find more information about this here.
3. Create pull requests 🔄
We can create pull requests by using the gh pr create command and follow the on-screen prompts. You can also specify the title and body as arguments to the command.
gh pr create -t "pull request title" -b "pull request body content" -a "assignee"
4. Review pull requests 👀
Run gh pr create and add the necessary flags: -t for the title, -b for the body -a for the assignee and -d to mark the pr as draft. You can also use gh pr create and follow the on screen prompts to create a new PR with the cli.
Once the PR is created, take note of the PR num and run gh pr view <num> to see the details of the pr in your terminal.
5. View action workflows 👀
We can view the action workflows right from the command line with the gh cli. This command will list all the recent action workflows for the repository.
gh run list
You can also run workflows right from your terminal with the command gh workflow run <workflow name>. This command will run the workflow and prompt you for any required inputs.
gh workflow run <workflow filename>
6. Open your current Repo in the browser 💻
You can open your current repository in the browser right from your terminal. This command will take you to the homepage of your repository.
gh browse
If you you attach the -b option, you can open the current branch in the browser, like so:
gh browse -b "branch name"
7. Create and update Project Boards 📋
Creating a project from your terminal with the command line requires you to have project scope permissions. To update your auth token with project scope permissions, run the following command and follow the on screen prompts:
gh auth refresh -s project,read:project
Once that's confirmed, you can create a project board with the command gh project create and follow the on screen prompts.
gh project create --owner "owner" --title "title"
8. Create edit, and view Releases 🚀
You can create a release with the command gh release create and follow the on screen prompts.
gh release create --title "title" --notes "notes"
You can also edit, dowload assets and delete relases with the gh cli. You can find more information about this here.
9. Start and Stop Codespaces 💻
A Codespace is an online development environment. You can start a codespace with the command gh codespace create and follow the on screen prompts. You can also do it by specifying certain flags, for example, the branch you want to use:
gh codespace create -b "branch"
You can then open up the codespace in VSCode or Jupyter Notebooks with the command gh codespace code [flags] or gh codespace jupyter [flags], respectively, where the flags can include the version of vscode, repo, repo owner and name of the codespace you want to open.
10. Browse and create gh cli extensions 📦
You can run gh extension browse in your terminal to view a list of all available cli extensions to make your terminal experience even better. You can also install ann extension directly from the browsing interface.
To install an extension you like, run gh extension install <repository> [flags] and follow the on screen prompts.
You can also create your own cli extensions with the command gh ext create and follow the on screen prompts.
Getting Help with the gh cli ❓
If you're ever unsure of what to do with the GitHub CLI or how to use it, you can always run gh --help and it will give you a list of all the commands, help topics, extensions, flags and examples you can run with the GitHub CLI.
GitHub Copilot for CLI 🤖
Ever forget a command and have to search for it over and over again? Yea, me too. This is why we built GitHub Copilot for CLI. It provides a chat-like interface in your terminal to help you find commands for GitHub CLI, shell commands and git.
I'll be showing you how to use GitHub Copilot for CLI and how amazing it is at taking your command line skills to the next level. Join me at GitHub Universe next month to see it in action.
And if you can't make it in person, virtual passes are free and open to everyone. Register here.
If you have any questions about the gh cli, feel free to post them below and I'll do my best to answer them. 😄
Top comments (3)
I have recently used GitHub CLI for some scripting and while I found it very useful, a few things bothered me. Not all commands can be used with the "--json" and "-q" parameters, which is not very convenient for scripting. Commands that create things (repo, workflow runs) don't return the id of the thing they create. I wish GitHub CLI would be more similar to Azure CLI on these matters.
these are such great points! I'll be sure to bring this back to the CLI team!
@ladykerr I wrote an article about using GitHub CLI (and Azure CLI) to create what I call an "Azure-ready GitHub repository" i.e. scripting the creation and configuration of a repository with a GitHub Actions workflow that can authenticate to Azure 👉 techwatching.dev/posts/scripting-a... . In the conclusion , I gave the same feedback about GitHub CLI, great but some things to improve.