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.603'; # 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.603
  30
  31 =head1 SYNOPSIS
  32
  33     graphql <URL> <QUERY> [ [--variables JSON] | [--variable KEY=VALUE]... ]
  34             [--operation-name NAME] [--transport KEY=VALUE]...
  35             [--[no-]unpack] [--format json|json:pretty|yaml|perl|csv|tsv|table]
  36             [--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 =head1 FORMAT
 147
 148 The argument for L</"--format STR"> can be one of:
 149
 150 =over 4
 151
 152 =item *
 153
 154 C<csv> - Comma-separated values (requires L<Text::CSV>)
 155
 156 =item *
 157
 158 C<json:pretty> - Human-readable JSON (default)
 159
 160 =item *
 161
 162 C<json> - JSON
 163
 164 =item *
 165
 166 C<perl> - Perl code (requires L<Data::Dumper>)
 167
 168 =item *
 169
 170 C<table> - Table (requires L<Text::Table::Any>)
 171
 172 =item *
 173
 174 C<tsv> - Tab-separated values (requires L<Text::CSV>)
 175
 176 =item *
 177
 178 C<yaml> - YAML (requires L<YAML>)
 179
 180 =back
 181
 182 The C<csv>, C<tsv>, and C<table> formats will only work if the response has a particular shape:
 183
 184     {
 185         "data" : {
 186             "onefield" : [
 187                 {
 188                     "key" : "value",
 189                     ...
 190                 },
 191                 ...
 192             ]
 193         }
 194     }
 195
 196 or
 197
 198     {
 199         "data" : {
 200             "onefield" : [
 201                 "value",
 202                 ...
 203             ]
 204         }
 205     }
 206
 207 If the response cannot be formatted, the default format will be used instead, an error message will
 208 be printed to STDERR, and the program will exit 3.
 209
 210 Table formatting can be done by one of several different modules, each with its own features and
 211 bugs. The default module is L<Text::Table::Tiny>, but this can be overridden using the
 212 C<PERL_TEXT_TABLE> environment variable if desired, like this:
 213
 214     PERL_TEXT_TABLE=Text::Table::HTML graphql ... -f table
 215
 216 The list of supported modules is at L<Text::Table::Any/@BACKENDS>.
 217
 218 =head1 EXAMPLES
 219
 220 Different ways to provide the query/mutation to execute:
 221
 222     graphql http://myserver/graphql {hello}
 223
 224     echo {hello} | graphql http://myserver/graphql
 225
 226     graphql http://myserver/graphql <<END
 227     > {hello}
 228     > END
 229
 230     graphql http://myserver/graphql
 231     Interactive mode engaged! Waiting for a query on <STDIN>...
 232     {hello}
 233     ^D
 234
 235 Execute a query with variables:
 236
 237     graphql http://myserver/graphql <<END --var episode=JEDI
 238     > query HeroNameAndFriends($episode: Episode) {
 239     >   hero(episode: $episode) {
 240     >     name
 241     >     friends {
 242     >       name
 243     >     }
 244     >   }
 245     > }
 246     > END
 247
 248     graphql http://myserver/graphql --vars '{"episode":"JEDI"}'
 249
 250 Configure the transport:
 251
 252     graphql http://myserver/graphql {hello} -t headers.authorization='Basic s3cr3t'
 253
 254 This example shows the effect of L</--unpack>:
 255
 256     graphql http://myserver/graphql {hello}
 257
 258     # Output:
 259     {
 260         "data" : {
 261             "hello" : "Hello world!"
 262         }
 263     }
 264
 265     graphql http://myserver/graphql {hello} --unpack
 266
 267     # Output:
 268     {
 269         "hello" : "Hello world!"
 270     }
 271
 272 =head1 ENVIRONMENT
 273
 274 Some environment variables affect the way C<graphql> behaves:
 275
 276 =over 4
 277
 278 =item *
 279
 280 C<GRAPHQL_CLIENT_DEBUG> - Set to 1 to print diagnostic messages to STDERR.
 281
 282 =item *
 283
 284 C<GRAPHQL_CLIENT_HTTP_USER_AGENT> - Set the HTTP user agent string.
 285
 286 =item *
 287
 288 C<GRAPHQL_CLIENT_OPTIONS> - Set the default set of options.
 289
 290 =item *
 291
 292 C<PERL_TEXT_TABLE> - Set table format backend; see L</FORMAT>.
 293
 294 =back
 295
 296 =head1 EXIT STATUS
 297
 298 Here is a consolidated summary of what exit statuses mean:
 299
 300 =over 4
 301
 302 =item *
 303
 304 C<0> - Success
 305
 306 =item *
 307
 308 C<1> - Client or server errors
 309
 310 =item *
 311
 312 C<2> - Option usage is wrong
 313
 314 =item *
 315
 316 C<3> - Could not format the response as requested
 317
 318 =back
 319
 320 =head1 SEE ALSO
 321
 322 =over 4
 323
 324 =item *
 325
 326 L<GraphQL::Client> - Programmatic interface
 327
 328 =back
 329
 330 =head1 BUGS
 331
 332 Please report any bugs or feature requests on the bugtracker website
 333 L<https://github.com/chazmcgarvey/graphql-client/issues>
 334
 335 When submitting a bug or request, please include a test-file or a
 336 patch to an existing test-file that illustrates the bug or desired
 337 feature.
 338
 339 =head1 AUTHOR
 340
 341 Charles McGarvey <chazmcgarvey@brokenzipper.com>
 342
 343 =head1 COPYRIGHT AND LICENSE
 344
 345 This software is copyright (c) 2020 by Charles McGarvey.
 346
 347 This is free software; you can redistribute it and/or modify it under
 348 the same terms as the Perl 5 programming language system itself.
 349
 350 =cut