All the power of GitHub in your terminal.
- Install
- Usage
- Contributors
- Contributing
- History
- License
- Demonstration
- Supported Node Versions
- Available commands
- Config
- Plugins
[sudo] npm install -g gh
gh [command] [--flags]
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
For detailed instructions, check Contributing. Don't miss the source code reports.
For detailed changelog, check Releases.
- We support the node versions that the Node.js organization supports which as of now is Node v6 & up.
- 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:
- 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
- Manually generate your personal token & add it to your
~/.gh.json
- Run
gh help
- List all comands options.
gh help --all
- List specific command options.
gh help <command>
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.
gh pull-request
Alias:
gh pr
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
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.
-
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"
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 |
- 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
Option | Usage | Type |
---|---|---|
-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
.
- 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
Option | Usage | Type |
---|---|---|
-c , --comment |
Required | String |
-n , --number |
Required | Number |
--remote |
Optional | String |
-r , --repo |
Optional | String |
-u , --user |
Optional | String |
- Comment on a pull request.
gh pr 1 --comment "Merged, thank you!"
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.
- Forward a pull request to another reviewer.
gh pr 1 --fwd username
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 |
- 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
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.
- 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
- Submit a pull request in draft state.
gh pr --submit eduardolundgren --draft
Option | Usage | Type |
---|---|---|
-B , --browser |
Required | Boolean |
-n , --number |
Required | Number |
-u , --user |
Optional | String |
-r , --repo |
Optional | String |
- Open GitHub pull request page in the browser.
gh pr 100 --browser
gh notification
Alias:
gh nt
Option | Usage | Type |
---|---|---|
-l , --latest |
Required | Boolean |
--remote |
Optional | String |
-r , --repo |
Optional | String |
-u , --user |
Optional | String |
--date |
Optional | String |
- 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"
Option | Usage | Type |
---|---|---|
-w , --watch |
Required | Boolean |
--remote |
Optional | String |
-r , --repo |
Optional | String |
-u , --user |
Optional | String |
- 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
gh issue
Alias:
gh is
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 |
- 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
Option | Usage | Type |
---|---|---|
-c , --comment |
Required | String |
-n , --number |
Required | Number |
--remote |
Optional | String |
-r , --repo |
Optional | String |
-u , --user |
Optional | String |
- 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
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 |
- 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
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 |
- 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
andbug
.
gh is --list --labels todo,bug
- List all issues on a certain repository.
gh is --list --user eduardolundgren --repo node-gh
Option | Usage | Type |
---|---|---|
-B , --browser |
Required | Boolean |
-n , --number |
Required | Number |
-u , --user |
Optional | String |
-r , --repo |
Optional | String |
- Shortcut for opening GitHub issue page in the browser.
gh is 100
- Open GitHub issue page in the browser.
gh is 100 --browser
Option | Usage | Type |
---|---|---|
-s , --search |
Required | Boolean |
-a , --all |
Optional | Boolean |
-d , --detailed |
Optional | Boolean |
-r , --repo |
Optional | String |
-u , --user |
Optional | String |
- 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'
Option | Usage | Type |
---|---|---|
--assign |
Required | Boolean |
-A , --assignee |
Required | String |
-n , --number |
Required | Number |
-r , --repo |
Optional | String |
-u , --user |
Optional | String |
- 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
gh repo
Alias:
gh re
Option | Usage | Type |
---|---|---|
-B , --browser |
Required | Boolean |
-u , --user |
Optional | String |
-r , --repo |
Optional | String |
- 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
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 |
- 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"
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 |
- 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
Option | Usage | Type |
---|---|---|
-f , --fork |
Required | String |
-u , --user |
Required | String |
-O , --organization |
Optional | String |
- 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
Option | Usage | Type |
---|---|---|
-D , --delete |
Required | String |
-u , --user |
Required | String |
- Delete a repository of the logged user.
gh re --delete foo
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.
- 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
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 |
- 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
Option | Usage | Type |
---|---|---|
-L , --label |
Required | Boolean |
-D , --delete |
Required | String |
-r , --repo |
Required | String |
-O , --organization |
Optional | String |
-u , --user |
Optional | String |
- 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
Option | Usage | Type |
---|---|---|
-L , --label |
Required | Boolean |
-l , --list |
Required | Boolean |
-r , --repo |
Required | String |
-O , --organization |
Optional | String |
-u , --user |
Optional | String |
- 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
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 |
- 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
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 ] |
- 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
gh gists
Alias:
gh gi
Option | Usage | Type |
---|---|---|
-B , --browser |
Required | Boolean |
-u , --user |
Optional | String |
-i , --id |
Optional | String |
- Shortcut for opening your Gists in the browser.
gh gi
- Open a Gist in the browser.
gh gi --browser --id 5991877
Option | Usage | Type |
---|---|---|
-l , --list |
Required | Boolean |
-u , --user |
Optional | String |
--date |
Optional | String |
- 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"
Option | Usage | Type |
---|---|---|
-N , --new |
Required | String |
-c , --content |
Optional | String |
-d , --description |
Optional | String |
-p , --private |
Optional | Boolean |
- 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
Option | Usage | Type |
---|---|---|
-f , --fork |
Required | String |
- Fork a Gist.
gh gi --fork 5444883
Option | Usage | Type |
---|---|---|
-D , --delete |
Required | String |
- Delete a Gist.
gh gi --delete 4252323
- Delete multiple Gists.
gh gi --delete 4252321 --delete 4252322
gh user
Alias:
gh us
Option | Usage | Type |
---|---|---|
-l , --login |
Required | Boolean |
-L , --logout |
Required | Boolean |
- Login or show current logged in GitHub user.
gh user --login
- Logout current GitHub account.
gh user --logout
Option | Usage | Type |
---|---|---|
-w , --whoami |
Required | Boolean |
- Prints your username to stdout.
gh user --whoami
gh milestone
Alias:
gh ms
Option | Usage | Type |
---|---|---|
-l , --list |
Required | Boolean |
-u , --user |
Required | String |
-a , --all |
Required | Boolean |
-r , --repo |
Optional | String |
-o , --organization |
Optional | String |
- 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
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
Option | Usage | Type |
---|---|---|
-l , --list |
Required | Boolean |
- Shortcut for listing aliases.
gh alias
- List aliases.
gh alias --list
Option | Usage | Type |
---|---|---|
-a , --add |
Required | String |
-u , --user |
Required | String |
- Create alias for username.
gh alias --add zeno --user zenorocha
Option | Usage | Type |
---|---|---|
-r , --remove |
Required | String |
- Remove alias.
gh alias --remove zeno
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
.
- 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.