# gql-cli

GQL provides a python 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,httpx,phoenix,websockets,aiohttp_websockets,appsync_http,appsync_websockets}]
                   [--api-key API_KEY | --jwt JWT]
                   server

### Positional Arguments

`server`

  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

`--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

    > - request deprecated input fields

    Possible options:

    > - descriptions:false for a compact schema without comments

    > - input_value_deprecation:false to omit deprecated input fields

    > - specified_by_url:true

    > - schema_description:true

    > - directive_is_repeatable:true

    > - input_object_one_of:true

`--execute-timeout`

  set the execute_timeout argument of the Client (default: 10)

  Default: `10`

`--transport`

  Possible choices: auto, aiohttp, httpx, phoenix, websockets, aiohttp_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

You can add `--schema-download descriptions:false` to request a compact schema without comments.

Warning

By default, from gql version 4.0, deprecated input fields are requested from the backend. It is possible that some old backends do not support this feature. In that case you can add `--schema-download input_value_deprecation:false` to go back to the previous behavior.