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

   1 #! perl
   2 # ABSTRACT: Command-line GraphQL client
   3 # PODNAME: graphql
   4
   5 =head1 SYNOPSIS
   6
   7     graphql <URL> <QUERY> [ [--variables JSON] | [--variable KEY=VALUE]... ]
   8             [--operation-name NAME] [--transport KEY=VALUE]...
   9             [--[no-]unpack] [--format json|json:pretty|yaml|perl|csv|tsv|table]
  10             [--output FILE]
  11
  12     graphql --version|--help|--manual
  13
  14 =head1 DESCRIPTION
  15
  16 C<graphql> is a command-line program for executing queries and mutations on
  17 a L<GraphQL|https://graphql.org/> server.
  18
  19 =head1 INSTALL
  20
  21 There are several ways to install F<graphql> to your system.
  22
  23 =head2 from CPAN
  24
  25 You can install F<graphql> using L<cpanm>:
  26
  27     cpanm GraphQL::Client
  28
  29 =head2 from GitHub
  30
  31 You can also choose to download F<graphql> as a self-contained executable:
  32
  33     curl -OL https://raw.githubusercontent.com/chazmcgarvey/graphql-client/solo/graphql
  34     chmod +x graphql
  35
  36 To hack on the code, clone the repo instead:
  37
  38     git clone https://github.com/chazmcgarvey/graphql-client.git
  39     cd graphql-client
  40     make bootstrap      # installs dependencies; requires cpanm
  41
  42 =head1 OPTIONS
  43
  44 =head2 C<--url URL>
  45
  46 The URL of the GraphQL server endpoint.
  47
  48 If no C<--url> option is given, the first argument is assumed to be the URL.
  49
  50 This option is required.
  51
  52 Alias: C<-u>
  53
  54 =head2 C<--query STR>
  55
  56 The query or mutation to execute.
  57
  58 If no C<--query> option is given, the next argument (after URL) is assumed to be the query.
  59
  60 If the value is "-" (which is the default), the query will be read from C<STDIN>.
  61
  62 See: L<https://graphql.org/learn/queries/>
  63
  64 Alias: C<--mutation>
  65
  66 =head2 C<--variables JSON>
  67
  68 Provide the variables as a JSON object.
  69
  70 Aliases: C<--vars>, C<-V>
  71
  72 =head2 C<--variable KEY=VALUE>
  73
  74 An alternative way to provide variables one at a time. This option can be repeated to provide
  75 multiple variables.
  76
  77 If used in combination with L</"--variables JSON">, this option is silently ignored.
  78
  79 See: L<https://graphql.org/learn/queries/#variables>
  80
  81 Aliases: C<--var>, C<-d>
  82
  83 =head2 C<--operation-name NAME>
  84
  85 Inform the server which query/mutation to execute.
  86
  87 Alias: C<-n>
  88
  89 =head2 C<--output FILE>
  90
  91 Write the response to a file instead of STDOUT.
  92
  93 Alias: C<-o>
  94
  95 =head2 C<--transport KEY=VALUE>
  96
  97 Key-value pairs for configuring the transport (usually HTTP).
  98
  99 Alias: C<-t>
 100
 101 =head2 C<--format STR>
 102
 103 Specify the output format to use. See L</FORMAT>.
 104
 105 Alias: C<-f>
 106
 107 =head2 C<--unpack>
 108
 109 Enables unpack mode.
 110
 111 By default, the response structure is printed as-is from the server, and the program exits 0.
 112
 113 When unpack mode is enabled, if the response completes with no errors, only the data section of
 114 the response is printed and the program exits 0. If the response has errors, the whole response
 115 structure is printed as-is and the program exits 1.
 116
 117 See L</EXAMPLES>.
 118
 119 =head1 FORMAT
 120
 121 The argument for L</"--format STR"> can be one of:
 122
 123 =for :list
 124 * C<csv> - Comma-separated values (requires L<Text::CSV>)
 125 * C<json:pretty> - Human-readable JSON (default)
 126 * C<json> - JSON
 127 * C<perl> - Perl code (requires L<Data::Dumper>)
 128 * C<table> - Table (requires L<Text::Table::Any>)
 129 * C<tsv> - Tab-separated values (requires L<Text::CSV>)
 130 * C<yaml> - YAML (requires L<YAML>)
 131
 132 The C<csv>, C<tsv>, and C<table> formats will only work if the response has a particular shape:
 133
 134     {
 135         "data" : {
 136             "onefield" : [
 137                 {
 138                     "key" : "value",
 139                     ...
 140                 },
 141                 ...
 142             ]
 143         }
 144     }
 145
 146 or
 147
 148     {
 149         "data" : {
 150             "onefield" : [
 151                 "value",
 152                 ...
 153             ]
 154         }
 155     }
 156
 157 If the response cannot be formatted, the default format will be used instead, an error message will
 158 be printed to STDERR, and the program will exit 3.
 159
 160 Table formatting can be done by one of several different modules, each with its own features and
 161 bugs. The default module is L<Text::Table::Tiny>, but this can be overridden using the
 162 C<PERL_TEXT_TABLE> environment variable if desired, like this:
 163
 164     PERL_TEXT_TABLE=Text::Table::HTML graphql ... -f table
 165
 166 The list of supported modules is at L<Text::Table::Any/@BACKENDS>.
 167
 168 =head1 EXAMPLES
 169
 170 Different ways to provide the query/mutation to execute:
 171
 172     graphql http://myserver/graphql {hello}
 173
 174     echo {hello} | graphql http://myserver/graphql
 175
 176     graphql http://myserver/graphql <<END
 177     > {hello}
 178     > END
 179
 180     graphql http://myserver/graphql
 181     Interactive mode engaged! Waiting for a query on <STDIN>...
 182     {hello}
 183     ^D
 184
 185 Execute a query with variables:
 186
 187     graphql http://myserver/graphql <<END --var episode=JEDI
 188     > query HeroNameAndFriends($episode: Episode) {
 189     >   hero(episode: $episode) {
 190     >     name
 191     >     friends {
 192     >       name
 193     >     }
 194     >   }
 195     > }
 196     > END
 197
 198     graphql http://myserver/graphql --vars '{"episode":"JEDI"}'
 199
 200 Configure the transport:
 201
 202     graphql http://myserver/graphql {hello} -t headers.authorization='Basic s3cr3t'
 203
 204 This example shows the effect of L</--unpack>:
 205
 206     graphql http://myserver/graphql {hello}
 207
 208     # Output:
 209     {
 210         "data" : {
 211             "hello" : "Hello world!"
 212         }
 213     }
 214
 215     graphql http://myserver/graphql {hello} --unpack
 216
 217     # Output:
 218     {
 219         "hello" : "Hello world!"
 220     }
 221
 222 =head1 ENVIRONMENT
 223
 224 Some environment variables affect the way C<graphql> behaves:
 225
 226 =for :list
 227 * C<GRAPHQL_CLIENT_DEBUG> - Set to 1 to print diagnostic messages to STDERR.
 228 * C<GRAPHQL_CLIENT_HTTP_USER_AGENT> - Set the HTTP user agent string.
 229 * C<GRAPHQL_CLIENT_OPTIONS> - Set the default set of options.
 230 * C<PERL_TEXT_TABLE> - Set table format backend; see L</FORMAT>.
 231
 232 =head1 EXIT STATUS
 233
 234 Here is a consolidated summary of what exit statuses mean:
 235
 236 =for :list
 237 * C<0> - Success
 238 * C<1> - Client or server errors
 239 * C<2> - Option usage is wrong
 240 * C<3> - Could not format the response as requested
 241
 242 =head1 SEE ALSO
 243
 244 =for :list
 245 * L<GraphQL::Client> - Programmatic interface
 246
 247 =cut
 248
 249 # FATPACK - Do not remove this line.
 250
 251 use warnings;
 252 use strict;
 253
 254 use GraphQL::Client::CLI;
 255
 256 our $VERSION = '999.999'; # VERSION
 257
 258 GraphQL::Client::CLI->main(@ARGV);