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