curl for GraphQL with autocomplete, subscriptions and GraphiQL. Also a dead-simple universal javascript GraphQL client.
APACHE-2.0 License
graphqurl
is a curl like CLI for GraphQL. It's features include:
Made with ❤️ by Hasura
npm install -g graphqurl
npm install --save graphqurl
gq https://my-graphql-endpoint/graphql \
-H 'Authorization: Bearer <token>' \
-q 'query { table { column } }'
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.
Open GraphiQL with a given endpoint:
gq <endpoint> -i
This is a custom GraphiQL where you can specify request's headers.
Subscriptions can be executed and the response is streamed on to stdout.
gq <endpoint> \
-q 'subscription { table { column } }'
Export GraphQL schema to GraphQL or JSON format:
gq <endpoint> --introspect > schema.graphql
# json
gq <endpoint> --introspect --format json > schema.json
$ gq ENDPOINT [-q QUERY]
ENDPOINT
: graphql endpoint (can be also set as GRAPHQURL_ENDPOINT
env var)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 |
--graphiql |
-i |
Open GraphiQL with the given endpoint, headers, query and variables |
--graphiqlHost |
-a |
Host to use for GraphiQL. (Default: localhost ) |
--graphiqlPort |
-p |
Port to use for GraphiQL |
--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 |
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
);
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
}
)
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:
{}
. These headers will be added along with all the GraphQL queries, mutations and subscriptions made through the client.GRAPHQL_CONNECTION_KEEP_ALIVE
messages to keep the connection alive.Returns: [client]
const client = createClient({
endpoint: 'https://my-graphql-endpoint/graphql'
});
The graphqurl client exposeses the following methods:
client.query: [(queryoptions, successCallback, errorCallback) => Promise (response)]
{}
queries
and mutations
.client.subscribe: [(subscriptionOptions, eventCallback, errorCallback) => Function (stop)]
{}
complete
by the server and no more events will be receivedQuery 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));
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
)
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