Home

Awesome

graphqurl

oclif Version

Azure Pipelines Appveyor CI Downloads/week License

<!--[![Codecov](https://codecov.io/gh/hasura/graphqurl/branch/master/graph/badge.svg)](https://codecov.io/gh/hasura/graphqurl)-->

graphqurl is a curl like CLI for GraphQL. It's features include:

Note: v2.0.0 onwards, support for GraphiQL (UI) is removed. See this issue for more details. Use v1.0.3 for GraphiQL feature.

Made with :heart: by <a href="https://hasura.io">Hasura</a>

Graphqurl Demo

Subscriptions triggering bash

Table of contents

Installation

Steps to Install CLI

npm install -g graphqurl

Steps to Install Node Library

npm install --save graphqurl

Usage

CLI

Query

gq https://my-graphql-endpoint/graphql \
     -H 'Authorization: Bearer <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.

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

Flag Reference

FlagShorthandDescription
--query-qGraphQL query to execute
--header-Hrequest header
--variable-vVariables used in the query
--variablesJSON-nVariables used in the query as JSON
--singleLine-lPrints output in a single line, does not prettify
--introspectIntrospect the endpoint and get schema
--formatOutput format for GraphQL schema after introspection. Options: json, graphql (Default: graphql)
--help-hOutputs the command help text
--versionOutputs CLI version
--queryFileFile to read the query from
--operationNameName of the operation to execute from the query file
--variablesFileJSON file to read the query variables from

Node Library

Using callbacks:

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

const client = createClient({
  endpoint: 'https://my-graphql-endpoint/graphql',
  headers: {
    'Authorization': 'Bearer <token>'
  }
});

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

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

client.query(
  {
    query: 'query ($id: Int) { table_by_id (id: $id) { column } }',
    variables: { id: 24 }
  },
  successCallback,
  errorCallback
);

Using Promises:

For queries and mutations,

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

const client = createClient({
  endpoint: 'https://my-graphql-endpoint/graphql',
  headers: {
    'Authorization': 'Bearer <token>'
  }
});

client.query(
  {
    query: 'query ($id: Int) { table_by_id (id: $id) { column } }',
    variables: { id: 24 }
  }
).then((response) => console.log(response))
 .catch((error) => console.error(error));

For subscriptions,

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

const client = createClient({
  endpoint: 'https://my-graphql-endpoint/graphql',
  headers: {
    'Authorization': 'Bearer <token>'
  },
  websocket: {
    endpoint: 'wss://my-graphql-endpoint/graphql',
    onConnectionSuccess: () => console.log('Connected'),
    onConnectionError: () => console.log('Connection Error'),
  }
});

client.subscribe(
  {
    subscription: 'subscription { table { column } }',
  },
  (event) => {
    console.log('Event received: ', event);
    // handle event
  },
  (error) => {
    console.log('Error: ', error);
    // handle error
  }
)

API

createClient

The createClient function is available as a named export. It takes init options and returns client.

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

Client

const client = createClient({
  endpoint: 'https://my-graphql-endpoint/graphql'
});

The graphqurl client exposeses the following methods:

More Examples

Node Library

Queries and Mutations

Query example with variables

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

const client = createClient({
  endpoint: 'https://my-graphql-endpoint/graphql',
  headers: {
    'x-access-key': 'mysecretxxx',
  },
});

client.query(
  {
    query: `
      query ($name: String) {
        table(where: { column: $name }) {
          id
          column
        }
      }
    `,
    variables: {
      name: 'Alice'
    }
  }
).then((response) => console.log(response))
 .catch((error) => console.error(error));

Subscriptions

Using promises,

const { createClient } = require('graphqurl');
const client = createClient({
  endpoint: 'https://my-graphql-endpoint/graphql',
  headers: {
    'Authorization': 'Bearer Andkw23kj=Kjsdk2902ksdjfkd'
  }
  websocket: {
    endpoint: 'wss://my-graphql-endpoint/graphql',
  }
})

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

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

client.subscribe(
  {
    query: 'subscription { table { column } }',
  },
  eventCallback,
  errorCallback
)

CLI

Generic example:

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

Maintained with :heart: by <a href="https://hasura.io">Hasura</a>