GitHub CLI Commands: The Essential Guide

The GitHub CLI (command-line interface) is a tool that lets you manage GitHub repositories, issues, pull requests, and more directly from your terminal. You use it by typing commands like gh repo create or gh pr list, and it returns the same information you would see on the GitHub website. This guide covers the most common commands, how to install and authenticate, and answers frequent questions.

What Is GitHub CLI and Why Use It?

GitHub CLI, often called gh, is an official open-source tool from GitHub that brings the GitHub workflow into your command line. Instead of switching between your terminal and a web browser, you can create repositories, open pull requests, review code, and manage issues without leaving your coding environment. It is especially useful for developers who work with Git daily, as it reduces context switching and allows for scripting and automation. The tool works on Windows, macOS, and Linux, and it supports both GitHub.com and GitHub Enterprise Server.

Installing and Authenticating

Installation varies by operating system. On macOS with Homebrew, run brew install gh. On Windows, you can use winget install --id GitHub.cli or download the MSI installer from the official releases page. On Linux, you can use your package manager (like sudo apt install gh on Debian/Ubuntu) or download the binary. After installation, you must authenticate by running gh auth login. This command guides you through a browser-based OAuth flow or lets you paste a personal access token. You can check your authentication status with gh auth status.

Core Commands for Repositories

Here are the most frequently used repository commands:

• gh repo create <name> – Creates a new repository. Add --public or --private to set visibility, and --clone to clone it locally.
• gh repo clone <owner>/<repo> – Clones a repository from GitHub.
• gh repo view – Displays the repository description, README, and recent activity.
• gh repo fork – Creates a fork of the current repository under your account.
• gh repo list – Lists repositories you own or have access to, with filters like --owner and --language.

For example, gh repo create my-project --public --clone creates a new public repository and clones it to your current directory.

Working with Issues and Pull Requests

Issues and pull requests are central to collaboration on GitHub. The CLI gives you full control:

• gh issue create – Opens an interactive prompt to create an issue. You can specify title, body, labels, and assignees.
• gh issue list – Lists open issues. Use --label to filter by label and --assignee to filter by assignee.
• gh pr create – Creates a pull request from the current branch. It will prompt for a title and body, and you can add --base and --head to specify branches.
• gh pr list – Shows open pull requests. Add --state merged to see merged PRs.
• gh pr checkout <number> – Switches to the branch of a pull request locally.
• gh pr review – Submits a review (approve, request changes, or comment).

For example, gh pr create --title "Fix bug" --body "Closes #12" creates a PR that references issue #12.

Managing Workflows and Actions

GitHub Actions are automated workflows. With the CLI you can:

• gh workflow list – Lists all workflows in the repository.
• gh workflow run <workflow> – Triggers a workflow run manually.
• gh run list – Shows recent workflow runs.
• gh run view <run-id> – Displays details of a specific run, including logs.
• gh run watch – Watches a run until it completes.

This is handy when you want to trigger a deployment or check the status of a CI/CD pipeline without opening the browser.

Common Problems and How to Fix Them

One common issue is authentication errors. If you see HTTP 401 or Bad credentials, run gh auth login again. Another issue is the CLI not recognizing your repository – make sure you are inside a Git repository or use --repo owner/name to specify the repository. If commands are slow, check your network connection or try using GH_TOKEN environment variable for authentication in scripts. For Windows users, PowerShell may have trouble with aliases; use gh.exe or add the directory to your PATH.

Comparison: GitHub CLI vs. Git Commands vs. GitHub Desktop

Git is the underlying version control system, and its commands (like git commit, git push) handle local and remote Git operations. GitHub CLI wraps GitHub-specific features (issues, PRs, Actions) on top of Git. GitHub Desktop is a graphical application that provides a visual interface for Git and GitHub, but it lacks the scripting power and speed of the CLI. The CLI is ideal for developers who prefer the terminal and want to automate tasks. GitHub Desktop is better for beginners or those who prefer a GUI. You can use all three together; they are not mutually exclusive.

Frequently Asked Questions

How do I see all available commands?

Run gh help to see a list of top-level commands. For help on a specific command, use gh <command> --help. For example, gh pr --help shows all pull request subcommands.

Can I use GitHub CLI with GitHub Enterprise?

Yes. During gh auth login, choose “GitHub Enterprise Server” and enter your server’s URL. You may need to set the GH_HOST environment variable if you use multiple hosts.

How do I create a repository and push my existing code?

Navigate to your project folder, run gh repo create <name> --public --source=. --remote=origin. This creates the repository on GitHub and adds a remote named origin. Then push your code with git push -u origin main.

Is GitHub CLI free?

Yes, GitHub CLI is free and open source. You only need a GitHub account. Some advanced features (like private repositories with more collaborators) may require a paid GitHub plan, but the CLI itself is free.

What is the difference between gh pr create and gh pr checkout?

gh pr create creates a new pull request from your current branch. gh pr checkout switches your local repository to the branch of an existing pull request, allowing you to review or test it locally.

Can I use GitHub CLI in scripts?

Yes, that is a major advantage. You can use gh in shell scripts, CI pipelines, and cron jobs. Use --jq to parse JSON output and --template to format it. For example, gh pr list --json number,title --jq '.[].title' prints just the titles of open PRs.

Related

• Ireland vs UK for Starting an AI Company: How to Choose
• CI Green But Tests Failed: Optional Gate Explained
• Problems Joining FaceTime Group Call? Fixes