graphqurl

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

CLI for making GraphQL queries. It also provisions queries with autocomplete.
Use as a library with Node.js or from the browser
Supports subscriptions
Export GraphQL schema

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 ❤️ by Hasura

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

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

Flag Reference

Flag	Shorthand	Description
`--query`	`-q`	GraphQL query to execute
`--header`	`-H`	request header
`--variable`	`-v`	Variables used in the query
`--variablesJSON`	`-n`	Variables used in the query as JSON
`--singleLine`	`-l`	Prints output in a single line, does not prettify
`--introspect`		Introspect the endpoint and get schema
`--format`		Output format for GraphQL schema after introspection. Options: `json`, `graphql` (Default: `graphql`)
`--help`	`-h`	Outputs the command help text
`--version`		Outputs CLI version
`--queryFile`		File to read the query from
`--operationName`		Name of the operation to execute from the query file
`--variablesFile`		JSON 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');

options: [Object, required] graphqurl init options with the following properties:
- endpoint: [String, required] GraphQL endpoint
- headers: [Object] Request header, defaults to {}. These headers will be added along with all the GraphQL queries, mutations and subscriptions made through the client.
- websocket: [Object] Options for configuring subscriptions over websocket. Subscriptions are not supported if this field is empty.
  - endpoint: [String, ] WebSocket endpoint to run GraphQL subscriptions.
  - shouldRetry: [Boolean] Boolean value whether to retry closed websocket connection. Defaults to false.
  - parameters: [Object] Payload to send the connection init message with
  - onConnectionSuccess: [void => void] Callback function called when the GraphQL connection is successful. Please not that this is different from the websocket connection being open. Please check the followed protocol for more details.
  - onConnectionError: [error => null] Callback function called if the GraphQL connection over websocket is unsuccessful
  - onConnectionKeepAlive: [void => null]: Callback function called when the GraphQL server sends GRAPHQL_CONNECTION_KEEP_ALIVE messages to keep the connection alive.
Returns: [client]

Client

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

The graphqurl client exposeses the following methods:

client.query: [(queryoptions, successCallback, errorCallback) => Promise (response)]
- queryOptions: [Object required]
  - query: [String required] The GraphQL query or mutation to be executed over HTTP
  - variables: [Object] GraphQL query variables. Defaults to {}
  - headers: [Object] Header overrides. If you wish to make a GraphQL query while adding to or overriding the headers provided during initalisations, you can pass the headers here.
- successCallback: [response => null] Success callback which is called after a successful response. It is called with the following parameters:
  - response: The response of your query
- errorCallback: [error => null] Error callback which is called after the occurrence of an error. It is called with the following parameters:
  - error: The occurred error
- Returns: [Promise (response) ] This function returns the response wrapped in a promise.
  - response: response is a GraphQL compliant JSON object in case of queries and mutations.
client.subscribe: [(subscriptionOptions, eventCallback, errorCallback) => Function (stop)]
- subscriptionOptions: [Object required]
  - subscription: [String required] The GraphQL subscription to be started over WebSocket
  - variables: [Object] GraphQL query variables. Defaults to {}
  - onGraphQLData: [(response) => null] You can optionally pass this function as an event callback
  - onGraphQLError: [(response) => null] You can optionally pass this function as an error callback
  - onGraphQLComplete: [() => null] Callback function called when the GraphQL subscription is declared as complete by the server and no more events will be received
- eventCallback: [(response) => null] Event callback which is called after receiving an event from the given subscription. It is called with the following parameters:
  - event: The received event from the subscription
- errorCallback: [error => null] Error callback which is called after the occurrence of an error. It is called with the following parameters:
  - error: The occurred error
- Returns: [void => null] This is a function to stop the subscription

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 ❤️ by Hasura

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

graphqurl

Table of contents

Installation

Steps to Install CLI

Steps to Install Node Library

Usage

CLI

Query

Auto-complete

Subscription

Export schema

Command

Args

Flag Reference

Node Library

Using callbacks:

Using Promises:

API

createClient

Client

More Examples

Node Library

Queries and Mutations

Subscriptions

CLI

Files

README.md

Latest commit

History

README.md

File metadata and controls

graphqurl

Table of contents

Installation

Steps to Install CLI

Steps to Install Node Library

Usage

CLI

Query

Auto-complete

Subscription

Export schema

Command

Args

Flag Reference

Node Library

Using callbacks:

Using Promises:

API

createClient

Client

More Examples

Node Library

Queries and Mutations

Subscriptions

CLI