1HTTP(1) User Commands HTTP(1)
2
3
4
6 http - manual page for http 2.4.0
7
9 usage: http [--json] [--form] [--multipart] [--boundary BOUNDARY]
10 [--compress]
11
12 [--pretty {all,colors,format,none}] [--style STYLE] [--unsorted]
13 [--sorted] [--format-options FORMAT_OPTIONS] [--print WHAT]
14 [--headers] [--body] [--verbose] [--all] [--history-print WHAT]
15 [--stream] [--output FILE] [--download] [--continue] [--quiet]
16 [--session SESSION_NAME_OR_PATH | --session-read-only SES‐
17 SION_NAME_OR_PATH] [--auth USER[:PASS]] [--auth-type {basic,di‐
18 gest}] [--ignore-netrc] [--offline] [--proxy PROTOCOL:PROXY_URL]
19 [--follow] [--max-redirects MAX_REDIRECTS] [--max-headers
20 MAX_HEADERS] [--timeout SECONDS] [--check-status] [--path-as-is]
21 [--chunked] [--verify VERIFY] [--ssl
22 {ssl2.3,tls1,tls1.1,tls1.2}] [--ciphers CIPHERS] [--cert CERT]
23 [--cert-key CERT_KEY] [--ignore-stdin] [--help] [--version]
24 [--traceback] [--default-scheme DEFAULT_SCHEME] [--debug]
25 [METHOD] URL [REQUEST_ITEM ...]
26
27 HTTPie: command-line HTTP client for the API era. <https://httpie.org>
28
29 Positional Arguments:
30
31 These arguments come after any flags and in the order they are
32 listed here. Only URL is required.
33
34 METHOD
35
36 The HTTP method to be used for the request (GET, POST, PUT,
37 DELETE, ...).
38
39 This argument can be omitted in which case HTTPie will use POST
40 if there is some data to be sent, otherwise GET:
41
42 $ http example.org # => GET
43 $ http example.org hello=world # => POST
44
45 URL
46
47 The scheme defaults to 'http://' if the URL does not include
48 one. (You can override this with: --default-scheme=https)
49
50 You can also use a shorthand for localhost
51
52 $ http :3000 # => http://localhost:3000
53 $ http :/foo # => http://localhost/foo
54
55 REQUEST_ITEM
56
57 Optional key-value pairs to be included in the request. The sep‐
58 arator used determines the type:
59
60 ':' HTTP headers:
61
62 Referer:http://httpie.org
63 Cookie:foo=bar User-Agent:bacon/1.0
64
65 '==' URL parameters to be appended to the request URI:
66
67 search==httpie
68
69 '=' Data fields to be serialized into a JSON object (with
70 --json, -j)
71
72 or form data (with --form, -f):
73
74 name=HTTPie
75 language=Python description='CLI HTTP client'
76
77 ':=' Non-string JSON data fields (only with --json, -j):
78
79 awesome:=true
80 amount:=42 colors:='["red", "green", "blue"]'
81
82 '@' Form file fields (only with --form or --multipart):
83
84 cv@~/Documents/CV.pdf cv@'~/Documents/CV.pdf;type=applica‐
85 tion/pdf'
86
87 '=@' A data field like '=', but takes a file path and embeds its
88 content:
89
90 essay=@Documents/essay.txt
91
92 ':=@' A raw JSON field like ':=', but takes a file path and em‐
93 beds its content:
94
95 package:=@./package.json
96
97 You can use a backslash to escape a colliding separator in the
98 field name:
99
100 field-name-with\:colon=value
101
102 Predefined Content Types:
103 --json, -j
104
105 (default) Data items from the command line are serialized as a
106 JSON object. The Content-Type and Accept headers are set to ap‐
107 plication/json (if not specified).
108
109 --form, -f
110
111 Data items from the command line are serialized as form fields.
112
113 The Content-Type is set to application/x-www-form-urlencoded (if
114 not specified). The presence of any file fields results in a
115 multipart/form-data request.
116
117 --multipart
118
119 Similar to --form, but always sends a multipart/form-data re‐
120 quest (i.e., even without files).
121
122 --boundary BOUNDARY
123
124 Specify a custom boundary string for multipart/form-data re‐
125 quests. Only has effect only together with --form.
126
127 Content Processing Options:
128 --compress, -x
129
130 Content compressed (encoded) with Deflate algorithm. The Con‐
131 tent-Encoding header is set to deflate.
132
133 Compression is skipped if it appears that compression ratio is
134 negative. Compression can be forced by repeating the argument.
135
136 Output Processing:
137 --pretty {all,colors,format,none}
138
139 Controls output processing. The value can be "none" to not pret‐
140 tify the output (default for redirected output), "all" to apply
141 both colors and formatting (default for terminal output), "col‐
142 ors", or "format".
143
144 --style STYLE, -s STYLE
145
146 Output coloring style (default is "auto"). It can be One of:
147
148 abap, algol, algol_nu, arduino, auto, autumn, borland, bw,
149
150 colorful, default, emacs, friendly, fruity, igor, inkpot,
151 lovelace, manni, monokai, murphy, native, paraiso-dark,
152 paraiso-light, pastie, perldoc, rainbow_dash, rrt, sas, solar‐
153 ized, solarized-dark, solarized-light, stata, statadark,
154 stata-light, tango, trac, vim, vs, xcode
155
156 The "auto" style follows your terminal's ANSI color styles.
157
158 For non-auto styles to work properly, please make sure that the
159 $TERM environment variable is set to "xterm-256color" or similar
160 (e.g., via `export TERM=xterm-256color' in your ~/.bashrc).
161
162 --unsorted
163
164 Disables all sorting while formatting output. It is a shortcut
165 for:
166
167 --format-options=headers.sort:false,json.sort_keys:false
168
169 --sorted
170
171 Re-enables all sorting options while formatting output. It is a
172 shortcut for:
173
174 --format-options=headers.sort:true,json.sort_keys:true
175
176 --format-options FORMAT_OPTIONS
177
178 Controls output formatting. Only relevant when formatting is en‐
179 abled through (explicit or implied) --pretty=all or
180 --pretty=format. The following are the default options:
181
182 headers.sort:true json.format:true json.indent:4
183 json.sort_keys:true
184
185 You may use this option multiple times, as well as specify mul‐
186 tiple comma-separated options at the same time. For example,
187 this modifies the settings to disable the sorting of JSON keys,
188 and sets the indent size to 2:
189
190 --format-options json.sort_keys:false,json.indent:2
191
192 This is something you will typically put into your config file.
193
194 Output Options:
195 --print WHAT, -p WHAT
196
197 String specifying what the output should contain:
198
199 'H' request headers 'B' request body 'h' response headers 'b'
200 response body
201
202 The default behaviour is 'hb' (i.e., the response headers and
203 body is printed), if standard output is not redirected. If the
204 output is piped to another program or to a file, then only the
205 response body is printed by default.
206
207 --headers, -h
208
209 Print only the response headers. Shortcut for --print=h.
210
211 --body, -b
212
213 Print only the response body. Shortcut for --print=b.
214
215 --verbose, -v
216
217 Verbose output. Print the whole request as well as the response.
218 Also print any intermediary requests/responses (such as redi‐
219 rects). It's a shortcut for: --all --print=hbBH
220
221 --all
222
223 By default, only the final request/response is shown. Use this
224 flag to show any intermediary requests/responses as well. Inter‐
225 mediary requests include followed redirects (with --follow), the
226 first unauthorized request when Digest auth is used (--auth=di‐
227 gest), etc.
228
229 --history-print WHAT, -P WHAT
230
231 The same as --print, -p but applies only to intermediary re‐
232 quests/responses (such as redirects) when their inclusion is en‐
233 abled with --all. If this options is not specified, then they
234 are formatted the same way as the final response.
235
236 --stream, -S
237
238 Always stream the response body by line, i.e., behave like `tail
239 -f'.
240
241 Without --stream and with --pretty (either set or implied),
242 HTTPie fetches the whole response before it outputs the pro‐
243 cessed data.
244
245 Set this option when you want to continuously display a pretti‐
246 fied long-lived response, such as one from the Twitter streaming
247 API.
248
249 It is useful also without --pretty: It ensures that the output
250 is flushed more often and in smaller chunks.
251
252 --output FILE, -o FILE
253
254 Save output to FILE instead of stdout. If --download is also
255 set, then only the response body is saved to FILE. Other parts
256 of the HTTP exchange are printed to stderr.
257
258 --download, -d
259
260 Do not print the response body to stdout. Rather, download it
261 and store it in a file. The filename is guessed unless specified
262 with --output [filename]. This action is similar to the default
263 behaviour of wget.
264
265 --continue, -c
266
267 Resume an interrupted download. Note that the --output option
268 needs to be specified as well.
269
270 --quiet, -q
271
272 Do not print to stdout or stderr. stdout is still redirected if
273 --output is specified. Flag doesn't affect behaviour of down‐
274 load beyond not printing to terminal.
275
276 Sessions:
277 --session SESSION_NAME_OR_PATH
278
279 Create, or reuse and update a session. Within a session, custom
280 headers, auth credential, as well as any cookies sent by the
281 server persist between requests.
282
283 Session files are stored in:
284
285 /builddir/.config/httpie/sessions/<HOST>/<SESSION_NAME>.json.
286
287 --session-read-only SESSION_NAME_OR_PATH
288
289 Create or read a session without updating it form the re‐
290 quest/response exchange.
291
292 Authentication:
293 --auth USER[:PASS], -a USER[:PASS]
294
295 If only the username is provided (-a username), HTTPie will
296 prompt for the password.
297
298 --auth-type {basic,digest}, -A {basic,digest}
299
300 The authentication mechanism to be used. Defaults to "basic".
301
302 "basic": Basic HTTP auth "digest": Digest HTTP auth
303
304 --ignore-netrc
305
306 Ignore credentials from .netrc.
307
308 Network:
309 --offline
310
311 Build the request and print it but donâ.t actually send it.
312
313 --proxy PROTOCOL:PROXY_URL
314
315 String mapping protocol to the URL of the proxy (e.g.
316 http:http://foo.bar:3128). You can specify multiple proxies with
317 different protocols. The environment variables $ALL_PROXY,
318 $HTTP_PROXY, and $HTTPS_proxy are supported as well.
319
320 --follow, -F
321
322 Follow 30x Location redirects.
323
324 --max-redirects MAX_REDIRECTS
325
326 By default, requests have a limit of 30 redirects (works with
327 --follow).
328
329 --max-headers MAX_HEADERS
330
331 The maximum number of response headers to be read before giving
332 up (default 0, i.e., no limit).
333
334 --timeout SECONDS
335
336 The connection timeout of the request in seconds. The default
337 value is 0, i.e., there is no timeout limit. This is not a time
338 limit on the entire response download; rather, an error is re‐
339 ported if the server has not issued a response for timeout sec‐
340 onds (more precisely, if no bytes have been received on the un‐
341 derlying socket for timeout seconds).
342
343 --check-status
344
345 By default, HTTPie exits with 0 when no network or other fatal
346 errors occur. This flag instructs HTTPie to also check the HTTP
347 status code and exit with an error if the status indicates one.
348
349 When the server replies with a 4xx (Client Error) or 5xx (Server
350 Error) status code, HTTPie exits with 4 or 5 respectively. If
351 the response is a 3xx (Redirect) and --follow hasn't been set,
352 then the exit status is 3. Also an error message is written to
353 stderr if stdout is redirected.
354
355 --path-as-is
356
357 Bypass dot segment (/../ or /./) URL squashing.
358
359 --chunked
360
361 SSL:
362 --verify VERIFY
363
364 Set to "no" (or "false") to skip checking the host's SSL cer‐
365 tificate. Defaults to "yes" ("true"). You can also pass the
366 path to a CA_BUNDLE file for private certs. (Or you can set the
367 REQUESTS_CA_BUNDLE environment variable instead.)
368
369 --ssl {ssl2.3,tls1,tls1.1,tls1.2}
370
371 The desired protocol version to use. This will default to SSL
372 v2.3 which will negotiate the highest protocol that both the
373 server and your installation of OpenSSL support. Available pro‐
374 tocols may vary depending on OpenSSL installation (only the sup‐
375 ported ones are shown here).
376
377 --ciphers CIPHERS
378
379 A string in the OpenSSL cipher list format. By default, the fol‐
380 lowing is used:
381
382 ECDHE+AESGCM:ECDHE+CHACHA20:DHE+AESGCM:DHE+CHACHA20:ECDH+AES‐
383 GCM:DH+AESGCM:ECDH+AES:DH+AES:RSA+AESGCM:RSA+AES:!aN‐
384 ULL:!eNULL:!MD5:!DSS
385
386 --cert CERT
387
388 You can specify a local cert to use as client side SSL certifi‐
389 cate. This file may either contain both private key and cer‐
390 tificate or you may specify --cert-key separately.
391
392 --cert-key CERT_KEY
393
394 The private key to use with SSL. Only needed if --cert is given
395 and the certificate file does not contain the private key.
396
397 Troubleshooting:
398 --ignore-stdin, -I
399
400 Do not attempt to read stdin.
401
402 --help
403
404 Show this help message and exit.
405
406 --version
407
408 Show version and exit.
409
410 --traceback
411
412 Prints the exception traceback should one occur.
413
414 --default-scheme DEFAULT_SCHEME
415
416 The default scheme to use if not specified in the URL.
417
418 --debug
419
420 Prints the exception traceback should one occur, as well as
421 other information useful for debugging HTTPie itself and for re‐
422 porting bugs.
423
424 For every --OPTION there is also a --no-OPTION that reverts OPTION to
425 its default value.
426
427 Suggestions and bug reports are greatly appreciated:
428
429 https://github.com/httpie/httpie/issues
430
432 The full documentation for http is maintained as a Texinfo manual. If
433 the info and http programs are properly installed at your site, the
434 command
435
436 info http
437
438 should give you access to the complete manual.
439
440
441
442http 2.4.0 May 2021 HTTP(1)