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. See L</EXAMPLES> to see what this looks like in
 116 practice.
 117
 118 Use C<--no-unpack> to disable if unpack mode was enabled via C<GRAPHQL_CLIENT_OPTIONS>.
 119
 120 =head1 FORMAT
 121
 122 The argument for L</"--format STR"> can be one of:
 123
 124 =for :list
 125 * C<csv> - Comma-separated values (requires L<Text::CSV>)
 126 * C<json:pretty> - Human-readable JSON (default)
 127 * C<json> - JSON
 128 * C<perl> - Perl code (requires L<Data::Dumper>)
 129 * C<table> - Table (requires L<Text::Table::Any>)
 130 * C<tsv> - Tab-separated values (requires L<Text::CSV>)
 131 * C<yaml> - YAML (requires L<YAML>)
 132
 133 The C<csv>, C<tsv>, and C<table> formats will only work if the response has a particular shape:
 134
 135     {
 136         "data" : {
 137             "onefield" : [
 138                 {
 139                     "key" : "value",
 140                     ...
 141                 },
 142                 ...
 143             ]
 144         }
 145     }
 146
 147 or
 148
 149     {
 150         "data" : {
 151             "onefield" : [
 152                 "value",
 153                 ...
 154             ]
 155         }
 156     }
 157
 158 If the response cannot be formatted, the default format will be used instead, an error message will
 159 be printed to STDERR, and the program will exit 3.
 160
 161 Table formatting can be done by one of several different modules, each with its own features and
 162 bugs. The default module is L<Text::Table::Tiny>, but this can be overridden using the
 163 C<PERL_TEXT_TABLE> environment variable if desired, like this:
 164
 165     PERL_TEXT_TABLE=Text::Table::HTML graphql ... -f table
 166
 167 The list of supported modules is at L<Text::Table::Any/@BACKENDS>.
 168
 169 =head1 EXAMPLES
 170
 171 Different ways to provide the query/mutation to execute:
 172
 173     graphql http://myserver/graphql {hello}
 174
 175     echo {hello} | graphql http://myserver/graphql
 176
 177     graphql http://myserver/graphql <<END
 178     > {hello}
 179     > END
 180
 181     graphql http://myserver/graphql
 182     Interactive mode engaged! Waiting for a query on <STDIN>...
 183     {hello}
 184     ^D
 185
 186 Execute a query with variables:
 187
 188     graphql http://myserver/graphql <<END --var episode=JEDI
 189     > query HeroNameAndFriends($episode: Episode) {
 190     >   hero(episode: $episode) {
 191     >     name
 192     >     friends {
 193     >       name
 194     >     }
 195     >   }
 196     > }
 197     > END
 198
 199     graphql http://myserver/graphql --vars '{"episode":"JEDI"}'
 200
 201 Configure the transport:
 202
 203     graphql http://myserver/graphql {hello} -t headers.authorization='Basic s3cr3t'
 204
 205 This example shows the effect of L</--unpack>:
 206
 207     graphql http://myserver/graphql {hello}
 208
 209     # Output:
 210     {
 211         "data" : {
 212             "hello" : "Hello world!"
 213         }
 214     }
 215
 216     graphql http://myserver/graphql {hello} --unpack
 217
 218     # Output:
 219     {
 220         "hello" : "Hello world!"
 221     }
 222
 223 =head1 ENVIRONMENT
 224
 225 Some environment variables affect the way C<graphql> behaves:
 226
 227 =for :list
 228 * C<GRAPHQL_CLIENT_DEBUG> - Set to 1 to print diagnostic messages to STDERR.
 229 * C<GRAPHQL_CLIENT_HTTP_USER_AGENT> - Set the HTTP user agent string.
 230 * C<GRAPHQL_CLIENT_OPTIONS> - Set the default set of options.
 231 * C<PERL_TEXT_TABLE> - Set table format backend; see L</FORMAT>.
 232
 233 =head1 EXIT STATUS
 234
 235 Here is a consolidated summary of what exit statuses mean:
 236
 237 =for :list
 238 * C<0> - Success
 239 * C<1> - Client or server errors
 240 * C<2> - Option usage is wrong
 241 * C<3> - Could not format the response as requested
 242
 243 =head1 SEE ALSO
 244
 245 =for :list
 246 * L<GraphQL::Client> - Programmatic interface
 247
 248 =cut
 249
 250 # FATPACK - Do not remove this line.
 251
 252 use warnings;
 253 use strict;
 254
 255 use GraphQL::Client::CLI;
 256
 257 our $VERSION = '999.999'; # VERSION
 258
 259 GraphQL::Client::CLI->main(@ARGV);