# GithubCLI
[![Gem Version](https://badge.fury.io/rb/github_cli.png)](http://badge.fury.io/rb/github_cli) [![Build Status](https://secure.travis-ci.org/peter-murach/github_cli.png?branch=master)][travis] [![Dependency Status](https://gemnasium.com/peter-murach/github_cli.png?travis)][gemnasium] [![Code Climate](https://codeclimate.com/badge.png)][codeclimate]

[travis]: http://travis-ci.org/peter-murach/github_cli
[gemnasium]: https://gemnasium.com/peter-murach/github_cli
[codeclimate]: https://codeclimate.com/github/peter-murach/github_cli

CLI-based access to GitHub API v3 that works hand-in-hand with `github_api` gem.

Important!: This library is currently being updated to include all Github API requests and undergoes rapid development cycles. A feature roadmap will be added shortly.

![Interface](https://github.com/peter-murach/github_cli/raw/master/screenshots/interface.png)

## Installation

Add this line to your application's Gemfile:

    gem 'github_cli'

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install github_cli

## Usage

Run it:

```shell
$ gcli
```

### Initialize a configuration file

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

```shell
$ gcli init [--local] [filename]
```

Without any options this command will setup a `.githubrc` configuration file in
your home/project directory with all the global settings. By passing `--local` option the config file will be created locally in the execution directory. Further, by default `.githubrc` name is used which can be changed by passing the `filename`.

Main configuration options are:

```
user.token            # Authentication token
user.login            # User login
user.password         # User password
user.name             # Default user name
user.repo             # Default repo name
user.org              # Default organization name
core.editor           # Editor to be opened
core.pager            # Pager to be used, by default less
core.format           # Output formating
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

```shell
$ gcli config [--local] user.token
```

and to set the value do

```shell
$ gcli config [--local] user.token lh23l4kj234....
```

To list specific options

```shell
$ gcli config [--local] --list [regex]
```

To edit config in your favourite editor:

```shell
$ gcli config -e
```

Finally, to see a manpage about available configuration options do

```shell
$ gcli help config
```

### Authorization

To create oauth tokens you need to setup your basic authentication like so

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

Then to create your token do

```shell
$ gcli auth create --scopes=repo --note=gihtub_cli --note-url=http://github.com/peter-murach/github_cli
```

To see your current tokens do

```shell
$ gcli auth ls
```

Finally to add the token to your config do

```shell
$ gcli config user.token '...'
```

### Arguments

The required arguments come first as per command description, then are followed by the optional arguments supplied inside a `params` flag.

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

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

To create repository inside organization:

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

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

```shell
$ gcli repo help create
```

### Getting a list of commands

You can list all GitHub APIs comamnds:

```shell
$ gcli list
```

to limit returned results pass `pattern`

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

### Output Format

The API responses can be formatted as `csv`, `json`, `pretty`, `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.


![Command](https://github.com/peter-murach/github_cli/raw/master/screenshots/command.png)

To get `csv` formatting for easy command piping do

```shell
gcli repo ls -u wycats --format=csv
```

### Output Paging

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

```shell
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".

### API

Interact with git data:

```shell
$ gcli blob
$ gcli commit
$ gcli ref
$ gcli tag
$ gcli tree
```

Interact with issues:

```shell
$ gcli issue
$ gcli label
$ gcli milestone
$ gcli comment
```

Interact with repositories:

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

Interact with activities:

```shell
$ gcli star
$ gcli watch
$ gcli event
```

Interact with gists:

```shell
$ gcli gist
```

Interact with users:

```shell
$ gcli user
$ gcli email
$ gcli follower
```

Interact with organizations:

```shell
$ gcli org
$ gcli member
$ gcli team
```

Interact with authorizations:

```shell
$ gcli auth
```

Interact with search:

```shell
$ gcli search
```

## Contributing

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

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