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