Articles

GitHub CLI Tutorial: Complete Guide to gh Commands

Are you tired of bouncing between browser tabs to merge a pull request or check an issue? GitHub CLI lets you do everything from your terminal without context switching.

  • Free course

    Learn GitHub: Introduction

    Learn how to use GitHub, a service that allows you to host and share your code.
    • Beginner Friendly.
      1 hour
  • Course

    Learn Git & GitHub

    Use our beginner friendly Git course to integrate Git and GitHub and manage versions of your projects using Git branches.
    • With Certificate
    • Beginner Friendly.
      4 hours

What is GitHub CLI?

GitHub CLI is a command-line tool that helps us interact with GitHub directly from the terminal. Instead of opening GitHub in a browser, we can use gh commands to manage repositories, create pull requests, review issues, trigger workflows, and perform other operations without leaving the code environment. Key features of GitHub CLI include:

  • GitHub Actions support: Monitor, rerun, and debug workflows with basic commands.

  • Custom aliases: Create shorthand commands for repetitive tasks or multi-step scripts.

  • Scriptable automation: Chain gh commands into scripts for CI, deployment, or project housekeeping.

  • Context awareness: Automatically works with the current repo and branch, minimizing flags and setup.

  • Cross-platform support: Works on macOS, Windows, and Linux with consistent behavior.

Before we start using these features, we need to install and set up GitHub CLI on our machine.

How to install and set up GitHub CLI

GitHub CLI supports all major operating systems and is installed in only a couple of steps. Once installed, you’ll connect it to your GitHub account to interact with your repos.

Installing GitHub CLI on Windows

You can install GitHub CLI on Windows using Winget, the Windows Package Manager. Open the command prompt or PowerShell and run: 

winget install --id GitHub.cli

This command tells Winget to fetch and install the official GitHub CLI package.

Note: If you don’t have Winget installed or prefer not to use it, you can download the latest .msi installer from the official GitHub CLI website.

After installation, confirm it’s working by running: 

gh --version

Installing GitHub CLI on macOS

If you’re on macOS and have Homebrew installed, run: 

brew install gh

Then verify the installation: 

gh --version

Installing GitHub CLI on Linux

GitHub CLI is available through most major Linux package managers.

For Debian/Ubuntu, use the following command: 

sudo apt install gh

For Fedora use: 

sudo dnf install gh

For other distributions, follow the manual installation instructions on GitHub’s official CLI repo.

Authenticating with your GitHub account

Once installed, run the following to authenticate: 

gh auth login

The CLI will walk you through the following:

  • Selecting GitHub.com or GitHub Enterprise
  • Choosing HTTPS or SSH
  • Logging in via browser or personal access token

You don’t need to remember any flags, but make sure to follow the prompts.

Verify the authentication status

To make sure everything is working, use: 

gh auth status

If everything’s configured correctly, you’ll see confirmation that you’re logged in and Git operations are set up.

Now that we’ve installed GitHub CLI, let’s look at common commands.

Overview of common GitHub CLI commands

Here are some of the most used gh commands. These are the building blocks of most workflows you’ll use with GitHub CLI. Each command generally follows this structure: 

gh [command] [subcommand] [flags/options]

In this syntax,

  • gh: This is the GitHub CLI command itself.

  • command: This refers to the category of the task you’re performing. For example: repo, issue, pr, run.

  • subcommand: The specific action you want to perform within that group. For example: create, clone, view, list, status

  • flags/options: Optional arguments that refine the command’s behavior. These usually start with -- (like --public, --state closed, etc.)

Here’s a preview of the most frequently used GitHub CLI commands:

  • To create a repository: gh repo create
  • To list issues: gh issue list
  • To create a pull request (PR): gh pr create

To see all available commands and options, we can run: 

gh help

Now that you’ve got the basic structure, let’s see its usage.

Managing repositories with GitHub CLI

The repo group in GitHub CLI handles everything related to repositories. This is handy when you’re starting a new project or contributing to someone else’s work. Here are some of the core repository commands you’ll use:

Create a new repository

To create a repository, we use: 

gh repo create

This command walks you through an interactive setup where you can:

  • Set the repository name
  • Choose visibility (public or private)
  • Initialize with README, .gitignore, or a license
  • Push an existing local repo to GitHub

You can also pass flags for a non-interactive setup: 

gh repo create my-project --public --source=. --push

Clone a repository

To clone a repository, use: 

gh repo clone owner/repo-name

This pulls the entire repository to your local machine and sets up the remote automatically.

View repository info

To quickly check details about a repository: 

gh repo view

By default, it shows info for the current repo, including description, visibility, and README. Add --web to open it in the browser or --json to get structured data.

Delete a repository

Be careful, as this action is permanent and cannot be undone. To delete a repo (that you own): 

gh repo delete owner/repo-name

You’ll be asked to confirm before deletion.

Working with issues using GitHub CLI

The issue group in GitHub CLI lets you manage GitHub issues, whether you create new ones, review bugs, assign tasks, or leave comments.

Create a new issue 

gh issue create

This opens an interactive prompt where you can:

  • Enter the title and description
  • Add labels
  • Assign the issue to someone (including yourself)
  • Set a milestone (if available)

To skip the prompts and use flags: 

gh issue create --title "Bug: crash on save" --body "Steps to reproduce..." --label bug

