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

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