Skip to content
curl for GraphQL with autocomplete, subscriptions and GraphiQL. Also a dead-simple universal javascript GraphQL client.
Branch: master
Clone or download
shahidhk and wawhal parse variables as json, add a dedicated json var flag, close #43 (#45)
* parse vairables as json, add a dedicated json var flag, close #43

* fix review comments

* run eslint fix
Latest commit df86626 Mar 6, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci
assets add bash script trigger demo Aug 10, 2018
bin Adding GraphQURL Client (#13) Aug 3, 2018
src parse variables as json, add a dedicated json var flag, close #43 (#45) Mar 6, 2019
test
.editorconfig
.eslintignore
.eslintrc
.gitattributes
.gitignore
.sail.yml
CODE_OF_CONDUCT.md Create CODE_OF_CONDUCT.md Aug 1, 2018
CONTRIBUTING.md update contributing.md (#17) Aug 6, 2018
LICENSE
README.md
appveyor.yml
package-lock.json
package.json

README.md

graphqurl

Made by the team at hasura.io, graphqurl is a curl like CLI for GraphQL:

  • CLI for making GraphQL queries with autocomplete
  • Run GraphiQL locally against any endpoint
  • Use as a library with Node.js or from the browser
  • Supports subscriptions
  • Export GraphQL schema

oclif Version

CircleCI Appveyor CI Downloads/week License


Graphqurl Demo

GraphiQL Demo

Subscriptions triggering bash

Installation

CLI

npm install -g graphqurl

Node Library

npm install --save graphqurl

Usage

CLI

Query

gq https://my-graphql-endpoint/graphql \
     -H 'Authorization: token <token>' \
     -q 'query { table { column } }'

Auto-complete

GraphQURL can auto-complete queries using schema introspection. Execute the command without providing a query string:

$ gq <endpoint> [-H <header:value>]
Enter the query, use TAB to auto-complete, Ctrl+Q to execute, Ctrl+C to cancel
gql>

You can use TAB to trigger auto-complete. Ctrl+C to cancel the input and Ctrl+Q/Enter to execute the query.

GraphiQL

Open GraphiQL with a given endpoint:

gq <endpoint> -i

This is a custom GraphiQL where you can specify request's headers.

Mutation

Mutations with variables can be executed by providing the variables with -v flag.

gq <endpoint> \
   -v 'name=hasura' \
   -q 'mutation ($name: String) { table (objects: [{ name: $name }]) }'

Subscription

Subscriptions can be executed and the response is streamed on to stdout.

gq <endpoint> \
   -q 'subscription { table { column } }'

Export schema

Export GraphQL schema to GraphQL or JSON format:

gq <endpoint> --introspect > schema.graphql

# json
gq <endpoint> --introspect --format json > schema.json

Command

$ gq ENDPOINT [-q QUERY]

Args

  • ENDPOINT: graphql endpoint (can be also set as GRAPHQURL_ENDPOINT env var)

Options

  • -q, --query=query: graphql query to execute
  • -H, --header="key:value": request header
  • -v, --variable="key=value": variables used in the query
  • -n, --name=name: name of the graphql definition to execute, use only if there are multiple definitions
  • --queryFile=/path/to/queryfile: file to read the query from
  • --variablesFile=/path/to/variablefile: file to read the query variables from
  • -i, --graphiql: open graphiql with the given endpoint, headers, query and variables
  • -p, --graphiqlPort=graphiqlPort: [default: 4500] port to use for graphiql
  • -a, --graphiqlAddress=graphiqlAddress: [default: localhost] address to use for graphiql
  • -l, --singleLine: show output in a single line, do not prettify
  • --version: show CLI version
  • -h, --help: show CLI help

Node Library

Using callbacks:

const { query } = require('graphqurl');

function successCallback(response, queryType, parsedQuery) {
  if (queryType === 'subscription') {
    // handle subscription response
  } else {
    // handle query/mutation response
  }
}

function errorCallback(error, queryType, parsedQuery) {
  console.error(error);
}

query(
  {
    query: 'query { table { column } }',
    endpoint: 'https://my-graphql-endpoint/graphql',
    headers: {
      'x-access-key': 'mysecretxxx',
    }
  },
  successCallback,
  errorCallback
);

Using Promises:

For queries and mutations,

const { query } = require('graphqurl');

query(
  {
    query: 'query { table { column } }',
    endpoint: 'https://my-graphql-endpoint/graphql',
    headers: {
      'x-access-key': 'mysecretxxx',
    }
  }
).then((response) => console.log(response))
 .catch((error) => console.error(error));

For subscriptions,

const { query } = require('graphqurl');

query(
  {
    query: 'subscription { table { column } }',
    endpoint: 'https://my-graphql-endpoint/graphql',
    headers: {
      'x-access-key': 'mysecretxxx',
    }
  }
).then((observable) => {
  observable.subscribe(
    (event) => {
      console.log('Event received: ', event);
      // handle event
    },
    (error) => {
      console.log('Error: ', error);
      // handle error
    }
  )
})
 .catch((error) => console.error(error));

Subscriptions are not supported in browsers yet.

API

query(options, successCallback, errorCallback)

  • options: [Object, required] GraphQL query options with the following properties:
    • endpoint: [String, required] GraphQL endpoint
    • query: [String, required] GraphQL query string
    • headers: [Object] Request headers, defaults to {}
    • variables: [Object] GraphQL query variables, defaults to '{}'
    • name: [String] Operation name. Used only if the query string contains multiple operations.
  • successCallback: [Function] Success callback which is called after a successful response. It is called with the following parameters:
    • response: The response of your query
    • queryType: The type of query you made i.e. one [query, mutation, subscription]
    • parsedQuery: The query parsed into a GraphQL document
  • errorCallback: [Function] Error callback which is called after the occurrence of an error. It is called with the following parameters:
    • error: The occurred error
    • queryType: [String] The type of query you made i.e. one [query, mutation, subscription]
    • parsedQuery: [Object] The query parsed into a GraphQL document
  • Returns: [Promise (response) ]If successCallback and errorCallback are not provided, this function returns the response wrapped in a promise.
    • response: response is a GraphQL compliant JSON object in case of queries and mutations. However, if you make a subscription, it returns an observable that you can later subscribe to. Check this example to see how to subscribe to observables.

More Examples

Node Library

Queries

Query example with variables

const { query } = require('graphqurl');

query(
  {
    query: `
      query ($name: String) {
        table(where: { column: $name }) {
          id
          column
        }
      }
    `,
    endpoint: 'https://my-graphql-endpoint/graphql',
    headers: {
      'x-access-key': 'mysecretxxx',
    },
    variables: {
      name: 'Alice'
    }
  }
).then((response) => console.log(response))
 .catch((error) => console.error(error));

Mutations

const { query } = require('graphqurl');

query(
  {
    query: `
      mutation ($id_insert_input: String!, $column_insert_input: String!) {
        insert_to_table (
          id: $id_insert_input,
          column: $column_insert_input
        ) {
          affected_rows
        }
      }
    `,
    endpoint: 'https://my-graphql-endpoint/graphql',
    headers: {
      'x-access-key': 'mysecretxxx',
    },
    variables: {
      id_insert_input: 'id_ak23sdfkjk2',
      column_insert_input: 'Bob'
    }
  }
).then((response) => console.log(response))
 .catch((error) => console.error(error));

Subscriptions

Using promises,

const { query } = require('graphqurl');

const eventCallback = (event) => {
  console.log('Event received:', event);
  // handle event
};

const errorCallback = (error) => {
  console.log('Error:', error)
};

query(
  {
    query: 'subscription { table { column } }',
    endpoint: 'https://my-graphql-endpoint/graphql',
    headers: {
      'Authorization': 'Bearer Andkw23kj=Kjsdk2902ksdjfkd'
    }
  },
).then((observable) => {
  observable.subscribe(
    (event) => {
      console.log('Event received', event);
      // handle event
    },
    (error) => {
      console.log('Error', error);
      // handle error
    }
  )
}).catch(errorCallback);

Lets do the above subscription using callbacks,

const { query } = require('graphqurl');

function eventCallback(event) {
  console.log('Event received:', event);
  // handle event
}

function errorCallback(error) {
  console.log('Error:', error)
}

query(
  {
    query: 'subscription { table { column } }',
    endpoint: 'https://my-graphql-endpoint/graphql',
    headers: {
      'Authorization': 'Bearer Andkw23kj=Kjsdk2902ksdjfkd'
    }
  },
  eventCallback,
  errorCallback
);

CLI

Generic example:

gq \
     https://my-graphql-endpoint/graphql \
     -H 'Authorization: token <token>' \
     -H 'X-Another-Header: another-header-value' \
     -v 'variable1=value1' \
     -v 'variable2=value2' \
     -q 'query { table { column } }'

Reading the query and variables from a file:

gq \
     https://my-graphql-endpoint/graphql \
     -H 'Authorization: token <token>' \
     -H 'X-Another-Header: another-header-value' \
     --variableFile='./queryVariables.json' \
     --queryFile='./query.gql

Executing only a particular named query from a file that contains many queries:

gq <endpoint> --queryFile ./queries.gql --name getItems

Maintained with ❤️ by Hasura

You can’t perform that action at this time.