avoid fatpacking JSON::Path::Evaluator
[chaz/graphql-client] / README.md
1 # NAME
2
3 graphql - Command-line GraphQL client
4
5 # VERSION
6
7 version 0.604
8
9 # SYNOPSIS
10
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]
15
16 graphql --version|--help|--manual
17
18 # DESCRIPTION
19
20 `graphql` is a command-line program for executing queries and mutations on
21 a [GraphQL](https://graphql.org/) server.
22
23 # INSTALL
24
25 There are several ways to install `graphql` to your system.
26
27 ## from CPAN
28
29 You can install `graphql` using [cpanm](https://metacpan.org/pod/cpanm):
30
31 cpanm GraphQL::Client
32
33 ## from GitHub
34
35 You can also choose to download `graphql` as a self-contained executable:
36
37 curl -OL https://raw.githubusercontent.com/chazmcgarvey/graphql-client/solo/graphql
38 chmod +x graphql
39
40 To hack on the code, clone the repo instead:
41
42 git clone https://github.com/chazmcgarvey/graphql-client.git
43 cd graphql-client
44 make bootstrap # installs dependencies; requires cpanm
45
46 # OPTIONS
47
48 ## `--url URL`
49
50 The URL of the GraphQL server endpoint.
51
52 If no `--url` option is given, the first argument is assumed to be the URL.
53
54 This option is required.
55
56 Alias: `-u`
57
58 ## `--query STR`
59
60 The query or mutation to execute.
61
62 If no `--query` option is given, the next argument (after URL) is assumed to be the query.
63
64 If the value is "-" (which is the default), the query will be read from `STDIN`.
65
66 See: [https://graphql.org/learn/queries/](https://graphql.org/learn/queries/)
67
68 Alias: `--mutation`
69
70 ## `--variables JSON`
71
72 Provide the variables as a JSON object.
73
74 Aliases: `--vars`, `-V`
75
76 ## `--variable KEY=VALUE`
77
78 An alternative way to provide variables one at a time. This option can be repeated to provide
79 multiple variables.
80
81 If used in combination with ["--variables JSON"](#variables-json), this option is silently ignored.
82
83 See: [https://graphql.org/learn/queries/#variables](https://graphql.org/learn/queries/#variables)
84
85 Aliases: `--var`, `-d`
86
87 ## `--operation-name NAME`
88
89 Inform the server which query/mutation to execute.
90
91 Alias: `-n`
92
93 ## `--output FILE`
94
95 Write the response to a file instead of STDOUT.
96
97 Alias: `-o`
98
99 ## `--transport KEY=VALUE`
100
101 Key-value pairs for configuring the transport (usually HTTP).
102
103 Alias: `-t`
104
105 ## `--format STR`
106
107 Specify the output format to use. See ["FORMAT"](#format).
108
109 Alias: `-f`
110
111 ## `--unpack`
112
113 Enables unpack mode.
114
115 By default, the response structure is printed as-is from the server, and the program exits 0.
116
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
120 practice.
121
122 Use `--no-unpack` to disable if unpack mode was enabled via `GRAPHQL_CLIENT_OPTIONS`.
123
124 ## `--filter JSONPATH`
125
126 Filter the response based on a [JSONPath](https://metacpan.org/pod/JSON%3A%3APath#SYNOPSIS) expression.
127
128 Requires [JSON::Path](https://metacpan.org/pod/JSON%3A%3APath).
129
130 Alias: `-p`
131
132 # FORMAT
133
134 The argument for ["--format STR"](#format-str) can be one of:
135
136 - `csv` - Comma-separated values (requires [Text::CSV](https://metacpan.org/pod/Text%3A%3ACSV))
137 - `json:pretty` - Human-readable JSON (default)
138 - `json` - JSON
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))
143
144 The `csv`, `tsv`, and `table` formats will only work if the response has a particular shape:
145
146 {
147 "data" : {
148 "onefield" : [
149 {
150 "key" : "value",
151 ...
152 },
153 ...
154 ]
155 }
156 }
157
158 or
159
160 {
161 "data" : {
162 "onefield" : [
163 "value",
164 ...
165 ]
166 }
167 }
168
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.
171
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:
175
176 PERL_TEXT_TABLE=Text::Table::HTML graphql ... -f table
177
178 The list of supported modules is at ["@BACKENDS" in Text::Table::Any](https://metacpan.org/pod/Text%3A%3ATable%3A%3AAny#BACKENDS).
179
180 # EXAMPLES
181
182 Different ways to provide the query/mutation to execute:
183
184 graphql http://myserver/graphql {hello}
185
186 echo {hello} | graphql http://myserver/graphql
187
188 graphql http://myserver/graphql <<END
189 > {hello}
190 > END
191
192 graphql http://myserver/graphql
193 Interactive mode engaged! Waiting for a query on <STDIN>...
194 {hello}
195 ^D
196
197 Execute a query with variables:
198
199 graphql http://myserver/graphql <<END --var episode=JEDI
200 > query HeroNameAndFriends($episode: Episode) {
201 > hero(episode: $episode) {
202 > name
203 > friends {
204 > name
205 > }
206 > }
207 > }
208 > END
209
210 graphql http://myserver/graphql --vars '{"episode":"JEDI"}'
211
212 Configure the transport:
213
214 graphql http://myserver/graphql {hello} -t headers.authorization='Basic s3cr3t'
215
216 This example shows the effect of ["--unpack"](#unpack):
217
218 graphql http://myserver/graphql {hello}
219
220 # Output:
221 {
222 "data" : {
223 "hello" : "Hello world!"
224 }
225 }
226
227 graphql http://myserver/graphql {hello} --unpack
228
229 # Output:
230 {
231 "hello" : "Hello world!"
232 }
233
234 # ENVIRONMENT
235
236 Some environment variables affect the way `graphql` behaves:
237
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).
242
243 # EXIT STATUS
244
245 Here is a consolidated summary of what exit statuses mean:
246
247 - `0` - Success
248 - `1` - Client or server errors
249 - `2` - Option usage is wrong
250 - `3` - Could not format the response as requested
251
252 # SEE ALSO
253
254 - [GraphQL::Client](https://metacpan.org/pod/GraphQL%3A%3AClient) - Programmatic interface
255
256 # BUGS
257
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)
260
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
263 feature.
264
265 # AUTHOR
266
267 Charles McGarvey <chazmcgarvey@brokenzipper.com>
268
269 # COPYRIGHT AND LICENSE
270
271 This software is copyright (c) 2020 by Charles McGarvey.
272
273 This is free software; you can redistribute it and/or modify it under
274 the same terms as the Perl 5 programming language system itself.
This page took 0.043601 seconds and 4 git commands to generate.