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

   1 #! perl
   2 # ABSTRACT: Command-line GraphQL client
   3 # PODNAME: graphql
   4
   5
   6 # FATPACK - Do not remove this line.
   7
   8 use warnings;
   9 use strict;
  10
  11 use GraphQL::Client::CLI;
  12
  13 our $VERSION = '0.604'; # VERSION
  14
  15 GraphQL::Client::CLI->main(@ARGV);
  16
  17 __END__
  18
  19 =pod
  20
  21 =encoding UTF-8
  22
  23 =head1 NAME
  24
  25 graphql - Command-line GraphQL client
  26
  27 =head1 VERSION
  28
  29 version 0.604
  30
  31 =head1 SYNOPSIS
  32
  33     graphql <URL> <QUERY> [ [--variables JSON] | [--variable KEY=VALUE]... ]
  34             [--operation-name NAME] [--transport KEY=VALUE]...
  35             [--[no-]unpack] [--filter JSONPATH]
  36             [--format json|json:pretty|yaml|perl|csv|tsv|table] [--output FILE]
  37
  38     graphql --version|--help|--manual
  39
  40 =head1 DESCRIPTION
  41
  42 C<graphql> is a command-line program for executing queries and mutations on
  43 a L<GraphQL|https://graphql.org/> server.
  44
  45 =head1 INSTALL
  46
  47 There are several ways to install F<graphql> to your system.
  48
  49 =head2 from CPAN
  50
  51 You can install F<graphql> using L<cpanm>:
  52
  53     cpanm GraphQL::Client
  54
  55 =head2 from GitHub
  56
  57 You can also choose to download F<graphql> as a self-contained executable:
  58
  59     curl -OL https://raw.githubusercontent.com/chazmcgarvey/graphql-client/solo/graphql
  60     chmod +x graphql
  61
  62 To hack on the code, clone the repo instead:
  63
  64     git clone https://github.com/chazmcgarvey/graphql-client.git
  65     cd graphql-client
  66     make bootstrap      # installs dependencies; requires cpanm
  67
  68 =head1 OPTIONS
  69
  70 =head2 C<--url URL>
  71
  72 The URL of the GraphQL server endpoint.
  73
  74 If no C<--url> option is given, the first argument is assumed to be the URL.
  75
  76 This option is required.
  77
  78 Alias: C<-u>
  79
  80 =head2 C<--query STR>
  81
  82 The query or mutation to execute.
  83
  84 If no C<--query> option is given, the next argument (after URL) is assumed to be the query.
  85
  86 If the value is "-" (which is the default), the query will be read from C<STDIN>.
  87
  88 See: L<https://graphql.org/learn/queries/>
  89
  90 Alias: C<--mutation>
  91
  92 =head2 C<--variables JSON>
  93
  94 Provide the variables as a JSON object.
  95
  96 Aliases: C<--vars>, C<-V>
  97
  98 =head2 C<--variable KEY=VALUE>
  99
 100 An alternative way to provide variables one at a time. This option can be repeated to provide
 101 multiple variables.
 102
 103 If used in combination with L</"--variables JSON">, this option is silently ignored.
 104
 105 See: L<https://graphql.org/learn/queries/#variables>
 106
 107 Aliases: C<--var>, C<-d>
 108
 109 =head2 C<--operation-name NAME>
 110
 111 Inform the server which query/mutation to execute.
 112
 113 Alias: C<-n>
 114
 115 =head2 C<--output FILE>
 116
 117 Write the response to a file instead of STDOUT.
 118
 119 Alias: C<-o>
 120
 121 =head2 C<--transport KEY=VALUE>
 122
 123 Key-value pairs for configuring the transport (usually HTTP).
 124
 125 Alias: C<-t>
 126
 127 =head2 C<--format STR>
 128
 129 Specify the output format to use. See L</FORMAT>.
 130
 131 Alias: C<-f>
 132
 133 =head2 C<--unpack>
 134
 135 Enables unpack mode.
 136
 137 By default, the response structure is printed as-is from the server, and the program exits 0.
 138
 139 When unpack mode is enabled, if the response completes with no errors, only the data section of
 140 the response is printed and the program exits 0. If the response has errors, the whole response
 141 structure is printed as-is and the program exits 1. See L</EXAMPLES> to see what this looks like in
 142 practice.
 143
 144 Use C<--no-unpack> to disable if unpack mode was enabled via C<GRAPHQL_CLIENT_OPTIONS>.
 145
 146 =head2 C<--filter JSONPATH>
 147
 148 Filter the response based on a L<JSONPath|JSON::Path/SYNOPSIS> expression.
 149
 150 Requires L<JSON::Path>.
 151
 152 Alias: C<-p>
 153
 154 =head1 FORMAT
 155
 156 The argument for L</"--format STR"> can be one of:
 157
 158 =over 4
 159
 160 =item *
 161
 162 C<csv> - Comma-separated values (requires L<Text::CSV>)
 163
 164 =item *
 165
 166 C<json:pretty> - Human-readable JSON (default)
 167
 168 =item *
 169
 170 C<json> - JSON
 171
 172 =item *
 173
 174 C<perl> - Perl code (requires L<Data::Dumper>)
 175
 176 =item *
 177
 178 C<table> - Table (requires L<Text::Table::Any>)
 179
 180 =item *
 181
 182 C<tsv> - Tab-separated values (requires L<Text::CSV>)
 183
 184 =item *
 185
 186 C<yaml> - YAML (requires L<YAML>)
 187
 188 =back
 189
 190 The C<csv>, C<tsv>, and C<table> formats will only work if the response has a particular shape:
 191
 192     {
 193         "data" : {
 194             "onefield" : [
 195                 {
 196                     "key" : "value",
 197                     ...
 198                 },
 199                 ...
 200             ]
 201         }
 202     }
 203
 204 or
 205
 206     {
 207         "data" : {
 208             "onefield" : [
 209                 "value",
 210                 ...
 211             ]
 212         }
 213     }
 214
 215 If the response cannot be formatted, the default format will be used instead, an error message will
 216 be printed to STDERR, and the program will exit 3.
 217
 218 Table formatting can be done by one of several different modules, each with its own features and
 219 bugs. The default module is L<Text::Table::Tiny>, but this can be overridden using the
 220 C<PERL_TEXT_TABLE> environment variable if desired, like this:
 221
 222     PERL_TEXT_TABLE=Text::Table::HTML graphql ... -f table
 223
 224 The list of supported modules is at L<Text::Table::Any/@BACKENDS>.
 225
 226 =head1 EXAMPLES
 227
 228 Different ways to provide the query/mutation to execute:
 229
 230     graphql http://myserver/graphql {hello}
 231
 232     echo {hello} | graphql http://myserver/graphql
 233
 234     graphql http://myserver/graphql <<END
 235     > {hello}
 236     > END
 237
 238     graphql http://myserver/graphql
 239     Interactive mode engaged! Waiting for a query on <STDIN>...
 240     {hello}
 241     ^D
 242
 243 Execute a query with variables:
 244
 245     graphql http://myserver/graphql <<END --var episode=JEDI
 246     > query HeroNameAndFriends($episode: Episode) {
 247     >   hero(episode: $episode) {
 248     >     name
 249     >     friends {
 250     >       name
 251     >     }
 252     >   }
 253     > }
 254     > END
 255
 256     graphql http://myserver/graphql --vars '{"episode":"JEDI"}'
 257
 258 Configure the transport:
 259
 260     graphql http://myserver/graphql {hello} -t headers.authorization='Basic s3cr3t'
 261
 262 This example shows the effect of L</--unpack>:
 263
 264     graphql http://myserver/graphql {hello}
 265
 266     # Output:
 267     {
 268         "data" : {
 269             "hello" : "Hello world!"
 270         }
 271     }
 272
 273     graphql http://myserver/graphql {hello} --unpack
 274
 275     # Output:
 276     {
 277         "hello" : "Hello world!"
 278     }
 279
 280 =head1 ENVIRONMENT
 281
 282 Some environment variables affect the way C<graphql> behaves:
 283
 284 =over 4
 285
 286 =item *
 287
 288 C<GRAPHQL_CLIENT_DEBUG> - Set to 1 to print diagnostic messages to STDERR.
 289
 290 =item *
 291
 292 C<GRAPHQL_CLIENT_HTTP_USER_AGENT> - Set the HTTP user agent string.
 293
 294 =item *
 295
 296 C<GRAPHQL_CLIENT_OPTIONS> - Set the default set of options.
 297
 298 =item *
 299
 300 C<PERL_TEXT_TABLE> - Set table format backend; see L</FORMAT>.
 301
 302 =back
 303
 304 =head1 EXIT STATUS
 305
 306 Here is a consolidated summary of what exit statuses mean:
 307
 308 =over 4
 309
 310 =item *
 311
 312 C<0> - Success
 313
 314 =item *
 315
 316 C<1> - Client or server errors
 317
 318 =item *
 319
 320 C<2> - Option usage is wrong
 321
 322 =item *
 323
 324 C<3> - Could not format the response as requested
 325
 326 =back
 327
 328 =head1 SEE ALSO
 329
 330 =over 4
 331
 332 =item *
 333
 334 L<GraphQL::Client> - Programmatic interface
 335
 336 =back
 337
 338 =head1 BUGS
 339
 340 Please report any bugs or feature requests on the bugtracker website
 341 L<https://github.com/chazmcgarvey/graphql-client/issues>
 342
 343 When submitting a bug or request, please include a test-file or a
 344 patch to an existing test-file that illustrates the bug or desired
 345 feature.
 346
 347 =head1 AUTHOR
 348
 349 Charles McGarvey <chazmcgarvey@brokenzipper.com>
 350
 351 =head1 COPYRIGHT AND LICENSE
 352
 353 This software is copyright (c) 2020 by Charles McGarvey.
 354
 355 This is free software; you can redistribute it and/or modify it under
 356 the same terms as the Perl 5 programming language system itself.
 357
 358 =cut