gh

Node GH

All the power of GitHub in your terminal.

Table of contents

• Install
• Usage
• Contributors
• Contributing
• History
• License
• Demonstration
• Supported Node Versions
• Available commands
  • Pull requests
  • Notifications
  • Issues
  • Repo
  • Gists
  • User
  • Milestone
  • Alias
• Config
• Plugins

Install

[sudo] npm install -g gh

Usage

gh [command] [--flags]

Contributors

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 💻

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

Supported Node Versions:

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

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

1. Info

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

gh pr

• Get information about a pull request.

gh pr --info number

2. 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.

Examples

• Shortcut for listing open pull requests for the current repository.

• To turn off pretty printing of output in a table add "pretty_print": false to your ~/.gh-json config

• 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"

3. Fetch

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

Examples

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

gh pr 1

• Fech pull request rebasing or merging into the current branch.

gh pr 1 --fetch --rebase

gh pr 1 --fetch --merge

4. Merge or rebase

Option	Usage	Type
-M, --merge	Required	Boolean
-R, --rebase	Required	Boolean
-n, --number	Optional	Number
-b, --branch	Optional	String
--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

• 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

5. 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!"

6. 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

7. 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

8. 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.

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

• 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

9. 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

1. 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"

2. 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

1. 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 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

2. 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 of a certain repository.

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

3. 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

4. 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.

gh is --list --milestone 1

• 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

5. 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

6. 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'

7. 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

1. 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

2. 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"

3. 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 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

4. 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

5. Delete

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

Example

• Delete a repository of the logged user.

gh re --delete foo

6. 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

7. 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

8. 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

9. 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

10. 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

Gists

gh gists

Alias: gh gi

1. 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

2. 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"

3. Create

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

Examples

• Create a Gist hello containing "Hello World".

gh gi --new hello --content "Hello World!"

• Create a private Gist hello containing "Hello World".

gh gi --new hello --content "Hello World!" --private

4. Fork

Option	Usage	Type
-f, --fork	Required	String

Examples

• Fork a Gist.

gh gi --fork 5444883

5. Delete

Option	Usage	Type
-D, --delete	Required	String

Example

• Delete a Gist.

gh gi --delete 4252323

• Delete multiple Gists.

gh gi --delete 4252321 --delete 4252322

User

gh user

Alias: gh us

1. Login/Logout

Option	Usage	Type
-l, --login	Required	Boolean
-L, --logout	Required	Boolean

Examples

• Login or show current logged in GitHub user.

gh user --login

• Logout current GitHub account.

gh user --logout

2. Whoami

Option	Usage	Type
-w, --whoami	Required	Boolean

Examples

• Prints your username to stdout.

gh user --whoami

Milestones

gh milestone

Alias: gh ms

1. List

Option	Usage	Type
-l, --list	Required	Boolean
-u, --user	Required	String
-a, --all	Required	Boolean
-r, --repo	Optional	String
-o, --organization	Optional	String

Examples

• Shortcut for listing milestones for a specific repo.

gh ms

• Listing milestones for a specific repo & user.

gh ms --list --user node-gh --repo gh

• Listing all milestones for a specific organization.

gh ms --list --all --organization node-gh

Alias

This cmd provides something similar to shell aliases. If there are aliases in your .gh.json file, we will attempt to resolve the user, PR forwarder or PR submitter to your alias.

gh alias

Alias: gh al

1. List

Option	Usage	Type
-l, --list	Required	Boolean

Examples

• Shortcut for listing aliases.

gh alias

• List aliases.

gh alias --list

2. Add

Option	Usage	Type
-a, --add	Required	String
-u, --user	Required	String

Examples

• Create alias for username.

gh alias --add zeno --user zenorocha

3. Remove

Option	Usage	Type
-r, --remove	Required	String

Examples

• Remove alias.

gh alias --remove zeno

Config

There are some pretty useful configurations that you can set on .gh.json. This file can be found under home directory (on MacOSx: /Users/yourName/.gh.json on Windows: C:\\Users\yourName\.gh.json).

You can also set per-project configurations by adding a .gh.json file in your project's root folder and overriding existing keys.

• GitHub API configurations. Change it if you're a GitHub Enterprise user.

"api": {
    "host": "github.mydomain.com",
    "protocol": "https"
}

• Set default branch and remote.

"default_branch": "master",
"default_remote": "origin"

• Set default users when submitting or forwarding pull requests.

"default_pr_forwarder": "",
"default_pr_reviewer": ""

• GitHub data filled once you log in.

"github_token": "",
"github_user": ""

• Run automated tasks before or after a certain command.

"hooks": {
        "pull-request": {
            "merge": {
                "before": [{"cmd": "ls -la", "log": true}],
                "after": [
                    "gh pr {{options.number}} --comment 'Thank you, pull request merged :D'"
                ]
            }
        }
}

• Run automated tasks passing arguments to the commands. Required for prompt commands.

"hooks": {
        "pull-request": {
            "merge": {
                "before": [{"cmd": "foo", "args": ["bar", "qux"]}]
            }
        }
}

• Set default branch name prefix for PR fetching.

"pull_branch_name_prefix": "pr-"

• Insert signature below issue comment.

"signature": "<br><br>:octocat: *Sent from [GH](http://nodegh.io).*"

• Turn off ssh when pulling a repo and use https instead.

"ssh": false,

If you need to use a custom git command, set the environment variable GH_GIT_COMMAND.

Plugins

• GH Gif - A plugin for commenting on pull requests/issues using GIF reactions.
• GH Travis - A plugin for integrating Travis, a continous integration server.
• GH Jira - A plugin for integrating Jira, an issue management system.

Feel free to create your own plugins by forking GH Boilerplate.