GQL provides a python 3.6+ script, called gql-cli which allows you to execute GraphQL queries directly from the terminal.

This script supports http(s) or websockets protocols.


Send GraphQL queries from the command line using http(s) or websockets. If used interactively, write your query, then use Ctrl-D (EOF) to execute it.

usage: gql-cli [-h] [-V [VARIABLES ...]] [-H [HEADERS ...]] [--version]
               [-d | -v] [-o OPERATION_NAME] [--print-schema]
               [--transport {auto,aiohttp,phoenix,websockets,appsync_http,appsync_websockets}]
               [--api-key API_KEY | --jwt JWT]

Positional Arguments


the server url starting with http://, https://, ws:// or wss://

Named Arguments

-V, --variables

query variables in the form key:json_value

-H, --headers

http headers in the form key:value


show program’s version number and exit

-d, --debug

print lots of debugging statements (loglevel==DEBUG)

-v, --verbose

show low level messages (loglevel==INFO)

-o, --operation-name

set the operation_name value


get the schema from instrospection and print it

Default: False


Possible choices: auto, aiohttp, phoenix, websockets, appsync_http, appsync_websockets

select the transport. ‘auto’ by default: aiohttp or websockets depending on url scheme

Default: “auto”

AWS AppSync options

By default, for an AppSync backend, the IAM authentication is chosen.

If you want API key or JWT authentication, you can provide one of the following arguments:


Provide an API key for authentication


Provide an JSON Web token for authentication


Simple query using https

$ echo 'query { continent(code:"AF") { name } }' | gql-cli
{"continent": {"name": "Africa"}}

Simple query using websockets

$ echo 'query { continent(code:"AF") { name } }' | gql-cli wss://
{"continent": {"name": "Africa"}}

Query with variable

$ echo 'query getContinent($code:ID!) { continent(code:$code) { name } }' | gql-cli --variables code:AF
{"continent": {"name": "Africa"}}

Interactive usage

Insert your query in the terminal, then press Ctrl-D to execute it.

$ gql-cli wss:// --variables code:AF

Execute query saved in a file

Put the query in a file:

$ echo 'query {
  continent(code:"AF") {
}' > query.gql

Then execute query from the file:

$ cat query.gql | gql-cli wss://
{"continent": {"name": "Africa"}}