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 on
21 a [GraphQL](https://graphql.org/) server.
25 There are several ways to install `graphql` to your system.
29 You can install `graphql` using [cpanm](https://metacpan.org/pod/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 URL.
54 This option is required.
60 The query or mutation to execute.
62 If no `--query` option is given, the next argument (after URL) is assumed to be the query.
64 If the value is "-" (which is the default), the query will be read from `STDIN`.
66 See: [https://graphql.org/learn/queries/](https://graphql.org/learn/queries/)
72 Provide the variables as a JSON object.
74 Aliases: `--vars`, `-V`
76 ## `--variable KEY=VALUE`
78 An alternative way to provide variables one at a time. This option can be repeated to provide
81 If used in combination with ["--variables JSON"](#variables-json), this option is silently ignored.
83 See: [https://graphql.org/learn/queries/#variables](https://graphql.org/learn/queries/#variables)
85 Aliases: `--var`, `-d`
87 ## `--operation-name NAME`
89 Inform the server which query/mutation to execute.
95 Write the response to a file instead of STDOUT.
99 ## `--transport KEY=VALUE`
101 Key-value pairs for configuring the transport (usually HTTP).
107 Specify the output format to use. See ["FORMAT"](#format).
115 By default, the response structure is printed as-is from the server, and the program exits 0.
117 When unpack mode is enabled, if the response completes with no errors, only the data section of
118 the response is printed and the program exits 0. If the response has errors, the whole response
119 structure is printed as-is and the program exits 1. See ["EXAMPLES"](#examples) to see what this looks like in
122 Use `--no-unpack` to disable if unpack mode was enabled via `GRAPHQL_CLIENT_OPTIONS`.
124 ## `--filter JSONPATH`
126 Filter the response based on a [JSONPath](https://metacpan.org/pod/JSON%3A%3APath#SYNOPSIS) expression.
128 Requires [JSON::Path](https://metacpan.org/pod/JSON%3A%3APath).
134 The argument for ["--format STR"](#format-str) can be one of:
136 - `csv` - Comma-separated values (requires [Text::CSV](https://metacpan.org/pod/Text%3A%3ACSV))
137 - `json:pretty` - Human-readable JSON (default)
139 - `perl` - Perl code (requires [Data::Dumper](https://metacpan.org/pod/Data%3A%3ADumper))
140 - `table` - Table (requires [Text::Table::Any](https://metacpan.org/pod/Text%3A%3ATable%3A%3AAny))
141 - `tsv` - Tab-separated values (requires [Text::CSV](https://metacpan.org/pod/Text%3A%3ACSV))
142 - `yaml` - YAML (requires [YAML](https://metacpan.org/pod/YAML))
144 The `csv`, `tsv`, and `table` formats will only work if the response has a particular shape:
169 If the response cannot be formatted, the default format will be used instead, an error message will
170 be printed to STDERR, and the program will exit 3.
172 Table formatting can be done by one of several different modules, each with its own features and
173 bugs. The default module is [Text::Table::Tiny](https://metacpan.org/pod/Text%3A%3ATable%3A%3ATiny), but this can be overridden using the
174 `PERL_TEXT_TABLE` environment variable if desired, like this:
176 PERL_TEXT_TABLE=Text::Table::HTML graphql ... -f table
178 The list of supported modules is at ["@BACKENDS" in Text::Table::Any](https://metacpan.org/pod/Text%3A%3ATable%3A%3AAny#BACKENDS).
182 Different ways to provide the query/mutation to execute:
184 graphql http://myserver/graphql {hello}
186 echo {hello} | graphql http://myserver/graphql
188 graphql http://myserver/graphql <<END
192 graphql http://myserver/graphql
193 Interactive mode engaged! Waiting for a query on <STDIN>...
197 Execute a query with variables:
199 graphql http://myserver/graphql <<END --var episode=JEDI
200 > query HeroNameAndFriends($episode: Episode) {
201 > hero(episode: $episode) {
210 graphql http://myserver/graphql --vars '{"episode":"JEDI"}'
212 Configure the transport:
214 graphql http://myserver/graphql {hello} -t headers.authorization='Basic s3cr3t'
216 This example shows the effect of ["--unpack"](#unpack):
218 graphql http://myserver/graphql {hello}
223 "hello" : "Hello world!"
227 graphql http://myserver/graphql {hello} --unpack
231 "hello" : "Hello world!"
236 Some environment variables affect the way `graphql` behaves:
238 - `GRAPHQL_CLIENT_DEBUG` - Set to 1 to print diagnostic messages to STDERR.
239 - `GRAPHQL_CLIENT_HTTP_USER_AGENT` - Set the HTTP user agent string.
240 - `GRAPHQL_CLIENT_OPTIONS` - Set the default set of options.
241 - `PERL_TEXT_TABLE` - Set table format backend; see ["FORMAT"](#format).
245 Here is a consolidated summary of what exit statuses mean:
248 - `1` - Client or server errors
249 - `2` - Option usage is wrong
250 - `3` - Could not format the response as requested
254 - [GraphQL::Client](https://metacpan.org/pod/GraphQL%3A%3AClient) - Programmatic interface
258 Please report any bugs or feature requests on the bugtracker website
259 [https://github.com/chazmcgarvey/graphql-client/issues](https://github.com/chazmcgarvey/graphql-client/issues)
261 When submitting a bug or request, please include a test-file or a
262 patch to an existing test-file that illustrates the bug or desired
267 Charles McGarvey <ccm@cpan.org>
271 jwright <jwright@ecstuning.com>
273 # COPYRIGHT AND LICENSE
275 This software is copyright (c) 2020 by Charles McGarvey.
277 This is free software; you can redistribute it and/or modify it under
278 the same terms as the Perl 5 programming language system itself.