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
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.
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
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
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.