iki/graphqurl

curl for GraphQL with autocomplete, subscriptions and GraphiQL. Also a dead-simple universal javascript GraphQL client.

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

---

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