1https(1)                         HTTPie Manual                        https(1)
2
3
4

NAME

6       https
7

SYNOPSIS

9       https [METHOD] URL [REQUEST_ITEM ...]
10
11

DESCRIPTION

13       HTTPie: modern, user-friendly command-line HTTP client for the API era.
14       <https://httpie.io>
15

Positional arguments

17       These arguments come after any flags and in the order they  are  listed
18       here.  Only URL is required.
19
20
21       METHOD
22
23
24              The  HTTP  method  to  be  used for the request (GET, POST, PUT,
25              DELETE, ...).
26
27              This argument can be omitted in which case HTTPie will use  POST
28              if there is some data to be sent, otherwise GET:
29
30                  $ http example.org               # => GET
31                  $ http example.org hello=world   # => POST
32
33
34
35
36       URL
37
38
39              The  request  URL.  Scheme defaults to 'http://' if the URL does
40              not  include  one.  (You  can  override  this  with:  --default-
41              scheme=http/https)
42
43              You can also use a shorthand for localhost
44
45                  $ http :3000                    # => http://localhost:3000
46                  $ http :/foo                    # => http://localhost/foo
47
48
49
50
51       REQUEST_ITEM
52
53
54              Optional key-value pairs to be included in the request. The sep‐
55              arator used determines the type:
56
57              ':' HTTP headers:
58
59                  Referer:https://httpie.io   Cookie:foo=bar    User-Agent:ba‐
60              con/1.0
61
62              '==' URL parameters to be appended to the request URI:
63
64                  search==httpie
65
66              '='  Data  fields  to  be  serialized  into  a JSON object (with
67              --json, -j)
68                  or form data (with --form, -f):
69
70                  name=HTTPie  language=Python  description='CLI HTTP client'
71
72              ':=' Non-string JSON data fields (only with --json, -j):
73
74                  awesome:=true    amount:=42     colors:='["red",    "green",
75              "blue"]'
76
77              '@' Form file fields (only with --form or --multipart):
78
79                  cv@~/Documents/CV.pdf
80                  cv@'~/Documents/CV.pdf;type=application/pdf'
81
82              '=@' A data field like '=', but takes a file path and embeds its
83              content:
84
85                  essay=@Documents/essay.txt
86
87              ':=@' A raw JSON field like ':=', but takes a file path and  em‐
88              beds its content:
89
90                  package:=@./package.json
91
92              You  can  use a backslash to escape a colliding separator in the
93              field name:
94
95                  field-name-with\:colon=value
96
97
98
99

Predefined content types

101       --json, -j
102
103
104              (default) Data items from the command line are serialized  as  a
105              JSON object.  The Content-Type and Accept headers are set to ap‐
106              plication/json (if not specified).
107
108
109
110
111       --form, -f
112
113
114              Data items from the command line are serialized as form fields.
115
116              The Content-Type is set to application/x-www-form-urlencoded (if
117              not  specified).  The  presence  of any file fields results in a
118              multipart/form-data request.
119
120
121
122
123       --multipart
124
125
126              Similar to --form, but always sends  a  multipart/form-data  re‐
127              quest (i.e., even without files).
128
129
130
131       --boundary
132
133
134              Specify  a  custom  boundary  string for multipart/form-data re‐
135              quests. Only has effect only together with --form.
136
137
138
139       --raw
140
141
142              This option allows you to pass raw request  data  without  extra
143              processing (as opposed to the structured request items syntax):
144
145                  $ http --raw='data' pie.dev/post
146
147              You can achieve the same by piping the data via stdin:
148
149                  $ echo data | http pie.dev/post
150
151              Or have HTTPie load the raw data from a file:
152
153                  $ http pie.dev/post @data.txt
154
155
156
157
158

Content processing options

160       --compress, -x
161
162
163              Content  compressed  (encoded) with Deflate algorithm.  The Con‐
164              tent-Encoding header is set to deflate.
165
166              Compression is skipped if it appears that compression  ratio  is
167              negative. Compression can be forced by repeating the argument.
168
169
170
171

