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