3 graphql - Command-line GraphQL client
11 graphql <URL> <QUERY> [ [--variables JSON] | [--variable KEY=VALUE]... ]
12 [--operation-name NAME] [--transport KEY=VALUE]...
13 [--[no-]unpack] [--filter JSONPATH]
14 [--format json|json:pretty|yaml|perl|csv|tsv|table] [--output FILE]
16 graphql --version|--help|--manual
20 graphql is a command-line program for executing queries and mutations
21 on a GraphQL <https://graphql.org/> server.
25 There are several ways to install graphql to your system.
29 You can install graphql using cpanm:
35 You can also choose to download graphql as a self-contained executable:
37 curl -OL https://raw.githubusercontent.com/chazmcgarvey/graphql-client/solo/graphql
40 To hack on the code, clone the repo instead:
42 git clone https://github.com/chazmcgarvey/graphql-client.git
44 make bootstrap # installs dependencies; requires cpanm
50 The URL of the GraphQL server endpoint.
52 If no --url option is given, the first argument is assumed to be the
55 This option is required.
61 The query or mutation to execute.
63 If no --query option is given, the next argument (after URL) is assumed
66 If the value is "-" (which is the default), the query will be read from
69 See: https://graphql.org/learn/queries/
75 Provide the variables as a JSON object.
81 An alternative way to provide variables one at a time. This option can
82 be repeated to provide multiple variables.
84 If used in combination with "--variables JSON", this option is silently
87 See: https://graphql.org/learn/queries/#variables
93 Inform the server which query/mutation to execute.
99 Write the response to a file instead of STDOUT.
103 --transport KEY=VALUE
105 Key-value pairs for configuring the transport (usually HTTP).
111 Specify the output format to use. See "FORMAT".
119 By default, the response structure is printed as-is from the server,
120 and the program exits 0.
122 When unpack mode is enabled, if the response completes with no errors,
123 only the data section of the response is printed and the program exits
124 0. If the response has errors, the whole response structure is printed
125 as-is and the program exits 1. See "EXAMPLES" to see what this looks
128 Use --no-unpack to disable if unpack mode was enabled via
129 GRAPHQL_CLIENT_OPTIONS.
133 Filter the response based on a JSONPath expression.
141 The argument for "--format STR" can be one of:
143 * csv - Comma-separated values (requires Text::CSV)
145 * json:pretty - Human-readable JSON (default)
149 * perl - Perl code (requires Data::Dumper)
151 * table - Table (requires Text::Table::Any)
153 * tsv - Tab-separated values (requires Text::CSV)
155 * yaml - YAML (requires YAML)
157 The csv, tsv, and table formats will only work if the response has a
183 If the response cannot be formatted, the default format will be used
184 instead, an error message will be printed to STDERR, and the program
187 Table formatting can be done by one of several different modules, each
188 with its own features and bugs. The default module is
189 Text::Table::Tiny, but this can be overridden using the PERL_TEXT_TABLE
190 environment variable if desired, like this:
192 PERL_TEXT_TABLE=Text::Table::HTML graphql ... -f table
194 The list of supported modules is at "@BACKENDS" in Text::Table::Any.
198 Different ways to provide the query/mutation to execute:
200 graphql http://myserver/graphql {hello}
202 echo {hello} | graphql http://myserver/graphql
204 graphql http://myserver/graphql <<END
208 graphql http://myserver/graphql
209 Interactive mode engaged! Waiting for a query on <STDIN>...
213 Execute a query with variables:
215 graphql http://myserver/graphql <<END --var episode=JEDI
216 > query HeroNameAndFriends($episode: Episode) {
217 > hero(episode: $episode) {
226 graphql http://myserver/graphql --vars '{"episode":"JEDI"}'
228 Configure the transport:
230 graphql http://myserver/graphql {hello} -t headers.authorization='Basic s3cr3t'
232 This example shows the effect of "--unpack":
234 graphql http://myserver/graphql {hello}
239 "hello" : "Hello world!"
243 graphql http://myserver/graphql {hello} --unpack
247 "hello" : "Hello world!"
252 Some environment variables affect the way graphql behaves:
254 * GRAPHQL_CLIENT_DEBUG - Set to 1 to print diagnostic messages to
257 * GRAPHQL_CLIENT_HTTP_USER_AGENT - Set the HTTP user agent string.
259 * GRAPHQL_CLIENT_OPTIONS - Set the default set of options.
261 * PERL_TEXT_TABLE - Set table format backend; see "FORMAT".
265 Here is a consolidated summary of what exit statuses mean:
269 * 1 - Client or server errors
271 * 2 - Option usage is wrong
273 * 3 - Could not format the response as requested
277 * GraphQL::Client - Programmatic interface
281 Please report any bugs or feature requests on the bugtracker website
282 https://github.com/chazmcgarvey/graphql-client/issues
284 When submitting a bug or request, please include a test-file or a patch
285 to an existing test-file that illustrates the bug or desired feature.
289 Charles McGarvey <ccm@cpan.org>
293 jwright <jwright@ecstuning.com>
295 COPYRIGHT AND LICENSE
297 This software is copyright (c) 2020 by Charles McGarvey.
299 This is free software; you can redistribute it and/or modify it under
300 the same terms as the Perl 5 programming language system itself.