List issues 

gh issue list

This shows all open issues in the current repository. You can filter by state, label, assignee, or author using flags: 

gh issue list --label bug --state closed 
gh issue list --assignee @me

View a specific issue 

gh issue view ISSUE_NUMBER

You’ll see the title, body, labels, and comments. Add --comments to include all discussion threads, or --web to open the issue in your browser.

Managing pull requests with GitHub CLI

The pr group in GitHub CLI covers everything you need to work with pull requests. Here are some common operations.

Create a PR 

gh pr create

This command prompts you to:

  • Choose a base and compare branches
  • Add a title and description
  • Optionally mark it as a draft

It can also be done non-interactively: 

gh pr create --base main --head feature-branch --title "Add login form" --body "Implements login with basic validation"

List PRs 

gh pr list

By default, this shows open PRs in the current repo. This can also filter with: 

gh pr list --state closed --author username --label enhancement

View a PR 

gh pr view PR_NUMBER

Add --web to open it in the browser, or --comments to see all discussion inline.

Check PR status 

gh pr status

This command is useful when you’re working on a feature branch. It shows:

  • Whether there’s an open PR from your branch
  • Incoming PRs that need your review
  • Review requests assigned to you

Merge a PR 

gh pr merge PR_NUMBER

You’ll be prompted to choose between a merge commit, rebase, or squash. You can also specify it with flags: 

gh pr merge 17 --squash --delete-branch

Working with GitHub actions in GitHub CLI

The run group in GitHub CLI helps you interact with GitHub Actions workflows directly from the terminal.

List workflows runs 

gh run list

This shows recent workflow runs for the current repository, including their status (success, failure, in progress). You can add flags to filter by branch, event type, or status: 

gh run list --branch main --status failure

View workflow run details 

gh run view RUN_ID

You can find the RUN_ID from the gh run list output.

View logs

To see logs of a specific run directly in the terminal: 

gh run view RUN_ID --log

This is handy when debugging failed builds or tests without navigating through the UI.

Re-run a workflow 

gh run rerun RUN_ID

You can also re-run the latest failed run: 

gh run rerun –failed

This is especially useful in CI pipelines where flaky tests or race conditions occasionally cause failures.

Customize and automate with aliases and scripts

Aliases that save you time, and scripting that lets you automate repetitive work. Here are some common commands.

Create your shortcuts with aliases

If you find yourself typing the same gh command repeatedly, create a custom alias to make your life easier. It has the following syntax: 

gh alias set [shortcut] '[full gh command]'

For example, this command: 

gh alias set myissues 'issue list --author @me --state open'

Now you can just type: 

gh myissues

To see all your aliases: 

gh alias list

Aliases can even include flags or parameters. You can get creative with them depending on your workflow.

Automate workflows with JSON and scripts

Most gh commands support --json output, which is great for automation and scripting. For example: 

gh pr list --state open --json title,author

If you want to format the output, use jq: 

gh issue list --json number,title --jq '.[] | "\(.number): \(.title)"'

This lets you build shell scripts that:

  • List PRs and issues
  • Parse them
  • Trigger CI/CD workflows
  • Even auto-generate changelogs

So, with GitHub CLI in your toolkit, you can skip the context switching and get more done right from your terminal. It’s a small shift that can make a big difference.

Conclusion

In this article, we explored how GitHub CLI can simplify and speed up your workflow by bringing GitHub features directly into your terminal. From setting up repositories and managing pull requests to customizing aliases and automating tasks, GitHub CLI gives you the control and flexibility to handle everyday GitHub tasks without ever leaving your command line.

If you’re ready to go deeper and start building real-world projects with Git and GitHub, check out the Learn Git & GitHub course on Codecademy.

Frequently asked questions

1. What is GitHub CLI used for?

GitHub CLI (gh) is a command-line tool that lets you interact with GitHub directly from your terminal. It helps create repositories, manage pull requests and issues, view commits, clone projects, and automate workflows.

2. Is GitHub CLI and Git Bash the same?

No, Git Bash is a terminal application for Windows that provides a Bash shell to run Git commands. GitHub CLI is a separate tool that adds GitHub-specific commands (like gh pr create, gh issue list, etc.) to the terminal, working with Git to streamline GitHub operations.

3. How to connect to GitHub via CLI?

To connect, first install GitHub CLI and then run gh auth login. You’ll be guided through a simple authentication flow to sign in with your GitHub account. Once authenticated, you can start using gh commands to interact with your repositories.

Codecademy Team

'The Codecademy Team, composed of experienced educators and tech experts, is dedicated to making tech skills accessible to all. We empower learners worldwide with expert-reviewed content that develops and enhances the technical skills needed to advance and succeed in their careers.'

Meet the full team

Related articles

Learn more on Codecademy

  • Free course

    Learn GitHub: Introduction

    Learn how to use GitHub, a service that allows you to host and share your code.
    • Beginner Friendly.
      1 hour
  • Course

    Learn Git & GitHub

    Use our beginner friendly Git course to integrate Git and GitHub and manage versions of your projects using Git branches.
    • With Certificate
    • Beginner Friendly.
      4 hours
  • Free course

    Learn GitHub: Best Practices

    Learn how to maintain clean code, write better pull requests, and collaborate with the GitHub community.
    • Beginner Friendly.
      < 1 hour
Contents