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] [--format json|json:pretty|yaml|perl|csv|tsv|table]
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.
131 The argument for "--format STR" can be one of:
133 * csv - Comma-separated values (requires Text::CSV)
135 * json:pretty - Human-readable JSON (default)
139 * perl - Perl code (requires Data::Dumper)
141 * table - Table (requires Text::Table::Any)
143 * tsv - Tab-separated values (requires Text::CSV)
145 * yaml - YAML (requires YAML)
147 The csv, tsv, and table formats will only work if the response has a
173 If the response cannot be formatted, the default format will be used
174 instead, an error message will be printed to STDERR, and the program
177 Table formatting can be done by one of several different modules, each
178 with its own features and bugs. The default module is
179 Text::Table::Tiny, but this can be overridden using the PERL_TEXT_TABLE
180 environment variable if desired, like this:
182 PERL_TEXT_TABLE=Text::Table::HTML graphql ... -f table
184 The list of supported modules is at "@BACKENDS" in Text::Table::Any.
188 Different ways to provide the query/mutation to execute:
190 graphql http://myserver/graphql {hello}
192 echo {hello} | graphql http://myserver/graphql
194 graphql http://myserver/graphql <<END
198 graphql http://myserver/graphql
199 Interactive mode engaged! Waiting for a query on <STDIN>...
203 Execute a query with variables:
205 graphql http://myserver/graphql <<END --var episode=JEDI
206 > query HeroNameAndFriends($episode: Episode) {
207 > hero(episode: $episode) {
216 graphql http://myserver/graphql --vars '{"episode":"JEDI"}'
218 Configure the transport:
220 graphql http://myserver/graphql {hello} -t headers.authorization='Basic s3cr3t'
222 This example shows the effect of "--unpack":
224 graphql http://myserver/graphql {hello}
229 "hello" : "Hello world!"
233 graphql http://myserver/graphql {hello} --unpack
237 "hello" : "Hello world!"
242 Some environment variables affect the way graphql behaves:
244 * GRAPHQL_CLIENT_DEBUG - Set to 1 to print diagnostic messages to
247 * GRAPHQL_CLIENT_HTTP_USER_AGENT - Set the HTTP user agent string.
249 * GRAPHQL_CLIENT_OPTIONS - Set the default set of options.
251 * PERL_TEXT_TABLE - Set table format backend; see "FORMAT".
255 Here is a consolidated summary of what exit statuses mean:
259 * 1 - Client or server errors
261 * 2 - Option usage is wrong
263 * 3 - Could not format the response as requested
267 * GraphQL::Client - Programmatic interface
271 Please report any bugs or feature requests on the bugtracker website
272 https://github.com/chazmcgarvey/graphql-client/issues
274 When submitting a bug or request, please include a test-file or a patch
275 to an existing test-file that illustrates the bug or desired feature.
279 Charles McGarvey <chazmcgarvey@brokenzipper.com>
281 COPYRIGHT AND LICENSE
283 This software is copyright (c) 2020 by Charles McGarvey.
285 This is free software; you can redistribute it and/or modify it under
286 the same terms as the Perl 5 programming language system itself.