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

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