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

   1 NAME
   2
   3     graphql - Command-line GraphQL client
   4
   5 VERSION
   6
   7     version 0.604
   8
   9 SYNOPSIS
  10
  11         graphql <URL> <QUERY> [ [--variables JSON] | [--variable KEY=VALUE]... ]
  12                 [--operation-name NAME] [--transport KEY=VALUE]...
  13                 [--[no-]unpack] [--filter JSONPATH]
  14                 [--format json|json:pretty|yaml|perl|csv|tsv|table] [--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. See "EXAMPLES" to see what this looks
 126     like in practice.
 127
 128     Use --no-unpack to disable if unpack mode was enabled via
 129     GRAPHQL_CLIENT_OPTIONS.
 130
 131  --filter JSONPATH
 132
 133     Filter the response based on a JSONPath expression.
 134
 135     Requires JSON::Path.
 136
 137     Alias: -p
 138
 139 FORMAT
 140
 141     The argument for "--format STR" can be one of:
 142
 143       * csv - Comma-separated values (requires Text::CSV)
 144
 145       * json:pretty - Human-readable JSON (default)
 146
 147       * json - JSON
 148
 149       * perl - Perl code (requires Data::Dumper)
 150
 151       * table - Table (requires Text::Table::Any)
 152
 153       * tsv - Tab-separated values (requires Text::CSV)
 154
 155       * yaml - YAML (requires YAML)
 156
 157     The csv, tsv, and table formats will only work if the response has a
 158     particular shape:
 159
 160         {
 161             "data" : {
 162                 "onefield" : [
 163                     {
 164                         "key" : "value",
 165                         ...
 166                     },
 167                     ...
 168                 ]
 169             }
 170         }
 171
 172     or
 173
 174         {
 175             "data" : {
 176                 "onefield" : [
 177                     "value",
 178                     ...
 179                 ]
 180             }
 181         }
 182
 183     If the response cannot be formatted, the default format will be used
 184     instead, an error message will be printed to STDERR, and the program
 185     will exit 3.
 186
 187     Table formatting can be done by one of several different modules, each
 188     with its own features and bugs. The default module is
 189     Text::Table::Tiny, but this can be overridden using the PERL_TEXT_TABLE
 190     environment variable if desired, like this:
 191
 192         PERL_TEXT_TABLE=Text::Table::HTML graphql ... -f table
 193
 194     The list of supported modules is at "@BACKENDS" in Text::Table::Any.
 195
 196 EXAMPLES
 197
 198     Different ways to provide the query/mutation to execute:
 199
 200         graphql http://myserver/graphql {hello}
 201
 202         echo {hello} | graphql http://myserver/graphql
 203
 204         graphql http://myserver/graphql <<END
 205         > {hello}
 206         > END
 207
 208         graphql http://myserver/graphql
 209         Interactive mode engaged! Waiting for a query on <STDIN>...
 210         {hello}
 211         ^D
 212
 213     Execute a query with variables:
 214
 215         graphql http://myserver/graphql <<END --var episode=JEDI
 216         > query HeroNameAndFriends($episode: Episode) {
 217         >   hero(episode: $episode) {
 218         >     name
 219         >     friends {
 220         >       name
 221         >     }
 222         >   }
 223         > }
 224         > END
 225
 226         graphql http://myserver/graphql --vars '{"episode":"JEDI"}'
 227
 228     Configure the transport:
 229
 230         graphql http://myserver/graphql {hello} -t headers.authorization='Basic s3cr3t'
 231
 232     This example shows the effect of "--unpack":
 233
 234         graphql http://myserver/graphql {hello}
 235
 236         # Output:
 237         {
 238             "data" : {
 239                 "hello" : "Hello world!"
 240             }
 241         }
 242
 243         graphql http://myserver/graphql {hello} --unpack
 244
 245         # Output:
 246         {
 247             "hello" : "Hello world!"
 248         }
 249
 250 ENVIRONMENT
 251
 252     Some environment variables affect the way graphql behaves:
 253
 254       * GRAPHQL_CLIENT_DEBUG - Set to 1 to print diagnostic messages to
 255       STDERR.
 256
 257       * GRAPHQL_CLIENT_HTTP_USER_AGENT - Set the HTTP user agent string.
 258
 259       * GRAPHQL_CLIENT_OPTIONS - Set the default set of options.
 260
 261       * PERL_TEXT_TABLE - Set table format backend; see "FORMAT".
 262
 263 EXIT STATUS
 264
 265     Here is a consolidated summary of what exit statuses mean:
 266
 267       * 0 - Success
 268
 269       * 1 - Client or server errors
 270
 271       * 2 - Option usage is wrong
 272
 273       * 3 - Could not format the response as requested
 274
 275 SEE ALSO
 276
 277       * GraphQL::Client - Programmatic interface
 278
 279 BUGS
 280
 281     Please report any bugs or feature requests on the bugtracker website
 282     https://github.com/chazmcgarvey/graphql-client/issues
 283
 284     When submitting a bug or request, please include a test-file or a patch
 285     to an existing test-file that illustrates the bug or desired feature.
 286
 287 AUTHOR
 288
 289     Charles McGarvey <chazmcgarvey@brokenzipper.com>
 290
 291 COPYRIGHT AND LICENSE
 292
 293     This software is copyright (c) 2020 by Charles McGarvey.
 294
 295     This is free software; you can redistribute it and/or modify it under
 296     the same terms as the Perl 5 programming language system itself.
 297