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

   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 on
  21 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](https://metacpan.org/pod/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 URL.
  53
  54 This option is required.
  55
  56 Alias: `-u`
  57
  58 ## `--query STR`
  59
  60 The query or mutation to execute.
  61
  62 If no `--query` option is given, the next argument (after URL) is assumed to be the query.
  63
  64 If the value is "-" (which is the default), the query will be read from `STDIN`.
  65
  66 See: [https://graphql.org/learn/queries/](https://graphql.org/learn/queries/)
  67
  68 Alias: `--mutation`
  69
  70 ## `--variables JSON`
  71
  72 Provide the variables as a JSON object.
  73
  74 Aliases: `--vars`, `-V`
  75
  76 ## `--variable KEY=VALUE`
  77
  78 An alternative way to provide variables one at a time. This option can be repeated to provide
  79 multiple variables.
  80
  81 If used in combination with ["--variables JSON"](#variables-json), this option is silently ignored.
  82
  83 See: [https://graphql.org/learn/queries/#variables](https://graphql.org/learn/queries/#variables)
  84
  85 Aliases: `--var`, `-d`
  86
  87 ## `--operation-name NAME`
  88
  89 Inform the server which query/mutation to execute.
  90
  91 Alias: `-n`
  92
  93 ## `--output FILE`
  94
  95 Write the response to a file instead of STDOUT.
  96
  97 Alias: `-o`
  98
  99 ## `--transport KEY=VALUE`
 100
 101 Key-value pairs for configuring the transport (usually HTTP).
 102
 103 Alias: `-t`
 104
 105 ## `--format STR`
 106
 107 Specify the output format to use. See ["FORMAT"](#format).
 108
 109 Alias: `-f`
 110
 111 ## `--unpack`
 112
 113 Enables unpack mode.
 114
 115 By default, the response structure is printed as-is from the server, and the program exits 0.
 116
 117 When unpack mode is enabled, if the response completes with no errors, only the data section of
 118 the response is printed and the program exits 0. If the response has errors, the whole response
 119 structure is printed as-is and the program exits 1. See ["EXAMPLES"](#examples) to see what this looks like in
 120 practice.
 121
 122 Use `--no-unpack` to disable if unpack mode was enabled via `GRAPHQL_CLIENT_OPTIONS`.
 123
 124 ## `--filter JSONPATH`
 125
 126 Filter the response based on a [JSONPath](https://metacpan.org/pod/JSON%3A%3APath#SYNOPSIS) expression.
 127
 128 Requires [JSON::Path](https://metacpan.org/pod/JSON%3A%3APath).
 129
 130 Alias: `-p`
 131
 132 # FORMAT
 133
 134 The argument for ["--format STR"](#format-str) can be one of:
 135
 136 - `csv` - Comma-separated values (requires [Text::CSV](https://metacpan.org/pod/Text%3A%3ACSV))
 137 - `json:pretty` - Human-readable JSON (default)
 138 - `json` - JSON
 139 - `perl` - Perl code (requires [Data::Dumper](https://metacpan.org/pod/Data%3A%3ADumper))
 140 - `table` - Table (requires [Text::Table::Any](https://metacpan.org/pod/Text%3A%3ATable%3A%3AAny))
 141 - `tsv` - Tab-separated values (requires [Text::CSV](https://metacpan.org/pod/Text%3A%3ACSV))
 142 - `yaml` - YAML (requires [YAML](https://metacpan.org/pod/YAML))
 143
 144 The `csv`, `tsv`, and `table` formats will only work if the response has a particular shape:
 145
 146     {
 147         "data" : {
 148             "onefield" : [
 149                 {
 150                     "key" : "value",
 151                     ...
 152                 },
 153                 ...
 154             ]
 155         }
 156     }
 157
 158 or
 159
 160     {
 161         "data" : {
 162             "onefield" : [
 163                 "value",
 164                 ...
 165             ]
 166         }
 167     }
 168
 169 If the response cannot be formatted, the default format will be used instead, an error message will
 170 be printed to STDERR, and the program will exit 3.
 171
 172 Table formatting can be done by one of several different modules, each with its own features and
 173 bugs. The default module is [Text::Table::Tiny](https://metacpan.org/pod/Text%3A%3ATable%3A%3ATiny), but this can be overridden using the
 174 `PERL_TEXT_TABLE` environment variable if desired, like this:
 175
 176     PERL_TEXT_TABLE=Text::Table::HTML graphql ... -f table
 177
 178 The list of supported modules is at ["@BACKENDS" in Text::Table::Any](https://metacpan.org/pod/Text%3A%3ATable%3A%3AAny#BACKENDS).
 179
 180 # EXAMPLES
 181
 182 Different ways to provide the query/mutation to execute:
 183
 184     graphql http://myserver/graphql {hello}
 185
 186     echo {hello} | graphql http://myserver/graphql
 187
 188     graphql http://myserver/graphql <<END
 189     > {hello}
 190     > END
 191
 192     graphql http://myserver/graphql
 193     Interactive mode engaged! Waiting for a query on <STDIN>...
 194     {hello}
 195     ^D
 196
 197 Execute a query with variables:
 198
 199     graphql http://myserver/graphql <<END --var episode=JEDI
 200     > query HeroNameAndFriends($episode: Episode) {
 201     >   hero(episode: $episode) {
 202     >     name
 203     >     friends {
 204     >       name
 205     >     }
 206     >   }
 207     > }
 208     > END
 209
 210     graphql http://myserver/graphql --vars '{"episode":"JEDI"}'
 211
 212 Configure the transport:
 213
 214     graphql http://myserver/graphql {hello} -t headers.authorization='Basic s3cr3t'
 215
 216 This example shows the effect of ["--unpack"](#unpack):
 217
 218     graphql http://myserver/graphql {hello}
 219
 220     # Output:
 221     {
 222         "data" : {
 223             "hello" : "Hello world!"
 224         }
 225     }
 226
 227     graphql http://myserver/graphql {hello} --unpack
 228
 229     # Output:
 230     {
 231         "hello" : "Hello world!"
 232     }
 233
 234 # ENVIRONMENT
 235
 236 Some environment variables affect the way `graphql` behaves:
 237
 238 - `GRAPHQL_CLIENT_DEBUG` - Set to 1 to print diagnostic messages to STDERR.
 239 - `GRAPHQL_CLIENT_HTTP_USER_AGENT` - Set the HTTP user agent string.
 240 - `GRAPHQL_CLIENT_OPTIONS` - Set the default set of options.
 241 - `PERL_TEXT_TABLE` - Set table format backend; see ["FORMAT"](#format).
 242
 243 # EXIT STATUS
 244
 245 Here is a consolidated summary of what exit statuses mean:
 246
 247 - `0` - Success
 248 - `1` - Client or server errors
 249 - `2` - Option usage is wrong
 250 - `3` - Could not format the response as requested
 251
 252 # SEE ALSO
 253
 254 - [GraphQL::Client](https://metacpan.org/pod/GraphQL%3A%3AClient) - Programmatic interface
 255
 256 # BUGS
 257
 258 Please report any bugs or feature requests on the bugtracker website
 259 [https://github.com/chazmcgarvey/graphql-client/issues](https://github.com/chazmcgarvey/graphql-client/issues)
 260
 261 When submitting a bug or request, please include a test-file or a
 262 patch to an existing test-file that illustrates the bug or desired
 263 feature.
 264
 265 # AUTHOR
 266
 267 Charles McGarvey <chazmcgarvey@brokenzipper.com>
 268
 269 # COPYRIGHT AND LICENSE
 270
 271 This software is copyright (c) 2020 by Charles McGarvey.
 272
 273 This is free software; you can redistribute it and/or modify it under
 274 the same terms as the Perl 5 programming language system itself.