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

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