gql-cli¶
GQL provides a python 3.7+ script, called gql-cli which allows you to execute GraphQL queries directly from the terminal.
This script supports http(s) or websockets protocols.
Usage¶
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]
[--schema-download [SCHEMA_DOWNLOAD ...]]
[--execute-timeout EXECUTE_TIMEOUT]
[--transport {auto,aiohttp,phoenix,websockets,appsync_http,appsync_websockets}]
[--api-key API_KEY | --jwt JWT]
server
Named Arguments¶
- -V, --variables
query variables in the form key:json_value
- -H, --headers
http headers in the form key:value
- --version
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
- --print-schema
get the schema from instrospection and print it
Default: False
- --schema-download
- select the introspection query arguments to download the schema.
Only useful if –print-schema is used. By default, it will:
request field descriptions
not request deprecated input fields
Possible options:
descriptions:false for a compact schema without comments
input_value_deprecation:true to download deprecated input fields
specified_by_url:true
schema_description:true
directive_is_repeatable:true
- --execute-timeout
set the execute_timeout argument of the Client (default: 10)
Default: 10
- --transport
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:
- --api-key
Provide an API key for authentication
- --jwt
Provide an JSON Web token for authentication
Examples¶
Simple query using https¶
$ echo 'query { continent(code:"AF") { name } }' | gql-cli https://countries.trevorblades.com
{"continent": {"name": "Africa"}}
Simple query using websockets¶
$ echo 'query { continent(code:"AF") { name } }' | gql-cli wss://countries.trevorblades.com/graphql
{"continent": {"name": "Africa"}}
Query with variable¶
$ echo 'query getContinent($code:ID!) { continent(code:$code) { name } }' | gql-cli https://countries.trevorblades.com --variables code:AF
{"continent": {"name": "Africa"}}
Interactive usage¶
Insert your query in the terminal, then press Ctrl-D to execute it.
$ gql-cli wss://countries.trevorblades.com/graphql --variables code:AF
Execute query saved in a file¶
Put the query in a file:
$ echo 'query {
continent(code:"AF") {
name
}
}' > query.gql
Then execute query from the file:
$ cat query.gql | gql-cli wss://countries.trevorblades.com/graphql
{"continent": {"name": "Africa"}}
Print the GraphQL schema in a file¶
$ gql-cli https://countries.trevorblades.com/graphql --print-schema > schema.graphql
Note
By default, deprecated input fields are not requested from the backend.
You can add --schema-download input_value_deprecation:true
to request them.
Note
You can add --schema-download descriptions:false
to request a compact schema
without comments.