Github CLI

Getting Started

Installation

Windows

Tool	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`

{.show-header}

Mac OS

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

{.show-header}

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