DEPRECATED

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

Table of contents

Contributors

• Install
• Usage
• Config
• Plugins
• Contributing

• --info - Get information about a pull request
• --list - List pull requests
• --fetch - Rebase or Merge pull request into new branch
• --comment - Comment on a pull request
• --fwd - Forward a pull request to another reviewer
• --open | --close - Open or Close a pull request
• --submit - Open or Close a pull request
• --browser - Open GitHub pull request page in the browser

• --new - Create new issues
• --comment - Comment on an issue of a repository
• --list - List issues on a repository
• --open | --close - Open or Close an issue
• --browser - Open GitHub issue page in the browser
• --lock - Lock GitHub issue
• --search - Search issues in current repository
• --assign - Assign an issue on a repository to a user

• --browser - Open the GitHub repository page in the browser
• --list - List repos
• --create - Create a new GitHub repository and clone on the current directory
• --fork - Fork a GitHub repository
• --delete - Delete a repository of specified user
• --clone - Clone a repository
• --label --new - Create or delete a label for a repository
• --label --delete - Delete a label for a repository
• --label --list - List labels for a repository
• --label --update - Update a label for a repository
• --search - Find repositories via various criteria

• --browser - Open a Gist in the browser
• --list - List user's gists
• --create - Create new gists
• --fork - Fork a gist
• --delete - Delete a gist

• --login - Automates saving user name & developer token credentials to your ~/.gh.json config
• --logout - Automates removing user name & developer token credentials from your ~/.gh.json config
• --whoami - Prints the user name from ~/.gh.json to your console

• --latest - Display the latest activities on a repository
• --list - Watch for any activity on repository

• --list - List milestones for a specific repo

• --add - Add a shell-like alias for users
• --remove - Remove alias
• --list - List aliases for a specific repo

• History
• License
• Demonstration
• Supported Node Versions

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):

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

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 |

• To adjust pagination rules

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