Skip to content
GitHub on your command line. Use your terminal, not the browser.
Ruby Gherkin Other
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
assets Change assets. May 23, 2016
bin Use error helper. Oct 6, 2013
features Add content delete command in ref issue #24 Jul 15, 2019
fixtures Remove unused fixture Aug 9, 2019
lib Change to update stat command in ref issue #24 Aug 9, 2019
man Add manpages for authorize, repo and whoami commands. Apr 6, 2013
spec Change to update specs Aug 9, 2019
tasks Add tasks Jul 16, 2019
.gitignore Change to ingore gemfile lock. Jun 4, 2016
.rspec Change to load specs automatically Jun 23, 2019
.travis.yml Change to use latest Rubies and restrict bundler version Jun 23, 2019 Add release notes Jul 16, 2019 Add code of conduct. Jun 4, 2016
Dockerfile Add initial Dockerfile Sep 1, 2015
Gemfile Change to stop limiting dev dependencies Jul 7, 2019
LICENSE Change tagline Jul 15, 2019
Rakefile Add tasks Jul 16, 2019
appveyor.yml Fix config Jul 6, 2019
github_cli.gemspec Change to update github_api dependency Jul 15, 2019

github api logo


Gem Version Build Status Build status Maintainability Coverage Status Inline docs

GitHub on your command line. User your terminal, not the browser. Works hand-in-hand with github_api gem.



Add this line to your application's Gemfile:

gem 'github_cli'

And then execute:

$ bundle

Or install it yourself as:

$ gem install github_cli


1. Usage

Run it:

$ gcli

2. Interface

2.1 Configuration file

The first step is to create a configuration file, either global in home directory or local inside the project:

$ gcli init [--local|-l]

Without any options this command will setup a .gcliconfig configuration file in your home directory with all the global settings. By passing --local option the config file will be created locally in the current directory.

Main configuration options are:

user.token            # Authentication token
user.login            # User login
user.password         # User password             # Default user name
user.repo             # Default repo name              # Default organization name
core.editor           # Editor to be opened
core.endpoint         # The api endpoint, by default             # The web endpoint, by default
core.pager            # Pager to be used, by default less
core.format           # Output formating
core.quiet            # Surpass output to show only response status
core.ssl              # SSL settings
core.auto_pagination  # Switch on default results pagination, default false

Moreover, gcli config command allows you to set/get any configuration option such as output format, editor or oauth token.

For instance, to check value for your authentication token do

$ gcli config user.token

And to set the value do

$ gcli config user.token lh23l4kj234....

To list specific options

$ gcli config --list [regex]

To edit config in your favourite editor:

$ gcli config -e

Finally, to see a manpage about available configuration options do

$ gcli help config

2.2 Authorization

To create oauth tokens you need to setup your basic authentication.

You can either set it up manually like so

$ gcli init
$ gcli config user.login '...'
$ gcli config user.password '...'

Then to create your token do

$ gcli auth create --scopes=repo --note=github_cli --note-url=

Alternatively authorize command has been provided that will guide you through authentication process by asking questions and then save the credentials to .githubrc file. Example

$ gcli authorize

To see your current tokens do

$ gcli auth ls

To see current tokens without configuration file pass --login and --password flags like so

$ gcli auth ls --login=... --password=...

Finally to add the token to your config do

$ gcli config user.token '...'

2.3. Arguments

The required arguments come first as per command description, then are followed by the optional arguments supplied as specific options.

For instance, one can create repository by supplying parameters in the following way:

$ gcli repo create github_api --desc='Test repo for kitty.'

To create repository inside organization:

$ gcli repo create github/github_api --desc='Test repo for kitty.'

To provide array argument, pass space delimited strings like so

$ gcli hook create <user> <repo> --events=push issues status

To provide hash argument, pass space delimited key:value pairs such as

$ gcli hook create <user> <repo> --config=url:"" content_type:json

To find out which options are required and which are optional use help command:

$ gcli repo help create

2.4. Listing commands

You can list all GitHub APIs commands:

$ gcli list

to limit returned results pass pattern

$ gcli list re*   # Returns all commands matching the pattern

2.5. Subcommands

To see a list of subcommands that a given command provides just type top-level command like so

$ gcli repo

2.5. Output formatting

The API responses can be formatted as csv or table.

By default responses are in tabular format. Tables are available in horizontal and vertical mode. To enforce table display pass :h and :v respectively. Otherwise a default orientation will be picked depending on the request made and terminal size.


To get csv formatting for easy command piping do

gcli repo ls -u wycats --format=csv

To suppress output pass --quiet option like so

gcli repo create ... --quiet=true

2.6. Output paging

By default all responses are paged. You can switch off paging by supplying no-pager flag.

gcli --no-pager user ls -u wycats

Also you can supply you preferred pager, otherwise the paging program is taken from environment variable PAGER if defined or defaults to "less".

3. API

Interact with git data:

$ gcli blob
$ gcli commit
$ gcli ref
$ gcli tag
$ gcli tree

Interact with issues:

$ gcli issue
$ gcli label
$ gcli milestone
$ gcli comment

Interact with repositories:

$ gcli repo
$ gcli collab
$ gcli content
$ gcli download
$ gcli fork
$ gcli hook
$ gcli key

Interact with activities:

$ gcli star
$ gcli watch
$ gcli event

Interact with gists:

$ gcli gist

Interact with users:

$ gcli user
$ gcli email
$ gcli follower

Interact with organizations:

$ gcli org
$ gcli member
$ gcli team

Interact with authorizations:

$ gcli auth

Interact with search:

$ gcli search

4. Development

The test suite includes both unit tests and end-to-end tests. The unit tests are in spec folder and can be run:

$ bundle exec rake spec

The end-to-end tests are in features folder and can be run:

$ bundle exec rake features

In order to run all the tests run:

$ bundle exec rake [ci]


This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

Bug reports and pull requests are welcome.

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request


Copyright (c) 2012 Piotr Murach. See LICENSE for further details.

You can’t perform that action at this time.