gh

Boost your productivity & automate tasks when working with GitHub, all from the comfort of your CLI.

Usage no npm install needed!

<script type="module">
  import gh from 'https://cdn.skypack.dev/gh';
</script>

README

DEPRECATED

Node GH

Boost your productivity & automate tasks when working with GitHub, all from the comfort of your CLI.

Table of contents

Contributors

Getting Started
Available Commands
Pull Requests `pr`
Issues `is`
Repos `re`
Gists `gi`
User `us`
Notifications `nt`
Milestones `ms`
Alias `al`

General

Install

npm install -g gh

Usage

  • Most commands require you to use a developer key
  • We automate the process for you the first time you run a command
  • Instructions on manually adding a developer key for extra security

Simple example: list prs for current repo

gh pr

Contributors

Huge thanks goes to these wonderful people (emoji key):


Eduardo Lundgren
πŸ’» πŸ› πŸ“– πŸ’¬ πŸš‡ πŸ”Œ ⚠️ πŸ‘€ πŸ€”
Zeno Rocha
πŸ’» πŸ› πŸ“– πŸ’¬ πŸš‡ πŸ”Œ ⚠️ πŸ‘€ πŸ€” πŸ–‹
Henrique Vicente
πŸ’» πŸ› πŸ’¬ πŸš‡ πŸ”Œ ⚠️ πŸ‘€ πŸ›‘οΈ πŸ€”
Ryan Garant
πŸ› πŸ’¬ πŸš‡ πŸ”Œ ⚠️ πŸ‘€ πŸ›‘οΈ πŸ€”
Bruno Coelho
πŸ’» πŸ›
Dustin Ryerson
πŸ’»
Drew Brokke
πŸ’» πŸ€”

Jose Ignacio
πŸ’»
Rodrigo Vidal
πŸ’»
Hamza Baig
πŸ’»
Gregory Amerson
πŸ’» πŸ›
Tom Rochette
πŸ’» πŸ› πŸš‡
Mike Roberts
πŸ’»
Snyk bot
πŸ’»

BlockchainDeveloper
πŸ’»
JoΓ£o Paulo Bochi
πŸ’»
Matthew Elphick
πŸ’»
Nate Cavanaugh
πŸ’»
Peter Dave Hello
πŸ’»
Matt DesLauriers
πŸ’»
oughter
πŸ’»

Adrian Macneil
πŸ’»
Aleksey Ostapenko
πŸ’»
Aliaksei
πŸ’»
Andrey
πŸ’»
AndrΓ© de Oliveira
πŸ’»
Brandon Patram
πŸ’»
Chema Balsas
πŸ’»

Christian Schlensker
πŸ’»
Ciro Nunes
πŸ’»
Denis Efremov
πŸ’»
Henri Cavalcante
πŸ’»
Jaka Hudoklin
πŸ’»
JosΓ© F. Romaniello
πŸ’»
Joshua Wu
πŸ’»

Kevon Eaglin
πŸ’»
M. TarΔ±k Yurt
πŸ’»
Marcus Buffett
πŸ’»
RandΡ•on
πŸ’»
Alex Hall
πŸ’»
Rossi Oddet
πŸ’»
Ryan Schmukler
πŸ’»

Stephen Williams
πŸ’»
Trevor Bortins
πŸ’»
Whitney Young
πŸ’»
Xavier RENE-CORAIL
πŸ’»
YAMAMOTO Yuji
πŸ’»
Sam Mikes
πŸ’»
Tiju Thomas
πŸ’»

Zev Averbach
πŸ’» πŸ›
Aaron Jones
πŸ›
Ryan Schumacher
πŸ›
Rob Dodson
πŸ›
Derek Sifford
πŸ›
rachidbch
πŸ›
Liraz Siri
πŸ›

Zsolt Balogh
πŸ› πŸ“–
Iliyan Peychev
πŸ›
Dante Wang
πŸ›
Raymond AugΓ©
πŸ›
Mohamed Bassem
πŸ›
Rich Sezov
πŸ›
Jason Kuhrt
πŸ›

gon138
πŸ›
Maxim Novikov
πŸ›
Anders D. Johnson
πŸ›
Gabriel Izaias
πŸ›
Myles McNamara
πŸ›
Gilad Peleg
πŸ›
Yoshua Wuyts
πŸ›

Marc Lundgren
πŸ›
Julio Camarero
πŸ›
Marcellus Tavares
πŸ›
Sergio Gonzalez
πŸ›
Djalma AraΓΊjo
πŸ›
Bruno Basto
πŸ›
Jason Pincin
πŸ›

