Skip to main content

A command-line interface to the GitHub Issues API v2.

Project description


github-cli provides an executable called ghi, that can be used to access all of GitHub’s documented Issues API (v2) functionality from your command-line

github-cli is written in Python


on most UNIX-like systems, you’ll probably need to run the following `install` commands as root or by using sudo


pip install github-cli

from source

pip install git+


git clone git://
cd github-cli
python install

as a result, the ghi executable will be installed into a system bin directory


make sure your GitHub username and API token are added to the global git config:

git config --global github.user <your GitHub username>
git config --global github.token <your GitHub API token>

or you can specify the environment variables GITHUB_USER and GITHUB_TOKEN

you can find the username and API token on your GitHub’s account page


from within a working directory with a remote that is hosted on GitHub (remote named either origin or github for git repositories or default or github for mercurial/hg-git repositories), you can do this (note: with the -r option, commands can be invoked from anywhere):

(github-cli)[jsmits@imac:~]$ ghi --help
Usage: ghi command [args] [options]

ghi list [-s open|closed|all]       show open, closed or all issues
                                    (default: open)
ghi [-s o|c|a] -v                   same as above, but with issue details
ghi                                 same as: ghi list
ghi -v                              same as: ghi list -v
ghi [-s o|c] -w                     show issues' GitHub page in web browser
                                    (default: open)
ghi list -u <github_user>           show issues created by specified user

ghi show <nr>                       show issue <nr>
ghi show <nr> -v                    same as above, but with comments
ghi <nr>                            same as: ghi show <nr>
ghi <nr> -w                         show issue <nr>'s GitHub page in web
ghi open (o)                        create a new issue (with $EDITOR)
ghi open (o) -m <msg>               create a new issue with <msg> content
                                    (optionally, use \n for new lines; first
                                    line will be the issue title)
ghi close (c) <nr>                  close issue <nr>
ghi open (o) <nr>                   reopen issue <nr>
ghi edit (e) <nr>                   edit issue <nr> (with $EDITOR)
ghi label add (al) <label> <nr>     add <label> to issue <nr>
ghi label remove (rl) <label> <nr>  remove <label> from issue <nr>
ghi search (s) <term>               search for <term> (default: open)
ghi s <term> [-s o|c] -v            same as above, but with details
ghi s <term> -s closed              only search in closed issues
ghi comment (m) <nr>                create a comment for issue <nr>
                                    (with $EDITOR)
ghi comment (m) <nr> -m <msg>       create a comment for issue <nr>
                                    with <msg> content. (optionally use \n
                                    for new lines)
ghi -r <user>/<repo>                specify a repository (can be used for
                                    all commands)
ghi -r <repo>                       specify a repository (gets user from
                                    global git config)

Description: command-line interface to GitHub's Issues API (v2)

  -h, --help            show this help message and exit
  -v, --verbose         show issue details (only for show, list and search
                        commands) [default: False]
  -s STATE, --state=STATE
                        specify state (only for list and search (except `all`)
                        commands) choices are: open (o), closed (c), all (a)
                        [default: open]
                        issues created by <github_username> [default: all]
  -m MESSAGE, --message=MESSAGE
                        message content for opening or commenting on an issue
                        without using the editor
  -r REPO, --repo=REPO, --repository=REPO
                        specify a repository (format: `user/repo` or just
                        `repo` (latter will get the user from the global git
  -w, --web, --webbrowser
                        show issue(s) GitHub page in web browser (only for
                        list and show commands) [default: False]
  -V, --version         show program's version number and exit

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
github-cli-1.0.0.tar.gz (11.1 kB) Copy SHA256 hash SHA256 Source None Nov 8, 2011

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page