Dogcows Code - chaz/graphql-client/blob - README

   1 NAME
   2
   3     graphql - Command-line GraphQL client
   4
   5 VERSION
   6
   7     version 0.602
   8
   9 SYNOPSIS
  10
  11         graphql <URL> <QUERY> [ [--variables JSON] | [--variable KEY=VALUE]... ]
  12                 [--operation-name NAME] [--transport KEY=VALUE]...
  13                 [--[no-]unpack] [--format json|json:pretty|yaml|perl|csv|tsv|table]
  14                 [--output FILE]
  15
  16         graphql --version|--help|--manual
  17
  18 DESCRIPTION
  19
  20     graphql is a command-line program for executing queries and mutations
  21     on a GraphQL <https://graphql.org/> server.
  22
  23 INSTALL
  24
  25     There are several ways to install graphql to your system.
  26
  27  from CPAN
  28
  29     You can install graphql using cpanm:
  30
  31         cpanm GraphQL::Client
  32
  33  from GitHub
  34
  35     You can also choose to download graphql as a self-contained executable:
  36
  37         curl -OL https://raw.githubusercontent.com/chazmcgarvey/graphql-client/solo/graphql
  38         chmod +x graphql
  39
  40     To hack on the code, clone the repo instead:
  41
  42         git clone https://github.com/chazmcgarvey/graphql-client.git
  43         cd graphql-client
  44         make bootstrap      # installs dependencies; requires cpanm
  45
  46 OPTIONS
  47
  48  --url URL
  49
  50     The URL of the GraphQL server endpoint.
  51
  52     If no --url option is given, the first argument is assumed to be the
  53     URL.
  54
  55     This option is required.
  56
  57     Alias: -u
  58
  59  --query STR
  60
  61     The query or mutation to execute.
  62
  63     If no --query option is given, the next argument (after URL) is assumed
  64     to be the query.
  65
  66     If the value is "-" (which is the default), the query will be read from
  67     STDIN.
  68
  69     See: https://graphql.org/learn/queries/
  70
  71     Alias: --mutation
  72
  73  --variables JSON
  74
  75     Provide the variables as a JSON object.
  76
  77     Aliases: --vars, -V
  78
  79  --variable KEY=VALUE
  80
  81     An alternative way to provide variables one at a time. This option can
  82     be repeated to provide multiple variables.
  83
  84     If used in combination with "--variables JSON", this option is silently
  85     ignored.
  86
  87     See: https://graphql.org/learn/queries/#variables
  88
  89     Aliases: --var, -d
  90
  91  --operation-name NAME
  92
  93     Inform the server which query/mutation to execute.
  94
  95     Alias: -n
  96
  97  --output FILE
  98
  99     Write the response to a file instead of STDOUT.
 100
 101     Alias: -o
 102
 103  --transport KEY=VALUE
 104
 105     Key-value pairs for configuring the transport (usually HTTP).
 106
 107     Alias: -t
 108
 109  --format STR
 110
 111     Specify the output format to use. See "FORMAT".
 112
 113     Alias: -f
 114
 115  --unpack
 116
 117     Enables unpack mode.
 118
 119     By default, the response structure is printed as-is from the server,
 120     and the program exits 0.
 121
 122     When unpack mode is enabled, if the response completes with no errors,
 123     only the data section of the response is printed and the program exits
 124     0. If the response has errors, the whole response structure is printed
 125     as-is and the program exits 1.
 126
 127     See "EXAMPLES".
 128
 129 FORMAT
 130
 131     The argument for "--format STR" can be one of:
 132
 133       * csv - Comma-separated values (requires Text::CSV)
 134
 135       * json:pretty - Human-readable JSON (default)
 136
 137       * json - JSON
 138
 139       * perl - Perl code (requires Data::Dumper)
 140
 141       * table - Table (requires Text::Table::Any)
 142
 143       * tsv - Tab-separated values (requires Text::CSV)
 144
 145       * yaml - YAML (requires YAML)
 146
 147     The csv, tsv, and table formats will only work if the response has a
 148     particular shape:
 149
 150         {
 151             "data" : {
 152                 "onefield" : [
 153                     {
 154                         "key" : "value",
 155                         ...
 156                     },
 157                     ...
 158                 ]
 159             }
 160         }
 161
 162     or
 163
 164         {
 165             "data" : {
 166                 "onefield" : [
 167                     "value",
 168                     ...
 169                 ]
 170             }
 171         }
 172
 173     If the response cannot be formatted, the default format will be used
 174     instead, an error message will be printed to STDERR, and the program
 175     will exit 3.
 176
 177     Table formatting can be done by one of several different modules, each
 178     with its own features and bugs. The default module is
 179     Text::Table::Tiny, but this can be overridden using the PERL_TEXT_TABLE
 180     environment variable if desired, like this:
 181
 182         PERL_TEXT_TABLE=Text::Table::HTML graphql ... -f table
 183
 184     The list of supported modules is at "@BACKENDS" in Text::Table::Any.
 185
 186 EXAMPLES
 187
 188     Different ways to provide the query/mutation to execute:
 189
 190         graphql http://myserver/graphql {hello}
 191
 192         echo {hello} | graphql http://myserver/graphql
 193
 194         graphql http://myserver/graphql <<END
 195         > {hello}
 196         > END
 197
 198         graphql http://myserver/graphql
 199         Interactive mode engaged! Waiting for a query on <STDIN>...
 200         {hello}
 201         ^D
 202
 203     Execute a query with variables:
 204
 205         graphql http://myserver/graphql <<END --var episode=JEDI
 206         > query HeroNameAndFriends($episode: Episode) {
 207         >   hero(episode: $episode) {
 208         >     name
 209         >     friends {
 210         >       name
 211         >     }
 212         >   }
 213         > }
 214         > END
 215
 216         graphql http://myserver/graphql --vars '{"episode":"JEDI"}'
 217
 218     Configure the transport:
 219
 220         graphql http://myserver/graphql {hello} -t headers.authorization='Basic s3cr3t'
 221
 222     This example shows the effect of "--unpack":
 223
 224         graphql http://myserver/graphql {hello}
 225
 226         # Output:
 227         {
 228             "data" : {
 229                 "hello" : "Hello world!"
 230             }
 231         }
 232
 233         graphql http://myserver/graphql {hello} --unpack
 234
 235         # Output:
 236         {
 237             "hello" : "Hello world!"
 238         }
 239
 240 ENVIRONMENT
 241
 242     Some environment variables affect the way graphql behaves:
 243
 244       * GRAPHQL_CLIENT_DEBUG - Set to 1 to print diagnostic messages to
 245       STDERR.
 246
 247       * GRAPHQL_CLIENT_HTTP_USER_AGENT - Set the HTTP user agent string.
 248
 249       * GRAPHQL_CLIENT_OPTIONS - Set the default set of options.
 250
 251       * PERL_TEXT_TABLE - Set table format backend; see "FORMAT".
 252
 253 EXIT STATUS
 254
 255     Here is a consolidated summary of what exit statuses mean:
 256
 257       * 0 - Success
 258
 259       * 1 - Client or server errors
 260
 261       * 2 - Option usage is wrong
 262
 263       * 3 - Could not format the response as requested
 264
 265 SEE ALSO
 266
 267       * GraphQL::Client - Programmatic interface
 268
 269 BUGS
 270
 271     Please report any bugs or feature requests on the bugtracker website
 272     https://github.com/chazmcgarvey/graphql-client/issues
 273
 274     When submitting a bug or request, please include a test-file or a patch
 275     to an existing test-file that illustrates the bug or desired feature.
 276
 277 AUTHOR
 278
 279     Charles McGarvey <chazmcgarvey@brokenzipper.com>
 280
 281 COPYRIGHT AND LICENSE
 282
 283     This software is copyright (c) 2020 by Charles McGarvey.
 284
 285     This is free software; you can redistribute it and/or modify it under
 286     the same terms as the Perl 5 programming language system itself.
 287