Joel Kuzmarski
πŸ›
Nadeem Bitar
πŸ“–
Cleydyr Bezerra de Albuquerque
πŸ›
Ramon Pires da Silva
πŸ”Œ
Patrick WeingΓ€rtner
πŸ’»
Gabriel Ramos
πŸ’»
Manuel de la PeΓ±a
πŸ’»

Jose M Vidal
πŸ›
Saulo Vallory
πŸ’»
Hernan Fernandez
πŸ’»
Aaron Berry
πŸ’»
InΓ‘cio Nery
πŸ› πŸ’»
Marcus Bizal
πŸ›
Julien Castelain
πŸ› πŸ’»

Andrew Bradley
πŸ›

This project follows the all-contributors specification. Contributions of any kind welcome!

Contributing

For detailed instructions, check Contributing. Don't miss the source code reports.

History

For detailed changelog, check Releases.

License

BSD-3-Clause

Demonstration

Terminal Demo

Supported Node Versions:

We support the node versions that the Node.js organization supports which as of now is Node v6 & up.

LTS Schedule

Authentication

Under the hood, we are using @octokit/rest to work with the GitHub API The method of authentication that we use with octokit, is a personal access token You have two options here: 1. Run gh which will start the authentication process & generate the token for you automatically - Though they are hidden, the downside of this is having to type your user & pass - Supports 2fa 2. Manually generate your personal token & add it to your ~/.gh.json

Available commands

gh help

List all comands options.

gh help --all

List specific command options.

gh help <command>

Global flags

Option Usage Type
--verbose Optional Boolean
--insane Optional Boolean
--no-color Optional Boolean
--no-hooks Optional Boolean

The verbose flag is useful for debugging issues. The insane flag is a more complete verbose flag, which leaks more privacy sensitive data by default.

Pull requests

gh pull-request

Alias: gh pr

PR: Info

Option Usage Type
-u, --user Required String
-I, --info Required Boolean
-n, --number Required String
-r, --repo Optional String
-u, --user Optional String

Get information about a pull request.

gh pr --info 1

PR: List

Option Usage Type
-l, --list Required Boolean
-a, --all Optional Boolean
-O, --org Optional String
-m, --me Optional Boolean
-d, --detailed Optional Boolean
--direction Optional [asc, desc]
--date Optional String
-b, --branch Optional String
--remote Optional String
-r, --repo Optional String
--sort Optional [created, updated, popularity, long-running, complexity]
-S, --state Optional [open, closed]
-u, --user Optional String
--link Optional Boolean
  • user is owner of the repository, it is the authenticated user by default.
  • remote is the name of the remote configuration in a git directory, i.e. origin, upstream.
  • Therefore, it only makes sense when this command is run in a git directory.
  • To turn off pretty printing of output in a table add "pretty_print": false to your ~/.gh-json config
  • To adjust pagination rules

Examples

Shortcut for listing open pull requests for the current repository

gh pr

List open pull requests for all branches from all your repositories.

gh pr --list --all

List open pull requests for all branches in all repositories belonging to the "github" organization.

gh pr --list --all --org github

List open pull requests sent by logged user on current repository.

gh pr --list --me

List open pull requests in node-gh/gh repository.

gh pr --list --user node-gh --repo gh

List open pull requests with link and content.

gh pr --list --detailed

List open pull requests for a branch.

gh pr --list --branch master

List open pull requests and sort them by popularity (comment count).

gh pr --list --sort popularity

List open pull requests and sort them by asc long-running (old but still active).

gh pr --list --sort long-running --direction asc

List open pull requests and sort them by complexity (complexity is calculated based on number of additions, deletions, changed files, comments and review comments).

gh pr --list --sort complexity

List open pull requests with their link

gh pr --list --link

