Code-REF.USE

Github CLI

A quick reference to Github CLI, an open-source command line tool that enables GitHub on your terminal.

#Getting Started

#Installation

Windows

Install Upgrade
Install Upgrade
WinGet winget install --id Github.cli winget upgrade --id GitHub.cli
Scoop scoop install gh scoop update gh
Choco choco install gh choco upgrade gh

Mac OS

Install Upgrade
Install Upgrade
Brew brew install gh brew upgrade gh
MacPorts sudo port install gh sudo port selfupdate && sudo port upgrade gh

Linux

See the install instructions for other Linux distributions.

Installation Script:

type -p curl >/dev/null || (sudo apt update && sudo apt install curl -y)
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
&& sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg \
&& echo "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/null \
&& sudo apt update \
&& sudo apt install gh -y

#Basic Usage

Help and Documentation

Display command options:

Command Description
gh help [command] Help provides help for any command in the application. Simply type gh help [path to command] for full details.

Authentication

Command Description
gh auth login Default authentication with web-based browser
gh auth logout Removes the authentication configuration for a host
gh auth refresh Expand or fix the permission scopes for stored credentials
gh auth setup-git Configures git to use GitHub CLI as a credential helper
gh auth status Verifies and displays information about your authentication state
gh auth token Print the auth token gh is configured to use

With Github token:

$ gh auth --with-token < token.txt

#Repository Management

General

Command Description
gh repo create Create a new GitHub repository
gh repo list [target] List repositories owned by a user or organization

Targets

Command Description
gh repo archive [repo] Archive a GitHub repository
gh repo clone [dir] Clone a GitHub repository locally
gh repo delete [repo] Delete a GitHub repository
gh repo deploy-key Manage deploy keys in a repository
gh repo edit [repo] Edit repository settings
gh repo fork [repo] Create a fork of a repository
gh repo rename [name] Rename a GitHub repository
gh repo set-default [repo] This command sets the default remote repository
gh repo sync [dest-repo] Sync destination repository from source repository
gh repo view [repo] Display the description and the README of a GitHub repository.

#Issues

Search Issues

Command Description
gh search issues [query] Search for issues on GitHub

Examples

# search issues matching set of keywords "readme" and "typo"
$ gh search issues readme typo

# search issues matching phrase "broken feature"
$ gh search issues "broken feature"

# search issues and pull requests in cli organization
$ gh search issues --include-prs --owner=cli

# search open issues assigned to yourself
$ gh search issues --assignee=@me --state=open

# search issues with numerous comments
$ gh search issues --comments=">100"

# search issues without label "bug"
$ gh search issues -- -label:bug

#Pull Requests

Pull Request Actions

Command Description
gh pr create Create a pull request on GitHub
gh pr list List pull requests in a GitHub repository
gh pr status Show status of relevant pull requests

Example

$ gh pr status

Sample Output:

Current branch
  #12 Remove the test feature [user:patch-2]
   - All checks failing - Review required

Created by you
  You have no open pull requests

Requesting a code review from you
  #13 Fix tests [branch]
  - 3/4 checks failing - Review required
  #15 New feature [branch]
   - Checks passing - Approved

#Github Actions

General Actions

Command Description
gh workflow disable Disable a workflow, preventing it from running or showing up when listing workflows
gh workflow enable Enable a workflow, allowing it to be run and show up when listing workflows
gh workflow list List workflow files, hiding disabled workflows by default
gh workflow run Create a workflow_dispatch event for a given workflow
gh workflow view View the summary of a workflow

Running Actions

Command Description
gh run cancel Cancel a workflow run
gh run delete Delete a workflow run
gh run download Download artifacts generated by a GitHub Actions workflow run
gh run list List recent workflow runs
gh run rerun Rerun an entire run, only failed jobs, or a specific job from a run
gh run view View a summary of a workflow run
gh run watch Watch a run until it completes, showing its progress

#Aliases

General Alias Settings

Command Description
gh alias delete Delete set aliases
gh alias import Import aliases from the contents of a YAML file
gh alias list Prints out all of the aliases gh is configured to use
gh alias set Define a word that will expand to a full gh command when invoked

#Releases

General Actions

Command Description
gh release create Create a new GitHub Release for a repository
gh release list List releases in a repository

Target Commands

Command Description
gh release delete Delete a release
gh release delete-asset Delete an asset from a release
gh release download Download assets from a GitHub release
gh release edit Edit a release
gh release upload Upload asset files to a GitHub Release
gh release view View information about a GitHub Release

#Configuration

Targeted Settings

Command Description
gh config clear-cache Clear the cli cache
gh config get Print the value of a given configuration key
gh config list Print a list of configuration keys and values
gh config set Update configuration with a value for the given key