GitHub GraphQL CLI

Disclaimer: This project is in no way associated, sponsored, development, maintained, owned, supported, or otherwise affiliated with GitHub.

GitHub GraphQL CLI is a highly versatile CLI tool written entirely in NodeJS that interacts with GitHub's v4 GraphQL API.

The motivation behind this project is to help with CLI automation where one can easily chain it with other CLI tools.

It is designed to be extensible by the open source community, so please contribute enhancements.

• Install
• Configuration
• Usage
• Supported APIs
• Contributing
• License
• Disclaimer

Install

npm install -g github-graphql-cli

Configuration

A personalToken must be setup in GitHub and then set it as an environment variables called GITHUB_TOKEN.

Important Without this token this tool will not work. Do NOT skip this step.

• GitHub Documentation

Usage

Assuming our repo is https://github.com/stepweb/github.git and we want to get information about PR 123, we would do something like:

github-graphql-cli -o stepweb -r github pullRequest 1 \
    --fields.body \
    --fields.author.login \
    --fields.number

This would give us the following output:

{
    body: 'Initial commit',
    number: 1,
    author: {
        login: 'adamovsky'
    }
}

Example Usage

If we want to get the pullRequestId for a mergePullRequest command, we could do something like this (assuming our pull request number is 1):

github-graphql-cli -o stepweb -r github pullRequest 1 \
    --fields.id \
    | json id \
    | xargs -I % github-graphql-cli -o stepweb -r github mergePullRequest % \
        --fields.pullRequest.merged

Pretty neat.

Fields

To specify what we want to select from the result set we use fields.

Fields follow a dot notation that mirror the hierarchy of the schema. This means if we go to GitHub's repository query (documentation)[https://developer.github.com/v4/object/repository/], at the bottom we see that we can query the field isPrivate.

Using dot notation we would simply follow the path of the documentation:

--fields.isPrivate

Notice we don't have to specify the query (e.g. repository) as part of our fields selection since we already know the context.

It is that simple.

Inputs

Resolvers can take parameters, which we call inputs. Anytime anything in GraphQL takes a parameter, similar to the fields, we use dot notation to mirror the schema.

If we stay on GitHub's repository query (documentation)[https://developer.github.com/v4/object/repository/], we can see that issue takes a number argument.

Using dot notation we would simply follow the path of the documentation:

--inputs.issue 123

Notice we don't have to specify the query (e.g. repository) as part of our fields selection since we already know the context.

We use inputs to pass arguments to mutations as well.

It is that simple.

Examples

Queries

• Fetch the number of issues in a repository
• Export project issues
• Find an issue by title
• Fetch a GitHub project name
• Fetch number of pull requests
• Fetch the id of a pull request
• Get user's name
• Get viewer name

Mutations

• Create an issue
• Create a pull request
• Merge a pull request

Open the script you want to run and you will be able to derive what parameters you need to give it.

Supported APIs

The code has been engineered to where the tool queries GitHub for the latest API. This ensures you don't have to wait for this project to get updated whenever GitHub updates their API.

This means that all the documentation of GitHub's GraphQL API is the documentation for this tool.

Documentation

• Mutation
• Query

Note that some of the APIs (e.g. pullRequest) are shortcut, convenience, or helper APIs, and in themselves are not first level methods of GitHub's official API.

Bash Alias

To reduce the likelihood of name collision, we use the longer name github-graphql-cli for the CLI command. We highly recommend to make a bash alias if you will use this tool frequently.

In your .bash_profile (or .bashrc) simply add this line:

alias gh="github-graphql-cli"

Contribute

Don't see a feature you need? Consider joining the project and help enhance it.

Read more in the CONTRIBUTING file for details.

License

Distributed under ISC license.