List open pull requests with a formatted date (Any string that the moment library's formatter accepts should work: https://momentjs.com/docs/#/displaying/format/).

gh pr --list --date "dddd, MMMM Do YYYY, h:mm:ss a"

PR: Merge or Rebase

Option Usage Type
-f, --fetch Required Boolean
-M, --merge Required Boolean
-R, --rebase Required Boolean
-n, --number Optional Number
-b, --branch Optional String
--draft Optional Boolean
--remote Optional String
-r, --repo Optional String
-u, --user Optional String

Omitting --number will try to guess the pull number from branch name e.g. pr-1 results in --number 1. Omitting --branch will merge or rebase into config.default_branch.

Examples

Shortcut for fetching pull request and checkout into a new branch pr-1.

gh pr 1

Merge or rebase pull request into a local branch.

gh pr 1 --fetch --merge

gh pr 1 --fetch --rebase

Merge or rebase pull request into branch dev.

gh pr 1 --fetch --rebase --branch dev

gh pr 1 --fetch --merge --branch dev

PR: Comment

Option Usage Type
-c, --comment Required String
-n, --number Required Number
--remote Optional String
-r, --repo Optional String
-u, --user Optional String

Examples

Comment on a pull request.

gh pr 1 --comment "Merged, thank you!"

Submit a pull request using your default editor by passing an empty --comment

gh pr 1 --comment

PR Forward

Option Usage Type
--fwd Required String
-n, --number Required Number

Omitting a value for --fwd fallbacks to the default_pr_forwarder key found in your config file.

Examples

Forward a pull request to another reviewer.

gh pr 1 --fwd username

PR: Open or Close

Option Usage Type
-o, --open Required Boolean
-C, --close Required Boolean
-n, --number Required Number
--remote Optional String
-r, --repo Optional String
-u, --user Optional String

Examples

Open a pull request.

gh pr 1 --open

Close a pull request.

gh pr 1 --close

Close multiple pull requests.

gh pr --close --number 1 --number 2

Open multiple pull requests.

gh pr --open --number 1 --number 2

Open or close a pull request that you've sent to someone.

gh pr 1 --close --user eduardolundgren

PR: Submit

Option Usage Type
-s, --submit Required String
-b, --branch Optional String
-D, --description Optional String
-i, --issue Optional Number
-r, --repo Optional String
-t, --title Optional String

Omitting a value for --submit fallbacks to the default_pr_reviewer key found in your config file. Omitting --title will submit a pull request using the last commit message as title.

Examples

Submit a pull request using the current branch to the repository owner or organization.

gh pr --submit eduardolundgren --title 'Fix #32' --description 'Awesome fix'

Submit a pull request using your default editor by passing an empty --title and or --description

gh pr --submit eduardolundgren --title --description

Submit a pull request using the current branch to dev branch.

gh pr --submit eduardolundgren --branch dev

Submit a pull request from a issue.

gh pr --submit eduardolundgren --issue 150

Submit a pull request in draft state.

gh pr --submit eduardolundgren --draft

PR: Open in Browser

Option Usage Type
-B, --browser Required Boolean
-n, --number Required Number
-u, --user Optional String
-r, --repo Optional String

Examples

Open GitHub pull request page in the browser.

gh pr 100 --browser

Notifications

gh notification

Alias: gh nt

Notifications: Latest

Option Usage Type
-l, --latest Required Boolean
--remote Optional String
-r, --repo Optional String
-u, --user Optional String
--date Optional String

Examples

Shortcut for displaying the latest activities on the current repository.

gh nt

Display the latest activities on a certain repository.

gh nt --latest --user eduardolundgren --repo node-gh

Diplay notifications with a formatted date (Any string that the moment library's formatter accepts should work: https://momentjs.com/docs/#/displaying/format/).

gh nt --date "dddd, MMMM Do YYYY, h:mm:ss a"

Notifications: Watch

Option Usage Type
-w, --watch Required Boolean
--remote Optional String
-r, --repo Optional String
-u, --user Optional String

Examples

Watch for any activity on the current repository.

gh nt --watch

Watch for any activity on a certain repository.

gh nt --watch --user eduardolundgren --repo node-gh

Issues

gh issue

Alias: gh is

Issue: Create

Option Usage Type
-N, --new Required Boolean
-t, --title Required String
-A, --assignee Optional String
-L, --labels Optional String
-m, --message Optional String
--remote Optional String
-r, --repo Optional String
-u, --user Optional String

Examples

Shortcut for creating a new issue on the current repository.

gh is 'Node GH rocks!' 'Body with **Markdown** support'

Create a new issue using your default editor by passing an empty --message (also works with an empty title)

gh is --new --title 'Node GH rocks!' --message

Create a new issue on a certain repository.

gh is --new --title 'Node GH rocks!' --message 'Body with **Markdown** support' --user eduardolundgren --repo node-gh

Create a new issue with labels.

gh is --new --title 'Node GH rocks!' --labels bug,question,test

Create a new issue and assign it to someone.

gh is --new --title 'Node GH rocks!' --assignee zenorocha

Issue: Comment

Option Usage Type
-c, --comment Required String
-n, --number Required Number
--remote Optional String
-r, --repo Optional String
-u, --user Optional String

Examples

Comment on an issue of the current repository.

gh is 1 --comment 'Node GH rocks!'

Comment on an issue using your default editor by passing an empty --comment (also works with an empty title)

gh is 1 --comment

Comment on an issue of a certain repository.

gh is 1 --comment 'Node GH rocks!' --user eduardolundgren --repo node-gh

Issue: Open or Close

Option Usage Type
-o, --open Required Boolean
-C, --close Required Boolean
-n, --number Required Number
--remote Optional String
-r, --repo Optional String
-u, --user Optional String

Examples

Open an issue.

gh is 1 --open

Close an issue.

gh is 1 --close

Close multiple issues.

gh is --close --number 1 --number 2

Open multiple issues.

gh is --open --number 1 --number 2

Open or close an issue that you've sent to someone.

gh is 1 --close --user eduardolundgren

Issue: List

Option Usage Type
-l, --list Required Boolean
-a, --all Optional Boolean
-A, --assignee Optional String
--date Optional String
-d, --detailed Optional Boolean
-L, --labels Optional String
-M, --milestone Optional [Number, String]
--remote Optional String
-r, --repo Optional String
-S, --state Optional [open, closed]
-u, --user Optional String

Examples

Shortcut for listing all issues on the current repository.

gh is

List all issues from all repositories.

gh is --list --all

List issues assigned to someone.

gh is --list --assignee zenorocha

List issues with link and content.

gh is --list --detailed

List only closed issues on the current repository.

gh is --list --state closed

List issues with a formatted date (Any string that the moment library's formatter accepts should work: https://momentjs.com/docs/#/displaying/format/).

gh is --list --date "dddd, MMMM Do YYYY, h:mm:ss a"

List issues filtered by milestone title.

gh is --list --milestone "milestone title"

List issues that contains labels todo and bug.

gh is --list --labels todo,bug

List all issues on a certain repository.

gh is --list --user eduardolundgren --repo node-gh

Issue: Open in Browser

Option Usage Type
-B, --browser Required Boolean
-n, --number Required Number
-u, --user Optional String
-r, --repo Optional String

Examples

Shortcut for opening GitHub issue page in the browser.

gh is 100

Open GitHub issue page in the browser.

gh is 100 --browser

Issue: Lock

Option Usage Type
--lock Required Boolean
--lock-reason Optional [off-topic, too heated, resolved, spam]
-n, --number Required Number
--remote Optional String
-r, --repo Optional String
-u, --user Optional String

Examples

Lock issue on the current repository.

gh is 1 --lock

Lock issue on the current repository with a reason.

gh is 1 --lock --lock-reason resolved

Issue: Search

Option Usage Type
-s, --search Required Boolean
-a, --all Optional Boolean
-d, --detailed Optional Boolean
-r, --repo Optional String
-u, --user Optional String

Examples

Search issues in current repository

gh is --search 'term'

Search issues in all repositories for a user

gh is --all --user node-gh --search 'term'

Search issues in a repository for a user

gh is  --user node-gh --repo gh --search 'term'

Search issues in a repository for a user with link and content

gh is  --user node-gh --repo gh --search 'term'

Search issues with github filters

gh is  --user node-gh --repo gh --search 'updated:<=2013-05-24'

Issue: Assign

Option Usage Type
--assign Required Boolean
-A, --assignee Required String
-n, --number Required Number
-r, --repo Optional String
-u, --user Optional String

Examples

Assign an issue on the current repository to a user.

gh is --assign --assignee zenorocha --number 1

Assign an issue on a specific repository to a user.

gh is --assign --assignee zenorocha --number 1 --user eduardolundgren --repo gh

Repo

gh repo

Alias: gh re

Repo: Open in Browser

Option Usage Type
-B, --browser Required Boolean
-u, --user Optional String
-r, --repo Optional String

Examples

Shortcut for opening the GitHub repository page in the browser.

gh re

Open GitHub repository page in the browser.

gh re --browser --user eduardolundgren --repo node-gh

Repo: List

Option Usage Type
-l, --list Required Boolean
-d, --detailed Optional Boolean
-u, --user Optional String
-t, --type Optional [all, owner, public, private, member]
--date Optional String

Examples

List all repositories.

gh re --list

List all private repositories.

gh re --list --type private

List all repositories from someone.

gh re --list --user zenorocha

List open repositories with a formatted date (Any string that the moment library's formatter accepts should work: https://momentjs.com/docs/#/displaying/format/).

gh re --list --detailed --date "dddd, MMMM Do YYYY, h:mm:ss a"

Repo: Create

Option Usage Type
-N, --new Required String
-O, --organization Optional String
-c, --clone Optional Boolean
-t, --type Optional [private]
--init Optional Boolean
--gitignore Optional String
--homepage Optional String
--description Optional String

Examples

Create a new GitHub repository and clone on the current directory.

gh re --new foo --clone

Create a new GitHub repository based on the name of the current directory & init with a README

gh re --new --clone --init

Create a new GitHub repository for an organization.

gh re --new foo --organization node-gh

Create a new GitHub repository using .gitignore template for Ruby.

gh re --new gemified --gitignore Ruby

Create a new private repository on GitHub, initializing it with a initial commit of the README.

gh re --new foo --init --type private

Repo: Fork

Option Usage Type
-f, --fork Required String
-u, --user Required String
-O, --organization Optional String

Examples

Fork a GitHub repository.

gh re --fork repo --user user

Fork a GitHub repository into the node-gh organization.

gh re --fork repo --user user --organization node-gh

Repo: Delete

Option Usage Type
-D, --delete Required String
-u, --user Required String

Example

Delete a repository of the logged user.

gh re --delete foo

Repo: Clone

Option Usage Type
-c, --clone Required String
-r, --repo Required String
-O, --organization Optional String
-P, --protocol Optional String
-u, --user Optional String

If you have custom ssh config, you can add "api": { "ssh_host": "custom-name", ... } to your .gh.json file.

Examples

Clone a repository.

gh re --clone --repo gh

Clone a repository from a specific user using HTTPS protocol.

gh re --clone --user eduardolundgren --repo gh --protocol https

Repo: Create Label

Option Usage Type
-C, --color Required String
-L, --label Required Boolean
-N, --new Required String
-r, --repo Required String
-O, --organization Optional String
-u, --user Optional String

Examples

Create a label for a repository (color is a hex code with or without literal hex symbol).

gh re --label --new bug --color '#7057ff' --repo gh

Create a label for a user's repository.

gh re --label --new bug --color '#7057ff' --user eduardolundgren --repo gh

Repo: Delete Label

Option Usage Type
-L, --label Required Boolean
-D, --delete Required String
-r, --repo Required String
-O, --organization Optional String
-u, --user Optional String

Examples

Delete a label from a repository.

gh re --label --delete bug --repo gh

Delete a label from a user's repository.

gh re --label --delete bug --user eduardolundgren --repo gh

Repo: List Labels

Option Usage Type
-L, --label Required Boolean
-l, --list Required Boolean
-r, --repo Required String
-O, --organization Optional String
-u, --user Optional String

Examples

List labels for a repository.

gh re --label --list --repo gh

List labels for a user's repository.

gh re --label --list --user eduardolundgren --repo gh

Repo: Update Label

Option Usage Type
-C, --color Required String
-L, --label Required Boolean
-r, --repo Required String
-U, --update Required String
-O, --organization Optional String
-u, --user Optional String

Examples

Update a label for a repository (color is a hex code with or without literal hex symbol).

gh re --label --update bug --color color --repo gh

Update a label for a user's repository.

gh re --label --update bug --color color --user eduardolundgren --repo gh

Repo: Search

Find repositories via various criteria. Repository search looks through the projects you have access to on GitHub. You can filter the results using GitHub's search qualifiers. Examples:

Option Usage Type
-s, --search Required Boolean
-d, --detailed Optional Boolean
-u, --user Optional String
-r, --repo Optional String
-O, --organization Optional String
-t, --type Optional [all, owner, public, private, member]

Examples

Search private repositories you have access to with the term "secret".

gh re --search secret --type private

OR

gh re --search secret is:private

Matches repositories from GitHub org showing detailed results.

gh re --detailed -o github --search octocat

OR

gh re --detailed --search octocat org:github

Gists

gh gists

Alias: gh gi

Gist: Open in Browser

Option Usage Type
-B, --browser Required Boolean
-u, --user Optional String
-i, --id Optional String

Examples

Shortcut for opening your Gists in the browser.

gh gi

Open a Gist in the browser.

gh gi --browser --id 5991877

Gist: List

Option Usage Type
-l, --list Required Boolean
-u, --user Optional String
--date Optional String

Examples

List all gists.

gh gi --list

List all gists from someone.

gh gi --list --user brunocoelho

List gists with a formatted date (Any string that the moment library's formatter accepts should work: https://momentjs.com/docs/#/displaying/format/).

gh gi --list --date "dddd, MMMM Do YYYY, h:mm:ss a"

Gist: Create

Option Usage Type
-N, --new Required String
-c, --content Optional String
-d, --description Optional String
-p, --private Optional Boolean

Examples