# 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

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

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