gqt 0.97.0

GraphQL client in the terminal.

Build and execute GraphQL queries in the terminal.

This project is inspired by https://graphiql-online.com.

Installation

pip3 install gqt

It’s recommended to install bat for pretty output.

Controls

• Press h or ? for help.

Examples

Set default GraphQL endpoint:

export GQT_ENDPOINT=https://mys-lang.org/graphql

Interactively create a query and execute it:

gqt

{
    "statistics": {
        "numberOfGraphqlRequests": 3
    }
}

Repeat last query:

gqt -r

{
    "statistics": {
        "numberOfGraphqlRequests": 4
    }
}

Print the query instead of executing it:

gqt -q

query Query {
  statistics {
    numberOfGraphqlRequests
  }
}

YAML output:

gqt -y

statistics:
  numberOfGraphqlRequests: 8

Name queries:

gqt -n stats -y

statistics:
  numberOfGraphqlRequests: 8

gqt -n time -y

standardLibrary:
  package:
    latestRelease:
      version: 0.20.0

gqt -n stats -y -r

statistics:
  numberOfGraphqlRequests: 9

gqt -n time -y -r

standardLibrary:
  package:
    latestRelease:
      version: 0.20.0

List cached queries:

gqt -l

Endpoint                      Query name
----------------------------  ------------
https://mys-lang.org/graphql  <default>
https://mys-lang.org/graphql  time
https://mys-lang.org/graphql  stats

Make arguments variables by pressing v or $ and give them as -v <name>=<value> on the command line:

gqt -v name=time -y

standardLibrary:
  package:
    latestRelease:
      version: 0.20.0

gqt -r -q

query Query($name: String!) {
  standardLibrary {
    package(name: $name) {
      latestRelease {
        version
      }
    }
  }
}

Print the schema:

gqt --print-schema

type Query {
  standardLibrary: StandardLibrary!
  statistics: Statistics!
  activities: [Activity!]!
}

type StandardLibrary {
  package(name: String!): Package!
  packages: [Package!]
  numberOfPackages: Int
  numberOfDownloads: Int
}
...

Known issues

• Unions are not implemented.

• There is one query cache per gqt version. Would be nice to keep the cache after upgrading gqt.

• The query is cleared when reloading the schema.

Ideas

• Search:

  Press / to search for visible fields. Press <Up> and <Down> to move to the previous and next search hit. Highlight all hits. Press <Enter> to end the search and move the cursor to the current hit. Press <Esc> to abort the search and restore the cursor to its pre-search position. Show number of hits.

  ╭─ Query
  │ ▼ search
  │   ▶ Book
  │     ■ title
  │   ▶ Author
  │     ■ name
  │ ▶ film
  │ ▶ films
  
  /fil                                                1 of 2 matches

• Unions:

  Always query __typename.

  union SearchResult = Book | Author
  
  type Book {
    title: String!
  }
  
  type Author {
    name: String!
  }
  
  type Query {
    search(contains: String): [SearchResult!]
  }
  
  Unselected:
  
  ╭─ Query
  │ ▶ search
  
  Selected:
  
  ╭─ Query
  │ ▼ search
  │   ▶ Book
  │     ■ title
  │   ▶ Author
  │     ■ name

• Alias?

  • Press a to create an alias.

  • Press d to delete an alias.

  smallPicture and mediumPicture are aliases of picture.

  ╭─ Query
  │ ▶ Book
  │   ▶ picture
  │   ▼ smallPicture: picture
  │     ■ width: 320
  │     ■ height: 240
  │   ▼ mediumPicture: picture
  │     ■ width: 800
  │     ■ height: 600

• Keep valid parts of any existing query when reloading the schema.

• Cache across updates.

  • Save introspection response.

  • Save last query.

  • Save cursor and possibly other state.

  -- ~/.cache/gqt/cache/generic/
     +-- <endpoint 1>
         +-- schema.json
         +-- query.graphql
         +-- state.json
         +-- query_names/
             +-- stats/
                 +-- schema.json
                 +-- query.graphql
                 +-- state.json

• Optionally give schema path on command line. For endpoints that does not support schema introspection.