Output processing

173       --pretty
174
175
176              Controls output processing. The value can be "none" to not pret‐
177              tify the output (default for redirected output), "all" to  apply
178              both  colors and formatting (default for terminal output), "col‐
179              ors", or "format".
180
181
182
183
184       --style, -s STYLE
185
186
187              Output coloring style (default is "auto"). It can be one of:
188
189                  auto, pie, pie-dark, pie-light, solarized
190
191
192              For finding out all available styles in your system, try:
193
194              $ http --style
195
196              The "auto" style follows your terminal's ANSI color styles.  For
197              non-auto  styles  to  work  properly,  please make sure that the
198              $TERM environment variable is set to "xterm-256color" or similar
199              (e.g., via `export TERM=xterm-256color' in your ~/.bashrc).
200
201
202       --unsorted
203
204
205              Disables  all  sorting while formatting output. It is a shortcut
206              for:
207
208                  --format-options=headers.sort:false,json.sort_keys:false
209
210
211
212
213       --sorted
214
215
216              Re-enables all sorting options while formatting output. It is  a
217              shortcut for:
218
219                  --format-options=headers.sort:true,json.sort_keys:true
220
221
222
223
224       --response-charset ENCODING
225
226
227              Override  the  response  encoding for terminal display purposes,
228              e.g.:
229
230                  --response-charset=utf8
231                  --response-charset=big5
232
233
234
235
236       --response-mime MIME_TYPE
237
238
239              Override the response mime type for coloring and formatting  for
240              the terminal, e.g.:
241
242                  --response-mime=application/json
243                  --response-mime=text/xml
244
245
246
247
248       --format-options
249
250
251              Controls output formatting. Only relevant when formatting is en‐
252              abled   through   (explicit   or   implied)   --pretty=all    or
253              --pretty=format.  The following are the default options:
254
255                  headers.sort:true
256                  json.format:true
257                  json.indent:4
258                  json.sort_keys:true
259                  xml.format:true
260                  xml.indent:2
261
262              You  may use this option multiple times, as well as specify mul‐
263              tiple comma-separated options at the  same  time.  For  example,
264              this  modifies the settings to disable the sorting of JSON keys,
265              and sets the indent size to 2:
266
267                  --format-options json.sort_keys:false,json.indent:2
268
269              This is something you will typically put into your config file.
270
271
272
273

Output options

275       --print, -p WHAT
276
277
278              String specifying what the output should contain:
279
280                  'H' request headers
281                  'B' request body
282                  'h' response headers
283                  'b' response body
284                  'm' response metadata
285
286              The default behaviour is 'hb' (i.e., the  response  headers  and
287              body  is printed), if standard output is not redirected.  If the
288              output is piped to another program or to a file, then  only  the
289              response body is printed by default.
290
291
292
293
294       --headers, -h
295
296
297              Print only the response headers. Shortcut for --print=h.
298
299
300
301
302       --meta, -m
303
304
305              Print only the response metadata. Shortcut for --print=m.
306
307
308
309
310       --body, -b
311
312
313              Print only the response body. Shortcut for --print=b.
314
315
316
317
318       --verbose, -v
319
320
321              Verbose  output.  For  the  level  one (with single `-v`/`--ver‐
322              bose`), print the whole request as well as  the  response.  Also
323              print  any  intermediary requests/responses (such as redirects).
324              For the second level and higher, print these as well as the  re‐
325              sponse metadata.
326
327              Level  one  is a shortcut for: --all --print=BHbh Level two is a
328              shortcut for: --all --print=BHbhm
329
330
331
332       --all
333
334
335              By default, only the final request/response is shown.  Use  this
336              flag to show any intermediary requests/responses as well. Inter‐
337              mediary requests include followed redirects (with --follow), the
338              first  unauthorized request when Digest auth is used (--auth=di‐
339              gest), etc.
340
341
342
343
344       --stream, -S
345
346
347              Always stream the response body by line, i.e., behave like `tail
348              -f'.
349
350              Without  --stream  and  with  --pretty  (either set or implied),
351              HTTPie fetches the whole response before  it  outputs  the  pro‐
352              cessed data.
353
354              Set  this option when you want to continuously display a pretti‐
355              fied long-lived response, such as one from the Twitter streaming
356              API.
357
358              It  is  useful also without --pretty: It ensures that the output
359              is flushed more often and in smaller chunks.
360
361
362
363
364       --output, -o FILE
365
366
367              Save output to FILE instead of stdout.  If  --download  is  also
368              set,  then  only the response body is saved to FILE. Other parts
369              of the HTTP exchange are printed to stderr.
370
371
372
373
374       --download, -d
375
376
377              Do not print the response body to stdout.  Rather,  download  it
378              and store it in a file. The filename is guessed unless specified
379              with --output [filename]. This action is similar to the  default
380              behaviour of wget.
381
382
383
384
385       --continue, -c
386
387
388              Resume  an  interrupted  download. Note that the --output option
389              needs to be specified as well.
390
391
392
393
394       --quiet, -q
395
396
397              Do not print to stdout or stderr, except for errors and warnings
398              when provided once.  Provide twice to suppress warnings as well.
399              stdout is still  redirected  if  --output  is  specified.   Flag
400              doesn't affect behaviour of download beyond not printing to ter‐
401              minal.
402
403
404
405

Sessions

407       --session SESSION_NAME_OR_PATH
408
409
410              Create, or reuse and update a session. Within a session,  custom
411              headers,  auth  credential,  as  well as any cookies sent by the
412              server persist between requests.
413
414              Session files are stored in:
415
416                  [HTTPIE_CONFIG_DIR]/<HOST>/<SESSION_NAME>.json.
417
418              See the following page to  find  out  your  default  HTTPIE_CON‐
419              FIG_DIR:
420
421                  https://httpie.io/docs/cli/config-file-directory
422
423
424
425       --session-read-only SESSION_NAME_OR_PATH
426
427
428              Create  or  read  a  session  without  updating  it form the re‐
429              quest/response exchange.
430
431
432
433

Authentication

435       --auth, -a USER[:PASS] | TOKEN
436
437
438              For username/password based authentication mechanisms (e.g basic
439              auth  or digest auth) if only the username is provided (-a user‐
440              name), HTTPie will prompt for the password.
441
442
443
444
445       --auth-type, -A
446
447
448              The authentication mechanism to be used. Defaults to "basic".
449
450              "basic": Basic HTTP auth
451
452              "digest": Digest HTTP auth
453
454              "bearer": Bearer HTTP Auth
455
456              For finding out all available authentication types in your  sys‐
457              tem, try:
458
459              $ http --auth-type
460
461
462       --ignore-netrc
463
464
465              Ignore credentials from .netrc.
466
467
468

Network

470       --offline
471
472
473              Build the request and print it but don`t actually send it.
474
475
476
477       --proxy PROTOCOL:PROXY_URL
478
479
480              String   mapping   protocol  to  the  URL  of  the  proxy  (e.g.
481              http:http://foo.bar:3128). You can specify multiple proxies with
482              different   protocols.  The  environment  variables  $ALL_PROXY,
483              $HTTP_PROXY, and $HTTPS_proxy are supported as well.
484
485
486
487
488       --follow, -F
489
490
491              Follow 30x Location redirects.
492
493
494
495       --max-redirects
496
497
498              By default, requests have a limit of 30  redirects  (works  with
499              --follow).
500
501
502
503
504       --max-headers
505
506
507              The  maximum number of response headers to be read before giving
508              up (default 0, i.e., no limit).
509
510
511
512       --timeout SECONDS
513
514
515              The connection timeout of the request in seconds.   The  default
516              value is 0, i.e., there is no timeout limit.  This is not a time
517              limit on the entire response download; rather, an error  is  re‐
518              ported  if the server has not issued a response for timeout sec‐
519              onds (more precisely, if no bytes have been received on the  un‐
520              derlying socket for timeout seconds).
521
522
523
524
525       --check-status
526
527
528              By  default,  HTTPie exits with 0 when no network or other fatal
529              errors occur. This flag instructs HTTPie to also check the  HTTP
530              status code and exit with an error if the status indicates one.
531
532              When the server replies with a 4xx (Client Error) or 5xx (Server
533              Error) status code, HTTPie exits with 4 or  5  respectively.  If
534              the  response  is a 3xx (Redirect) and --follow hasn't been set,
535              then the exit status is 3.  Also an error message is written  to
536              stderr if stdout is redirected.
537
538
539
540
541       --path-as-is
542
543
544              Bypass dot segment (/../ or /./) URL squashing.
545
546
547
548       --chunked
549
550
551              Enable streaming via chunked transfer encoding. The Transfer-En‐
552              coding header is set to chunked.
553
554
555

SSL

557       --verify
558
559
560              Set to "no" (or "false") to skip checking the  host's  SSL  cer‐
561              tificate.   Defaults  to  "yes"  ("true"). You can also pass the
562              path to a CA_BUNDLE file for private certs. (Or you can set  the
563              REQUESTS_CA_BUNDLE environment variable instead.)
564
565
566
567       --ssl
568
569
570              The  desired  protocol  version to use. This will default to SSL
571              v2.3 which will negotiate the highest  protocol  that  both  the
572              server  and your installation of OpenSSL support. Available pro‐
573              tocols may vary depending on OpenSSL installation (only the sup‐
574              ported ones are shown here).
575
576
577
578
579       --ciphers
580
581
582
583              A string in the OpenSSL cipher list format. By default, the fol‐
584              lowing is used:
585
586              ECDHE+AESGCM:ECDHE+CHACHA20:DHE+AESGCM:DHE+CHACHA20:ECDH+AES‐
587              GCM:DH+AESGCM:ECDH+AES:DH+AES:RSA+AESGCM:RSA+AES:!aN‐
588              ULL:!eNULL:!MD5:!DSS
589
590
591
592
593       --cert
594
595
596              You can specify a local cert to use as client side SSL  certifi‐
597              cate.   This  file  may either contain both private key and cer‐
598              tificate or you may specify --cert-key separately.
599
600
601
602
603       --cert-key
604
605
606              The private key to use with SSL. Only needed if --cert is  given
607              and the certificate file does not contain the private key.
608
609
610
611
612       --cert-key-pass
613
614
615              The  passphrase  to  be used to with the given private key. Only
616              needed if --cert-key is  given  and  the  key  file  requires  a
617              passphrase.  If not provided, you`ll be prompted interactively.
618
619
620

Troubleshooting

622       --ignore-stdin, -I
623
624
625              Do not attempt to read stdin
626
627
628
629       --help
630
631
632              Show this help message and exit.
633
634
635
636       --manual
637
638
639              Show the full manual.
640
641
642
643       --version
644
645
646              Show version and exit.
647
648
649
650       --traceback
651
652
653              Prints the exception traceback should one occur.
654
655
656
657       --default-scheme
658
659
660              The default scheme to use if not specified in the URL.
661
662
663
664       --debug
665
666
667              Prints  the  exception  traceback  should  one occur, as well as
668              other information useful for debugging HTTPie itself and for re‐
669              porting bugs.
670
671
672
673

SEE ALSO

675       For  every  --OPTION there is also a --no-OPTION that reverts OPTION to
676       its default value.
677
678       Suggestions    and    bug    reports    are    greatly     appreciated:
679       https://github.com/httpie/httpie/issues
680
681
682
683HTTPie 3.2.1                      2022-05-06                          https(1)
Impressum