Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 1344 lines (848 sloc) 37.079 kB
e25d64a @jkbrzt 0.3.0
authored
1 ****************************************
2 HTTPie: a CLI, cURL-like tool for humans
3 ****************************************
381e60f @jkbrzt Extended README.
authored
4
a2918d8 @insyte Update README.rst
insyte authored
5 HTTPie (pronounced *aych-tee-tee-pie*) is a **command line HTTP client**. Its
6 goal is to make CLI interaction with web services as **human-friendly** as
7 possible. It provides a simple ``http`` command that allows for sending
8 arbitrary HTTP requests using a simple and natural syntax, and displays
868baab @jkbrzt README
authored
9 colorized output. HTTPie can be used for **testing, debugging**, and
a2918d8 @insyte Update README.rst
insyte authored
10 generally **interacting** with HTTP servers.
381e60f @jkbrzt Extended README.
authored
11
f4dde9d @jkbrzt Updated travis config.
authored
12
fa4bd03 @jkbrzt Updated links.
authored
13 .. image:: https://raw.githubusercontent.com/jkbrzt/httpie/master/httpie.png
8cff0a3 @jkbrzt Updated README.
authored
14 :alt: HTTPie compared to cURL
40d95b6 @jkbrzt README
authored
15 :width: 679
16 :height: 781
d97a610 @jkbrzt Added new logo by @claudiatd :sparkles:
authored
17 :align: center
381e60f @jkbrzt Extended README.
authored
18
8e6c765 @jkbrzt Initial --download implementation (#104).
authored
19
381e60f @jkbrzt Extended README.
authored
20 HTTPie is written in Python, and under the hood it uses the excellent
bbc702f @jkbrzt Improved README.
authored
21 `Requests`_ and `Pygments`_ libraries.
381e60f @jkbrzt Extended README.
authored
22
23
868baab @jkbrzt README
authored
24 -----
25
26 |pypi| |unix_build| |windows_build| |coverage|
27
28 -----
29
30
381e60f @jkbrzt Extended README.
authored
31 .. contents::
32 :local:
33 :depth: 1
34 :backlinks: none
35
b966efa @jkbrzt Initial commit.
authored
36
381e60f @jkbrzt Extended README.
authored
37 =============
38 Main Features
39 =============
b966efa @jkbrzt Initial commit.
authored
40
381e60f @jkbrzt Extended README.
authored
41 * Expressive and intuitive syntax
42 * Formatted and colorized terminal output
43 * Built-in JSON support
44 * Forms and file uploads
193683a @jkbrzt Added proxy docs.
authored
45 * HTTPS, proxies, and authentication
381e60f @jkbrzt Extended README.
authored
46 * Arbitrary request data
47 * Custom headers
e25d64a @jkbrzt 0.3.0
authored
48 * Persistent sessions
5a1177d @jkbrzt Fixed downloads with no Content-Length.
authored
49 * Wget-like downloads
ff9f23d @jkbrzt Grouped arguments for a more user-friendly --help.
authored
50 * Python 2.6, 2.7 and 3.x support
381e60f @jkbrzt Extended README.
authored
51 * Linux, Mac OS X and Windows support
0f96348 @jkbrzt Cleanup
authored
52 * Plugins
381e60f @jkbrzt Extended README.
authored
53 * Documentation
54 * Test coverage
b802f2b @jkbrzt Added `field-name:=raw-json`
authored
55
381e60f @jkbrzt Extended README.
authored
56
57 ============
b53d483 @jkbrzt v0.2.6
authored
58 Installation
59 ============
b802f2b @jkbrzt Added `field-name:=raw-json`
authored
60
5c29a4e @jkbrzt Added windows build status icon to README.
authored
61
5e55661 @jkbrzt Added `$ brew install httpie` to README
authored
62 On **Mac OS X**, HTTPie can be installed via `Homebrew <http://brew.sh/>`_:
5e7bb1f @jkbrzt Syntax-highlighting for examples in the README.
authored
63
381e60f @jkbrzt Extended README.
authored
64 .. code-block:: bash
65
5e55661 @jkbrzt Added `$ brew install httpie` to README
authored
66 $ brew install httpie
79329ed @jkbrzt Mention "brew install httpie --HEAD".
authored
67
5e55661 @jkbrzt Added `$ brew install httpie` to README
authored
68
868baab @jkbrzt README
authored
69 Most **Linux** distributions provide a package that can be installed using the
fdabbc6 @jkbrzt Typo
authored
70 system package manager, e.g.:
868baab @jkbrzt README
authored
71
72 .. code-block:: bash
73
74 # Debian-based distributions such as Ubuntu:
75 $ apt-get install httpie
76
77 # RPM-based distributions:
78 $ yum install httpie
5e55661 @jkbrzt Added `$ brew install httpie` to README
authored
79
7d82b85 @jkbrzt Updated installation instructions.
authored
80
79329ed @jkbrzt Mention "brew install httpie --HEAD".
authored
81 A **universal installation method** (that works on **Windows**, Mac OS X, Linux, …,
5e55661 @jkbrzt Added `$ brew install httpie` to README
authored
82 and provides the latest version) is to use `pip`_:
a8ddb83 @jkbrzt Default to https:// if invoked as `https'.
authored
83
bbc702f @jkbrzt Improved README.
authored
84
381e60f @jkbrzt Extended README.
authored
85 .. code-block:: bash
a02a1eb @jkbrzt Fixed README formatting
authored
86
868baab @jkbrzt README
authored
87 # Make sure we have an up-to-date version of pip and setuptools:
88 $ pip install --upgrade pip setuptools
381e60f @jkbrzt Extended README.
authored
89
868baab @jkbrzt README
authored
90 $ pip install --upgrade httpie
8cff0a3 @jkbrzt Updated README.
authored
91
5e7bb1f @jkbrzt Syntax-highlighting for examples in the README.
authored
92
868baab @jkbrzt README
authored
93 (If ``pip`` installation fails for some reason, you can try
94 ``easy_install httpie`` as a fallback.)
09810d5 @jkbrzt Updated installation instructions.
authored
95
96
5c29a4e @jkbrzt Added windows build status icon to README.
authored
97 -------------------
98 Development version
99 -------------------
8cff0a3 @jkbrzt Updated README.
authored
100
5c29a4e @jkbrzt Added windows build status icon to README.
authored
101 The **latest development version** can be installed directly from GitHub:
b802f2b @jkbrzt Added `field-name:=raw-json`
authored
102
381e60f @jkbrzt Extended README.
authored
103 .. code-block:: bash
b966efa @jkbrzt Initial commit.
authored
104
79329ed @jkbrzt Mention "brew install httpie --HEAD".
authored
105 # Mac OS X via Homebrew
106 $ brew install httpie --HEAD
107
108 # Universal
fa4bd03 @jkbrzt Updated links.
authored
109 $ pip install --upgrade https://github.com/jkbrzt/httpie/tarball/master
c71de95 @simono Update README.rst and add links to Ubuntu and Debian Packages.
simono authored
110
111
5c29a4e @jkbrzt Added windows build status icon to README.
authored
112
193683a @jkbrzt Added proxy docs.
authored
113 =====
114 Usage
115 =====
381e60f @jkbrzt Extended README.
authored
116
117
118 Hello World:
119
120
121 .. code-block:: bash
122
123 $ http httpie.org
124
125
126 Synopsis:
127
128 .. code-block:: bash
129
130 $ http [flags] [METHOD] URL [ITEM [ITEM]]
131
132
133 See also ``http --help``.
134
135
136 --------
137 Examples
138 --------
139
27f0892 @jkbrzt Improved examples.
authored
140 Custom `HTTP method`_, `HTTP headers`_ and `JSON`_ data:
381e60f @jkbrzt Extended README.
authored
141
142 .. code-block:: bash
143
27f0892 @jkbrzt Improved examples.
authored
144 $ http PUT example.org X-API-Token:123 name=John
381e60f @jkbrzt Extended README.
authored
145
146
27f0892 @jkbrzt Improved examples.
authored
147 Submitting `forms`_:
381e60f @jkbrzt Extended README.
authored
148
149 .. code-block:: bash
150
27f0892 @jkbrzt Improved examples.
authored
151 $ http -f POST example.org hello=World
381e60f @jkbrzt Extended README.
authored
152
153
bbc702f @jkbrzt Improved README.
authored
154 See the request that is being sent using one of the `output options`_:
381e60f @jkbrzt Extended README.
authored
155
156 .. code-block:: bash
157
27f0892 @jkbrzt Improved examples.
authored
158 $ http -v example.org
381e60f @jkbrzt Extended README.
authored
159
160
7ccdece @jkbrzt Cleanup
authored
161 Use `Github API`_ to post a comment on an
fa4bd03 @jkbrzt Updated links.
authored
162 `issue <https://github.com/jkbrzt/httpie/issues/83>`_
7ccdece @jkbrzt Cleanup
authored
163 with `authentication`_:
381e60f @jkbrzt Extended README.
authored
164
165 .. code-block:: bash
166
fa4bd03 @jkbrzt Updated links.
authored
167 $ http -a USERNAME POST https://api.github.com/repos/jkbrzt/httpie/issues/83/comments body='HTTPie is awesome!'
381e60f @jkbrzt Extended README.
authored
168
169
27f0892 @jkbrzt Improved examples.
authored
170 Upload a file using `redirected input`_:
381e60f @jkbrzt Extended README.
authored
171
172 .. code-block:: bash
173
174 $ http example.org < file.json
175
176
27f0892 @jkbrzt Improved examples.
authored
177 Download a file and save it via `redirected output`_:
381e60f @jkbrzt Extended README.
authored
178
179 .. code-block:: bash
180
181 $ http example.org/file > file
182
8e6c765 @jkbrzt Initial --download implementation (#104).
authored
183
184 Download a file ``wget`` style:
185
186 .. code-block:: bash
187
188 $ http --download example.org/file
189
bbc702f @jkbrzt Improved README.
authored
190 Use named `sessions`_ to make certain aspects or the communication persistent
191 between requests to the same host:
192
193 .. code-block:: bash
194
195 $ http --session=logged-in -a username:password httpbin.org/get API-Key:123
196
197 $ http --session=logged-in httpbin.org/headers
198
63b61bc @jkbrzt Add custom Host example.
authored
199
200 Set a custom ``Host`` header to work around missing DNS records:
201
202 .. code-block:: bash
203
204 $ http localhost:8000 Host:example.com
205
bbc702f @jkbrzt Improved README.
authored
206 ..
27f0892 @jkbrzt Improved examples.
authored
207
208 --------
209
210 *What follows is a detailed documentation. It covers the command syntax,
bbc702f @jkbrzt Improved README.
authored
211 advanced usage, and also features additional examples.*
27f0892 @jkbrzt Improved examples.
authored
212
213
5c29a4e @jkbrzt Added windows build status icon to README.
authored
214 ===========
381e60f @jkbrzt Extended README.
authored
215 HTTP Method
5c29a4e @jkbrzt Added windows build status icon to README.
authored
216 ===========
381e60f @jkbrzt Extended README.
authored
217
218 The name of the HTTP method comes right before the URL argument:
219
220 .. code-block:: bash
221
222 $ http DELETE example.org/todos/7
223
224
27f0892 @jkbrzt Improved examples.
authored
225 Which looks similar to the actual ``Request-Line`` that is sent:
381e60f @jkbrzt Extended README.
authored
226
227 .. code-block:: http
228
229 DELETE /todos/7 HTTP/1.1
8cff0a3 @jkbrzt Updated README.
authored
230
231
381e60f @jkbrzt Extended README.
authored
232 When the ``METHOD`` argument is **omitted** from the command, HTTPie defaults to
193683a @jkbrzt Added proxy docs.
authored
233 either ``GET`` (with no request data) or ``POST`` (with request data).
381e60f @jkbrzt Extended README.
authored
234
235
236 ===========
237 Request URL
238 ===========
239
240 The only information HTTPie needs to perform a request is a URL.
241 The default scheme is, somewhat unsurprisingly, ``http://``,
242 and can be omitted from the argument – ``http example.org`` works just fine.
243
8a52bef @nlf make shorthand parsing more robust, add unit tests and documentation
nlf authored
244 Additionally, curl-like shorthand for localhost is supported.
245 This means that, for example ``:3000`` would expand to ``http://localhost:3000``
246 If the port is omitted, then port 80 is assumed.
247
248 .. code-block:: bash
249
250 $ http :/foo
70eb97d @nlf tweak readme to show http requests
nlf authored
251
9034546 @nlf tweak readme more
nlf authored
252
70eb97d @nlf tweak readme to show http requests
nlf authored
253 .. code-block:: http
254
9034546 @nlf tweak readme more
nlf authored
255 GET /foo HTTP/1.1
2c12fd9 @nlf tweak readme more
nlf authored
256 Host: localhost
70eb97d @nlf tweak readme to show http requests
nlf authored
257
9034546 @nlf tweak readme more
nlf authored
258
70eb97d @nlf tweak readme to show http requests
nlf authored
259 .. code-block:: bash
260
8a52bef @nlf make shorthand parsing more robust, add unit tests and documentation
nlf authored
261 $ http :3000/bar
262
9034546 @nlf tweak readme more
nlf authored
263
70eb97d @nlf tweak readme to show http requests
nlf authored
264 .. code-block:: http
265
9034546 @nlf tweak readme more
nlf authored
266 GET /bar HTTP/1.1
2c12fd9 @nlf tweak readme more
nlf authored
267 Host: localhost:3000
70eb97d @nlf tweak readme to show http requests
nlf authored
268
52dd6ad @jkbrzt Updated README.
authored
269
270 .. code-block:: bash
271
272 $ http :
273
274
275 .. code-block:: http
276
277 GET / HTTP/1.1
278 Host: localhost
279
ece85c0 @ifdattic Fix typos, improve readability
ifdattic authored
280 If you find yourself manually constructing URLs with **querystring parameters**
381e60f @jkbrzt Extended README.
authored
281 on the terminal, you may appreciate the ``param==value`` syntax for appending
282 URL parameters so that you don't have to worry about escaping the ``&``
283 separators. To search for ``HTTPie`` on Google Images you could use this
284 command:
285
286 .. code-block:: bash
287
288 $ http GET www.google.com search==HTTPie tbm==isch
289
290
291 .. code-block:: http
292
293 GET /?search=HTTPie&tbm=isch HTTP/1.1
294
295
296 =============
297 Request Items
298 =============
299
d5bc564 @jkbrzt Allow embeding text (=@) and JSON (:=@) files content into request da…
authored
300 There are a few different *request item* types that provide a
381e60f @jkbrzt Extended README.
authored
301 convenient mechanism for specifying HTTP headers, simple JSON and
302 form data, files, and URL parameters.
303
304 They are key/value pairs specified after the URL. All have in
305 common that they become part of the actual request that is sent and that
306 their type is distinguished only by the separator used:
d5bc564 @jkbrzt Allow embeding text (=@) and JSON (:=@) files content into request da…
authored
307 ``:``, ``=``, ``:=``, ``==``, ``@``, ``=@``, and ``:=@``. The ones with an
308 ``@`` expect a file path as value.
381e60f @jkbrzt Extended README.
authored
309
310 +-----------------------+-----------------------------------------------------+
311 | Item Type | Description |
312 +=======================+=====================================================+
313 | HTTP Headers | Arbitrary HTTP header, e.g. ``X-API-Token:123``. |
314 | ``Name:Value`` | |
b53d483 @jkbrzt v0.2.6
authored
315 +-----------------------+-----------------------------------------------------+
381e60f @jkbrzt Extended README.
authored
316 | URL parameters | Appends the given name/value pair as a query |
317 | ``name==value`` | string parameter to the URL. |
ece85c0 @ifdattic Fix typos, improve readability
ifdattic authored
318 | | The ``==`` separator is used. |
b53d483 @jkbrzt v0.2.6
authored
319 +-----------------------+-----------------------------------------------------+
381e60f @jkbrzt Extended README.
authored
320 | Data Fields | Request data fields to be serialized as a JSON |
e0cc63c @jkbrzt Cleanup
authored
321 | ``field=value``, | object (default), or to be form-encoded |
d5bc564 @jkbrzt Allow embeding text (=@) and JSON (:=@) files content into request da…
authored
322 | ``field=@file.txt`` | (``--form, -f``). |
b53d483 @jkbrzt v0.2.6
authored
323 +-----------------------+-----------------------------------------------------+
381e60f @jkbrzt Extended README.
authored
324 | Raw JSON fields | Useful when sending JSON and one or |
d5bc564 @jkbrzt Allow embeding text (=@) and JSON (:=@) files content into request da…
authored
325 | ``field:=json``, | more fields need to be a ``Boolean``, ``Number``, |
326 | ``field:=@file.json`` | nested ``Object``, or an ``Array``, e.g., |
381e60f @jkbrzt Extended README.
authored
327 | | ``meals:='["ham","spam"]'`` or ``pies:=[1,2,3]`` |
328 | | (note the quotes). |
b53d483 @jkbrzt v0.2.6
authored
329 +-----------------------+-----------------------------------------------------+
d5bc564 @jkbrzt Allow embeding text (=@) and JSON (:=@) files content into request da…
authored
330 | Form File Fields | Only available with ``--form, -f``. |
381e60f @jkbrzt Extended README.
authored
331 | ``field@/dir/file`` | For example ``screenshot@~/Pictures/img.png``. |
b53d483 @jkbrzt v0.2.6
authored
332 | | The presence of a file field results |
381e60f @jkbrzt Extended README.
authored
333 | | in a ``multipart/form-data`` request. |
b53d483 @jkbrzt v0.2.6
authored
334 +-----------------------+-----------------------------------------------------+
335
381e60f @jkbrzt Extended README.
authored
336 You can use ``\`` to escape characters that shouldn't be used as separators
bbc702f @jkbrzt Improved README.
authored
337 (or parts thereof). For instance, ``foo\==bar`` will become a data key/value
381e60f @jkbrzt Extended README.
authored
338 pair (``foo=`` and ``bar``) instead of a URL parameter.
b53d483 @jkbrzt v0.2.6
authored
339
d5bc564 @jkbrzt Allow embeding text (=@) and JSON (:=@) files content into request da…
authored
340 You can also quote values, e.g. ``foo="bar baz"``.
341
bbc702f @jkbrzt Improved README.
authored
342 Note that data fields aren't the only way to specify request data:
343 `Redirected input`_ allows for passing arbitrary data to be sent with the
344 request.
76a3125 Updated documentation for query string params.
Jake Basile authored
345
1f49900 @jkbrzt Improved README.
authored
346
381e60f @jkbrzt Extended README.
authored
347 ====
348 JSON
349 ====
350
351 JSON is the *lingua franca* of modern web services and it is also the
4a6f32a @jkbrzt Documented config.
authored
352 **implicit content type** HTTPie by default uses:
5e7bb1f @jkbrzt Syntax-highlighting for examples in the README.
authored
353
381e60f @jkbrzt Extended README.
authored
354 If your command includes some data items, they are serialized as a JSON
355 object by default. HTTPie also automatically sets the following headers,
356 both of which can be overwritten:
8cff0a3 @jkbrzt Updated README.
authored
357
381e60f @jkbrzt Extended README.
authored
358 ================ =======================================
6e7e2f2 @jkbrzt Changed the default JSON `Content-Type` to `application/json`.
authored
359 ``Content-Type`` ``application/json``
381e60f @jkbrzt Extended README.
authored
360 ``Accept`` ``application/json``
361 ================ =======================================
8cff0a3 @jkbrzt Updated README.
authored
362
7ccdece @jkbrzt Cleanup
authored
363 You can use ``--json, -j`` to explicitly set ``Accept``
4a6f32a @jkbrzt Documented config.
authored
364 to ``application/json`` regardless of whether you are sending data
365 (it's a shortcut for setting the header via the usual header notation –
381e60f @jkbrzt Extended README.
authored
366 ``http url Accept:application/json``).
5e7bb1f @jkbrzt Syntax-highlighting for examples in the README.
authored
367
381e60f @jkbrzt Extended README.
authored
368 Simple example:
e7dc59e @jkbrzt Updated README.
authored
369
381e60f @jkbrzt Extended README.
authored
370 .. code-block:: bash
371
372 $ http PUT example.org name=John email=john@example.org
373
374 .. code-block:: http
375
376 PUT / HTTP/1.1
377 Accept: application/json
596fdc8 @jkbrzt Update README examples with the new default `Accept-Encoding` value u…
authored
378 Accept-Encoding: gzip, deflate
6e7e2f2 @jkbrzt Changed the default JSON `Content-Type` to `application/json`.
authored
379 Content-Type: application/json
381e60f @jkbrzt Extended README.
authored
380 Host: example.org
381
382 {
383 "name": "John",
384 "email": "john@example.org"
385 }
386
387
388 Non-string fields use the ``:=`` separator, which allows you to embed raw JSON
d5bc564 @jkbrzt Allow embeding text (=@) and JSON (:=@) files content into request da…
authored
389 into the resulting object. Text and raw JSON files can also be embedded into
390 fields using ``=@`` and ``:=@``:
381e60f @jkbrzt Extended README.
authored
391
392 .. code-block:: bash
393
d5bc564 @jkbrzt Allow embeding text (=@) and JSON (:=@) files content into request da…
authored
394 $ http PUT api.example.com/person/1 \
395 name=John \
396 age:=29 married:=false hobbies:='["http", "pies"]' \ # Raw JSON
397 description=@about-john.txt \ # Embed text file
398 bookmarks:=@bookmarks.json # Embed JSON file
e7dc59e @jkbrzt Updated README.
authored
399
258fc0c @jkbrzt Renamed the CLI tool `http`.
authored
400
381e60f @jkbrzt Extended README.
authored
401 .. code-block:: http
b802f2b @jkbrzt Added `field-name:=raw-json`
authored
402
381e60f @jkbrzt Extended README.
authored
403 PUT /person/1 HTTP/1.1
404 Accept: application/json
6e7e2f2 @jkbrzt Changed the default JSON `Content-Type` to `application/json`.
authored
405 Content-Type: application/json
381e60f @jkbrzt Extended README.
authored
406 Host: api.example.com
407
408 {
409 "age": 29,
410 "hobbies": [
411 "http",
412 "pies"
413 ],
d5bc564 @jkbrzt Allow embeding text (=@) and JSON (:=@) files content into request da…
authored
414 "description": "John is a nice guy who likes pies.",
381e60f @jkbrzt Extended README.
authored
415 "married": false,
d5bc564 @jkbrzt Allow embeding text (=@) and JSON (:=@) files content into request da…
authored
416 "name": "John",
417 "bookmarks": {
418 "HTTPie": "http://httpie.org",
419 }
381e60f @jkbrzt Extended README.
authored
420 }
421
422
27f0892 @jkbrzt Improved examples.
authored
423 Send JSON data stored in a file (see `redirected input`_ for more examples):
424
425 .. code-block:: bash
426
427 $ http POST api.example.com/person/1 < person.json
428
381e60f @jkbrzt Extended README.
authored
429
430 =====
431 Forms
432 =====
433
434 Submitting forms is very similar to sending `JSON`_ requests. Often the only
7ccdece @jkbrzt Cleanup
authored
435 difference is in adding the ``--form, -f`` option, which ensures that
27f0892 @jkbrzt Improved examples.
authored
436 data fields are serialized as, and ``Content-Type`` is set to,
381e60f @jkbrzt Extended README.
authored
437 ``application/x-www-form-urlencoded; charset=utf-8``.
438
bbc702f @jkbrzt Improved README.
authored
439 It is possible to make form data the implicit content type instead of JSON
440 via the `config`_ file.
4a6f32a @jkbrzt Documented config.
authored
441
27f0892 @jkbrzt Improved examples.
authored
442
381e60f @jkbrzt Extended README.
authored
443 -------------
444 Regular Forms
445 -------------
446
447 .. code-block:: bash
448
ece85c0 @ifdattic Fix typos, improve readability
ifdattic authored
449 $ http --form POST api.example.org/person/1 name='John Smith' \
450 email=john@example.org cv=@~/Documents/cv.txt
381e60f @jkbrzt Extended README.
authored
451
452
453 .. code-block:: http
454
455 POST /person/1 HTTP/1.1
8cff0a3 @jkbrzt Updated README.
authored
456 Content-Type: application/x-www-form-urlencoded; charset=utf-8
b802f2b @jkbrzt Added `field-name:=raw-json`
authored
457
d5bc564 @jkbrzt Allow embeding text (=@) and JSON (:=@) files content into request da…
authored
458 name=John+Smith&email=john%40example.org&cv=John's+CV+...
381e60f @jkbrzt Extended README.
authored
459
460
461 -----------------
462 File Upload Forms
463 -----------------
464
27f0892 @jkbrzt Improved examples.
authored
465 If one or more file fields is present, the serialization and content type is
381e60f @jkbrzt Extended README.
authored
466 ``multipart/form-data``:
b802f2b @jkbrzt Added `field-name:=raw-json`
authored
467
381e60f @jkbrzt Extended README.
authored
468 .. code-block:: bash
5e7bb1f @jkbrzt Syntax-highlighting for examples in the README.
authored
469
381e60f @jkbrzt Extended README.
authored
470 $ http -f POST example.com/jobs name='John Smith' cv@~/Documents/cv.pdf
b7e0473 @jkbrzt Added file upload support
authored
471
472
381e60f @jkbrzt Extended README.
authored
473 The request above is the same as if the following HTML form were
5e7bb1f @jkbrzt Syntax-highlighting for examples in the README.
authored
474 submitted:
475
476 .. code-block:: html
b7e0473 @jkbrzt Added file upload support
authored
477
1f49900 @jkbrzt Improved README.
authored
478 <form enctype="multipart/form-data" method="post" action="http://example.com/jobs">
479 <input type="text" name="name" />
b7e0473 @jkbrzt Added file upload support
authored
480 <input type="file" name="cv" />
481 </form>
482
d5bc564 @jkbrzt Allow embeding text (=@) and JSON (:=@) files content into request da…
authored
483 Note that ``@`` is used to simulate a file upload form field, whereas
484 ``=@`` just embeds the file content as a regular text field value.
485
5e7bb1f @jkbrzt Syntax-highlighting for examples in the README.
authored
486
381e60f @jkbrzt Extended README.
authored
487 ============
488 HTTP Headers
489 ============
490
491 To set custom headers you can use the ``Header:Value`` notation:
492
493 .. code-block:: bash
494
ece85c0 @ifdattic Fix typos, improve readability
ifdattic authored
495 $ http example.org User-Agent:Bacon/1.0 'Cookie:valued-visitor=yes;foo=bar' \
496 X-Foo:Bar Referer:http://httpie.org/
381e60f @jkbrzt Extended README.
authored
497
498
499 .. code-block:: http
500
501 GET / HTTP/1.1
502 Accept: */*
596fdc8 @jkbrzt Update README examples with the new default `Accept-Encoding` value u…
authored
503 Accept-Encoding: gzip, deflate
6924706 @lorin Augment cookie example in README for multiple cookies
lorin authored
504 Cookie: valued-visitor=yes;foo=bar
381e60f @jkbrzt Extended README.
authored
505 Host: example.org
506 Referer: http://httpie.org/
507 User-Agent: Bacon/1.0
508 X-Foo: Bar
509
510
27f0892 @jkbrzt Improved examples.
authored
511 There are a couple of default headers that HTTPie sets:
381e60f @jkbrzt Extended README.
authored
512
513 .. code-block:: http
514
515 GET / HTTP/1.1
516 Accept: */*
596fdc8 @jkbrzt Update README examples with the new default `Accept-Encoding` value u…
authored
517 Accept-Encoding: gzip, deflate
381e60f @jkbrzt Extended README.
authored
518 User-Agent: HTTPie/<version>
519 Host: <taken-from-URL>
520
521
27f0892 @jkbrzt Improved examples.
authored
522 Any of the default headers can be overwritten.
523
524
193683a @jkbrzt Added proxy docs.
authored
525 ==============
526 Authentication
527 ==============
381e60f @jkbrzt Extended README.
authored
528
5a6b65e @jkbrzt Added link to httpie-oauth.
authored
529 The currently supported authentication schemes are Basic and Digest
530 (see `auth plugins`_ for more). There are two flags that control authentication:
381e60f @jkbrzt Extended README.
authored
531
532 =================== ======================================================
533 ``--auth, -a`` Pass a ``username:password`` pair as
534 the argument. Or, if you only specify a username
535 (``-a username``), you'll be prompted for
536 the password before the request is sent.
ece85c0 @ifdattic Fix typos, improve readability
ifdattic authored
537 To send an empty password, pass ``username:``.
d87b2aa @jkbrzt Added support for credentials in URL.
authored
538 The ``username:password@hostname`` URL syntax is
539 supported as well (but credentials passed via ``-a``
540 have higher priority).
381e60f @jkbrzt Extended README.
authored
541
542 ``--auth-type`` Specify the auth mechanism. Possible values are
543 ``basic`` and ``digest``. The default value is
544 ``basic`` so it can often be omitted.
545 =================== ======================================================
76a3125 Updated documentation for query string params.
Jake Basile authored
546
dac79a8 Added example for .netrc usage (see issue #139 in upstream.
Graeme West authored
547
76a3125 Updated documentation for query string params.
Jake Basile authored
548
381e60f @jkbrzt Extended README.
authored
549 Basic auth:
5e7bb1f @jkbrzt Syntax-highlighting for examples in the README.
authored
550
b966efa @jkbrzt Initial commit.
authored
551
381e60f @jkbrzt Extended README.
authored
552 .. code-block:: bash
e7dc59e @jkbrzt Updated README.
authored
553
381e60f @jkbrzt Extended README.
authored
554 $ http -a username:password example.org
5e7bb1f @jkbrzt Syntax-highlighting for examples in the README.
authored
555
41d6409 @jkbrzt Added more examples.
authored
556
381e60f @jkbrzt Extended README.
authored
557 Digest auth:
41d6409 @jkbrzt Added more examples.
authored
558
5e7bb1f @jkbrzt Syntax-highlighting for examples in the README.
authored
559
381e60f @jkbrzt Extended README.
authored
560 .. code-block:: bash
41d6409 @jkbrzt Added more examples.
authored
561
381e60f @jkbrzt Extended README.
authored
562 $ http --auth-type=digest -a username:password example.org
41d6409 @jkbrzt Added more examples.
authored
563
5e7bb1f @jkbrzt Syntax-highlighting for examples in the README.
authored
564
381e60f @jkbrzt Extended README.
authored
565 With password prompt:
098e1d3 @jkbrzt Fixed multipart requests output; binary support.
authored
566
381e60f @jkbrzt Extended README.
authored
567 .. code-block:: bash
2646eba @jkbrzt Replaced --ignore-http-status with --check-status.
authored
568
381e60f @jkbrzt Extended README.
authored
569 $ http -a username example.org
5e7bb1f @jkbrzt Syntax-highlighting for examples in the README.
authored
570
50196be @jkbrzt Added support for request payload from a filepath
authored
571
354aaa9 @jkbrzt Improved .netrc example formatting.
authored
572 Authorization information from your ``~/.netrc`` file is honored as well:
dac79a8 Added example for .netrc usage (see issue #139 in upstream.
Graeme West authored
573
574 .. code-block:: bash
575
354aaa9 @jkbrzt Improved .netrc example formatting.
authored
576 $ cat ~/.netrc
dac79a8 Added example for .netrc usage (see issue #139 in upstream.
Graeme West authored
577 machine httpbin.org
578 login httpie
579 password test
2ad4059 @jkbrzt Improved .netrc example formatting.
authored
580
dac79a8 Added example for .netrc usage (see issue #139 in upstream.
Graeme West authored
581 $ http httpbin.org/basic-auth/httpie/test
582 HTTP/1.1 200 OK
583 [...]
584
585
5a6b65e @jkbrzt Added link to httpie-oauth.
authored
586 ------------
587 Auth Plugins
588 ------------
2acb303 @jkbrzt Added support for auth plugins.
authored
589
fa4bd03 @jkbrzt Updated links.
authored
590 * `httpie-oauth <https://github.com/jkbrzt/httpie-oauth>`_: OAuth
591 * `httpie-ntlm <https://github.com/jkbrzt/httpie-ntlm>`_: NTLM (NT LAN Manager)
0e267d8 @jkbrzt Added a link to the httpie-negotiate auth plugin by @ndzou II.
authored
592 * `httpie-negotiate <https://github.com/ndzou/httpie-negotiate>`_: SPNEGO (GSS Negotiate)
e3c83fc @ametaireau Add the hawk plugin
ametaireau authored
593 * `requests-hawk <https://github.com/mozilla-services/requests-hawk>`_: Hawk
0d21ff0 @jkbrzt Added a link to @pd's httpie-api-auth plugin
authored
594 * `httpie-api-auth <https://github.com/pd/httpie-api-auth>`_: ApiAuth
f8c1104 @jkbrzt Fixed link to httpie-edgegrid
authored
595 * `httpie-edgegrid <https://github.com/akamai-open/httpie-edgegrid>`_: EdgeGrid
2acb303 @jkbrzt Added support for auth plugins.
authored
596
597
193683a @jkbrzt Added proxy docs.
authored
598 =======
599 Proxies
600 =======
601
7ccdece @jkbrzt Cleanup
authored
602 You can specify proxies to be used through the ``--proxy`` argument for each
603 protocol (which is included in the value in case of redirects across protocols):
193683a @jkbrzt Added proxy docs.
authored
604
605 .. code-block:: bash
606
81c9988 @jkbrzt Update --proxy examples to include URLs to work with Requests v2.0.0..
authored
607 $ http --proxy=http:http://10.10.1.10:3128 --proxy=https:https://10.10.1.10:1080 example.org
193683a @jkbrzt Added proxy docs.
authored
608
609
610 With Basic authentication:
611
612 .. code-block:: bash
613
bbc702f @jkbrzt Improved README.
authored
614 $ http --proxy=http:http://user:pass@10.10.1.10:3128 example.org
193683a @jkbrzt Added proxy docs.
authored
615
616 You can also configure proxies by environment variables ``HTTP_PROXY`` and
617 ``HTTPS_PROXY``, and the underlying Requests library will pick them up as well.
07de32c @jkbrzt Version fix.
authored
618 If you want to disable proxies configured through the environment variables for
193683a @jkbrzt Added proxy docs.
authored
619 certain hosts, you can specify them in ``NO_PROXY``.
620
621 In your ``~/.bash_profile``:
622
623 .. code-block:: bash
624
81c9988 @jkbrzt Update --proxy examples to include URLs to work with Requests v2.0.0..
authored
625 export HTTP_PROXY=http://10.10.1.10:3128
626 export HTTPS_PROXY=https://10.10.1.10:1080
193683a @jkbrzt Added proxy docs.
authored
627 export NO_PROXY=localhost,example.com
628
629
fa334bd @jkbrzt Documented --verify.
authored
630 =====
631 HTTPS
632 =====
633
59b6020 @jkbrzt Extended SSL documentation.
authored
634 -----------------------------------
635 Server SSL certificate verification
636 -----------------------------------
fa334bd @jkbrzt Documented --verify.
authored
637
59b6020 @jkbrzt Extended SSL documentation.
authored
638 To skip the **host's SSL certificate verification,** you can pass
639 ``--verify=no`` (default is ``yes``):
dd7197c document --cert and --certkey
Matthias Lehmann authored
640
59b6020 @jkbrzt Extended SSL documentation.
authored
641 .. code-block:: bash
642
643 $ http --verify=no https://example.org
644
645
ed64854 @jkbrzt README
authored
646 You can also use ``--verify=<CA_BUNDLE_PATH>`` to set a **custom CA bundle**
647 path:
59b6020 @jkbrzt Extended SSL documentation.
authored
648
649 .. code-block:: bash
650
651 $ http --verify=/ssl/custom_ca_bundle https://example.org
652
653
654 The path can also be configured via the environment variable
655 ``REQUESTS_CA_BUNDLE`` (picked up by the underlying python-requests library):
656
657 .. code-block:: bash
658
659 $ REQUESTS_CA_BUNDLE=/ssl/custom_ca_bundle http https://example.org
660
661
662 ---------------------------
663 Client side SSL certificate
664 ---------------------------
665 To use a **client side certificate** for the SSL communication, you can pass
666 the path of the cert file with ``--cert``:
667
668 .. code-block:: bash
669
670 $ http --cert=client.pem https://example.org
671
672
ed64854 @jkbrzt README
authored
673 If the **private key** is not contained in the cert file you may pass the
59b6020 @jkbrzt Extended SSL documentation.
authored
674 path of the key file with ``--cert-key``:
675
676 .. code-block:: bash
677
678 $ http --cert=client.crt --cert-key=client.key https://example.org
679
680
681 ----------------------------
682 SNI (Server Name Indication)
683 ----------------------------
684
ed64854 @jkbrzt README
authored
685 If you use HTTPie with Python < 2.7.9
686 (can be verified with ``python --version``) and need to talk to servers that
687 use **SNI (Server Name Indication)** you need to install some additional
59b6020 @jkbrzt Extended SSL documentation.
authored
688 dependencies:
f283de6 @felixbuenemann Add info about SNI on Python 2.x to README
felixbuenemann authored
689
690 .. code-block:: bash
691
692 $ pip install --upgrade pyopenssl pyasn1 ndg-httpsclient
693
694
695 You can use the following command to test SNI support:
696
697 .. code-block:: bash
698
699 $ http https://sni.velox.ch
700
fa334bd @jkbrzt Documented --verify.
authored
701
381e60f @jkbrzt Extended README.
authored
702 ==============
703 Output Options
704 ==============
50196be @jkbrzt Added support for request payload from a filepath
authored
705
381e60f @jkbrzt Extended README.
authored
706 By default, HTTPie outputs the whole response message (headers as well as the
707 body).
708
709 You can control what should be printed via several options:
710
711 ================= =====================================================
712 ``--headers, -h`` Only the response headers are printed.
713 ``--body, -b`` Only the response body is printed.
714 ``--verbose, -v`` Print the whole HTTP exchange (request and response).
715 ``--print, -p`` Selects parts of the HTTP exchange.
716 ================= =====================================================
717
718 ``--verbose`` can often be useful for debugging the request and generating
719 documentation examples:
720
721 .. code-block:: bash
722
723 $ http --verbose PUT httpbin.org/put hello=world
724 PUT /put HTTP/1.1
725 Accept: application/json
596fdc8 @jkbrzt Update README examples with the new default `Accept-Encoding` value u…
authored
726 Accept-Encoding: gzip, deflate
6e7e2f2 @jkbrzt Changed the default JSON `Content-Type` to `application/json`.
authored
727 Content-Type: application/json
381e60f @jkbrzt Extended README.
authored
728 Host: httpbin.org
729 User-Agent: HTTPie/0.2.7dev
730
731 {
732 "hello": "world"
733 }
734
735
736 HTTP/1.1 200 OK
737 Connection: keep-alive
738 Content-Length: 477
739 Content-Type: application/json
740 Date: Sun, 05 Aug 2012 00:25:23 GMT
741 Server: gunicorn/0.13.4
742
743 {
744 […]
745 }
746
747
7ccdece @jkbrzt Cleanup
authored
748 All the other options are just a shortcut for ``--print, -p``.
381e60f @jkbrzt Extended README.
authored
749 It accepts a string of characters each of which represents a specific part of
750 the HTTP exchange:
751
752 ========== ==================
753 Character Stands for
754 ========== ==================
755 ``H`` Request headers.
756 ``B`` Request body.
757 ``h`` Response headers.
758 ``b`` Response body.
759 ========== ==================
760
27f0892 @jkbrzt Improved examples.
authored
761 Print request and response headers:
381e60f @jkbrzt Extended README.
authored
762
763 .. code-block:: bash
764
765 $ http --print=Hh PUT httpbin.org/put hello=world
766
767
768 -------------------------
769 Conditional Body Download
770 -------------------------
771
772 As an optimization, the response body is downloaded from the server
773 only if it's part of the output. This is similar to performing a ``HEAD``
774 request, except that it applies to any HTTP method you use.
775
776 Let's say that there is an API that returns the whole resource when it is
777 updated, but you are only interested in the response headers to see the
27f0892 @jkbrzt Improved examples.
authored
778 status code after an update:
381e60f @jkbrzt Extended README.
authored
779
780 .. code-block:: bash
781
782 $ http --headers PATCH example.org/Really-Huge-Resource name='New Name'
783
784
27f0892 @jkbrzt Improved examples.
authored
785 Since we are only printing the HTTP headers here, the connection to the server
381e60f @jkbrzt Extended README.
authored
786 is closed as soon as all the response headers have been received.
787 Therefore, bandwidth and time isn't wasted downloading the body
788 which you don't care about.
789
790 The response headers are downloaded always, even if they are not part of
791 the output
792
793
794 ================
795 Redirected Input
796 ================
797
798 **A universal method for passing request data is through redirected** ``stdin``
799 (standard input). Such data is buffered and then with no further processing
800 used as the request body. There are multiple useful ways to use piping:
801
802 Redirect from a file:
803
804 .. code-block:: bash
805
806 $ http PUT example.com/person/1 X-API-Token:123 < person.json
807
808
809 Or the output of another program:
810
811 .. code-block:: bash
812
541c75e Fixed the order of args to grep in README.
Rocky Meza authored
813 $ grep '401 Unauthorized' /var/log/httpd/error_log | http POST example.org/intruders
381e60f @jkbrzt Extended README.
authored
814
815
816 You can use ``echo`` for simple data:
817
818 .. code-block:: bash
819
820 $ echo '{"name": "John"}' | http PATCH example.com/person/1 X-API-Token:123
821
822
823 You can even pipe web services together using HTTPie:
824
825 .. code-block:: bash
826
fa4bd03 @jkbrzt Updated links.
authored
827 $ http GET https://api.github.com/repos/jkbrzt/httpie | http POST httpbin.org/post
381e60f @jkbrzt Extended README.
authored
828
829
830 You can use ``cat`` to enter multiline data on the terminal:
831
832 .. code-block:: bash
833
86256af @jkbrzt Removed non-ASCII characters from README (closes #85).
authored
834 $ cat | http POST example.com
381e60f @jkbrzt Extended README.
authored
835 <paste>
836 ^D
837
838
839 .. code-block:: bash
840
86256af @jkbrzt Removed non-ASCII characters from README (closes #85).
authored
841 $ cat | http POST example.com/todos Content-Type:text/plain
381e60f @jkbrzt Extended README.
authored
842 - buy milk
843 - call parents
844 ^D
845
846
847 On OS X, you can send the contents of the clipboard with ``pbpaste``:
848
849 .. code-block:: bash
850
851 $ pbpaste | http PUT example.com
852
853
854 Passing data through ``stdin`` cannot be combined with data fields specified
f87884d @jkbrzt README
authored
855 on the command line:
856
857
858 .. code-block:: bash
859
860 $ echo 'data' | http POST example.org more=data # This is invalid
381e60f @jkbrzt Extended README.
authored
861
862
f7b703b @jkbrzt Added --ignore-stdin
authored
863 To prevent HTTPie from reading ``stdin`` data you can use the
864 ``--ignore-stdin`` option.
865
866
381e60f @jkbrzt Extended README.
authored
867 -------------------------
868 Body Data From a Filename
869 -------------------------
870
871 **An alternative to redirected** ``stdin`` is specifying a filename (as
872 ``@/path/to/file``) whose content is used as if it came from ``stdin``.
873
874 It has the advantage that **the** ``Content-Type``
27f0892 @jkbrzt Improved examples.
authored
875 **header is automatically set** to the appropriate value based on the
381e60f @jkbrzt Extended README.
authored
876 filename extension. For example, the following request sends the
877 verbatim contents of that XML file with ``Content-Type: application/xml``:
878
879 .. code-block:: bash
880
881 $ http PUT httpbin.org/put @/data/file.xml
882
883
887f70f @jkbrzt Added CONTRIBUTING.rst.
authored
884 ===============
381e60f @jkbrzt Extended README.
authored
885 Terminal Output
887f70f @jkbrzt Added CONTRIBUTING.rst.
authored
886 ===============
381e60f @jkbrzt Extended README.
authored
887
27f0892 @jkbrzt Improved examples.
authored
888 HTTPie does several things by default in order to make its terminal output
889 easy to read.
381e60f @jkbrzt Extended README.
authored
890
891
892 ---------------------
893 Colors and Formatting
894 ---------------------
895
896 Syntax highlighting is applied to HTTP headers and bodies (where it makes
22a10ae @jkbrzt Added --colors and --format.
authored
897 sense). You can choose your prefered color scheme via the ``--style`` option
27f0892 @jkbrzt Improved examples.
authored
898 if you don't like the default one (see ``$ http --help`` for the possible
22a10ae @jkbrzt Added --colors and --format.
authored
899 values).
900
901 Also, the following formatting is applied:
381e60f @jkbrzt Extended README.
authored
902
903 * HTTP headers are sorted by name.
904 * JSON data is indented, sorted by keys, and unicode escapes are converted
905 to the characters they represent.
809a461 @jkbrzt v0.6.0
authored
906 * XML data is indented for better readability.
381e60f @jkbrzt Extended README.
authored
907
22a10ae @jkbrzt Added --colors and --format.
authored
908 One of these options can be used to control output processing:
381e60f @jkbrzt Extended README.
authored
909
bf03937 @jkbrzt Unified output processing options under --pretty.
authored
910 ==================== ========================================================
911 ``--pretty=all`` Apply both colors and formatting.
912 Default for terminal output.
913 ``--pretty=colors`` Apply colors.
914 ``--pretty=format`` Apply formatting.
915 ``--pretty=none`` Disables output processing.
916 Default for redirected output.
917 ==================== ========================================================
381e60f @jkbrzt Extended README.
authored
918
919 -----------
920 Binary data
921 -----------
922
923 Binary data is suppressed for terminal output, which makes it safe to perform
27f0892 @jkbrzt Improved examples.
authored
924 requests to URLs that send back binary data. Binary data is suppressed also in
381e60f @jkbrzt Extended README.
authored
925 redirected, but prettified output. The connection is closed as soon as we know
926 that the response body is binary,
927
928 .. code-block:: bash
929
bbc702f @jkbrzt Improved README.
authored
930 $ http example.org/Movie.mov
381e60f @jkbrzt Extended README.
authored
931
932
27f0892 @jkbrzt Improved examples.
authored
933 You will nearly instantly see something like this:
381e60f @jkbrzt Extended README.
authored
934
935 .. code-block:: http
936
937 HTTP/1.1 200 OK
938 Accept-Ranges: bytes
939 Content-Encoding: gzip
940 Content-Type: video/quicktime
941 Transfer-Encoding: chunked
942
943 +-----------------------------------------+
944 | NOTE: binary data not shown in terminal |
945 +-----------------------------------------+
946
947
948 =================
949 Redirected Output
950 =================
951
952 HTTPie uses **different defaults** for redirected output than for
953 `terminal output`_:
954
bf03937 @jkbrzt Unified output processing options under --pretty.
authored
955 * Formatting and colors aren't applied (unless ``--pretty`` is specified).
381e60f @jkbrzt Extended README.
authored
956 * Only the response body is printed (unless one of the `output options`_ is set).
957 * Also, binary data isn't suppressed.
958
959 The reason is to make piping HTTPie's output to another programs and
960 downloading files work with no extra flags. Most of the time, only the raw
961 response body is of an interest when the output is redirected.
962
963 Download a file:
964
965 .. code-block:: bash
966
967 $ http example.org/Movie.mov > Movie.mov
968
969
970 Download an image of Octocat, resize it using ImageMagick, upload it elsewhere:
971
972 .. code-block:: bash
973
974 $ http octodex.github.com/images/original.jpg | convert - -resize 25% - | http example.org/Octocats
975
976
27f0892 @jkbrzt Improved examples.
authored
977 Force colorizing and formatting, and show both the request and the response in
381e60f @jkbrzt Extended README.
authored
978 ``less`` pager:
979
980 .. code-block:: bash
981
bf03937 @jkbrzt Unified output processing options under --pretty.
authored
982 $ http --pretty=all --verbose example.org | less -R
381e60f @jkbrzt Extended README.
authored
983
984
27f0892 @jkbrzt Improved examples.
authored
985 The ``-R`` flag tells ``less`` to interpret color escape sequences included
986 HTTPie`s output.
987
444a9fa @jkbrzt Added `httpless` to README.
authored
988 You can create a shortcut for invoking HTTPie with colorized and paged output
2cf379d @jkbrzt Fixed README typo.
authored
989 by adding the following to your ``~/.bash_profile``:
444a9fa @jkbrzt Added `httpless` to README.
authored
990
991 .. code-block:: bash
992
993 function httpless {
994 # `httpless example.org'
60f0977 @jkbrzt `httpless` outputs also response headers by default
authored
995 http --pretty=all --print=hb "$@" | less -R;
444a9fa @jkbrzt Added `httpless` to README.
authored
996 }
997
27f0892 @jkbrzt Improved examples.
authored
998
8e6c765 @jkbrzt Initial --download implementation (#104).
authored
999 =============
1000 Download Mode
1001 =============
1002
55d5e78 @jkbrzt --download docs (#104).
authored
1003 HTTPie features a download mode in which it acts similarly to ``wget``.
1004
1005 When enabled using the ``--download, -d`` flag, response headers are printed to
1006 the terminal (``stderr``), and a progress bar is shown while the response body
1007 is being saved to a file.
1008
1009 .. code-block:: bash
1010
fa4bd03 @jkbrzt Updated links.
authored
1011 $ http --download https://github.com/jkbrzt/httpie/tarball/master
55d5e78 @jkbrzt --download docs (#104).
authored
1012
1013 .. code-block:: http
1014
1015 HTTP/1.1 200 OK
1016 Connection: keep-alive
fa4bd03 @jkbrzt Updated links.
authored
1017 Content-Disposition: attachment; filename=jkbrzt-httpie-0.4.1-33-gfc4f70a.tar.gz
55d5e78 @jkbrzt --download docs (#104).
authored
1018 Content-Length: 505530
1019 Content-Type: application/x-gzip
1020 Server: GitHub.com
1021 Vary: Accept-Encoding
1022
fa4bd03 @jkbrzt Updated links.
authored
1023 Downloading 494.89 kB to "jkbrzt-httpie-0.4.1-33-gfc4f70a.tar.gz"
6c3b983 @jkbrzt Tests
authored
1024 / 21.01% 104.00 kB 47.55 kB/s 0:00:08 ETA
55d5e78 @jkbrzt --download docs (#104).
authored
1025
1026
1027 If not provided via ``--output, -o``, the output filename will be determined
1028 from ``Content-Disposition`` (if available), or from the URL and
1029 ``Content-Type``. If the guessed filename already exists, HTTPie adds a unique
1030 suffix to it.
1031
1032 You can also redirect the response body to another program while the response
1033 headers and progress are still shown in the terminal:
1034
1035 .. code-block:: bash
1036
fa4bd03 @jkbrzt Updated links.
authored
1037 $ http -d https://github.com/jkbrzt/httpie/tarball/master | tar zxf -
55d5e78 @jkbrzt --download docs (#104).
authored
1038
1039
1040 If ``--output, -o`` is specified, you can resume a partial download using the
1041 ``--continue, -c`` option. This only works with servers that support
1042 ``Range`` requests and ``206 Partial Content`` responses. If the server doesn't
1043 support that, the whole file will simply be downloaded:
1044
1045 .. code-block:: bash
1046
e8d79c4 @jkbrzt Docs fix.
authored
1047 $ http -dco file.zip example.org/file
55d5e78 @jkbrzt --download docs (#104).
authored
1048
1049 Other notes:
1050
1051 * The ``--download`` option only changes how the response body is treated.
bc756cb @jkbrzt Cleanup
authored
1052 * You can still set custom headers, use sessions, ``--verbose, -v``, etc.
55d5e78 @jkbrzt --download docs (#104).
authored
1053 * ``--download`` always implies ``--follow`` (redirects are followed).
38206e9 @jkbrzt Cleanup
authored
1054 * HTTPie exits with status code ``1`` (error) if the body hasn't been fully
55d5e78 @jkbrzt --download docs (#104).
authored
1055 downloaded.
1056 * ``Accept-Encoding`` cannot be set with ``--download``.
8e6c765 @jkbrzt Initial --download implementation (#104).
authored
1057
1058
381e60f @jkbrzt Extended README.
authored
1059 ==================
1060 Streamed Responses
1061 ==================
1062
1063 Responses are downloaded and printed in chunks, which allows for streaming
1064 and large file downloads without using too much RAM. However, when
27f0892 @jkbrzt Improved examples.
authored
1065 `colors and formatting`_ is applied, the whole response is buffered and only
381e60f @jkbrzt Extended README.
authored
1066 then processed at once.
1067
1068
1069 You can use the ``--stream, -S`` flag to make two things happen:
1070
1071 1. The output is flushed in **much smaller chunks** without any buffering,
1072 which makes HTTPie behave kind of like ``tail -f`` for URLs.
1073
1074 2. Streaming becomes enabled even when the output is prettified: It will be
1075 applied to **each line** of the response and flushed immediately. This makes
27f0892 @jkbrzt Improved examples.
authored
1076 it possible to have a nice output for long-lived requests, such as one
381e60f @jkbrzt Extended README.
authored
1077 to the Twitter streaming API.
1078
1079
1080 Prettified streamed response:
1081
1082 .. code-block:: bash
1083
1084 $ http --stream -f -a YOUR-TWITTER-NAME https://stream.twitter.com/1/statuses/filter.json track='Justin Bieber'
1085
1086
27f0892 @jkbrzt Improved examples.
authored
1087 Streamed output by small chunks alá ``tail -f``:
381e60f @jkbrzt Extended README.
authored
1088
1089 .. code-block:: bash
1090
1091 # Send each new tweet (JSON object) mentioning "Apple" to another
1092 # server as soon as it arrives from the Twitter streaming API:
1093 $ http --stream -f -a YOUR-TWITTER-NAME https://stream.twitter.com/1/statuses/filter.json track=Apple \
1094 | while read tweet; do echo "$tweet" | http POST example.org/tweets ; done
1095
4a6f32a @jkbrzt Documented config.
authored
1096 ========
1097 Sessions
1098 ========
1099
87c59ae @jkbrzt Added anonymous sessions (--session=/file/path.json).
authored
1100 By default, every request is completely independent of any previous ones.
e09b740 @jkbrzt Ignore Content-* and If-* request headers.
authored
1101 HTTPie also supports persistent sessions, where custom headers (except for the
1102 ones starting with ``Content-`` or ``If-``), authorization, and cookies
1103 (manually specified or sent by the server) persist between requests
1104 to the same host.
e25d64a @jkbrzt 0.3.0
authored
1105
87c59ae @jkbrzt Added anonymous sessions (--session=/file/path.json).
authored
1106 --------------
1107 Named Sessions
1108 --------------
1109
1110 Create a new session named ``user1`` for ``example.org``:
4a6f32a @jkbrzt Documented config.
authored
1111
1112 .. code-block:: bash
1113
e25d64a @jkbrzt 0.3.0
authored
1114 $ http --session=user1 -a user1:password example.org X-Foo:Bar
4a6f32a @jkbrzt Documented config.
authored
1115
bbc702f @jkbrzt Improved README.
authored
1116 Now you can refer to the session by its name, and the previously used
1117 authorization and HTTP headers will automatically be set:
4a6f32a @jkbrzt Documented config.
authored
1118
1119 .. code-block:: bash
1120
e25d64a @jkbrzt 0.3.0
authored
1121 $ http --session=user1 example.org
4a6f32a @jkbrzt Documented config.
authored
1122
e25d64a @jkbrzt 0.3.0
authored
1123 To create or reuse a different session, simple specify a different name:
4a6f32a @jkbrzt Documented config.
authored
1124
1125 .. code-block:: bash
1126
e25d64a @jkbrzt 0.3.0
authored
1127 $ http --session=user2 -a user2:password example.org X-Bar:Foo
4a6f32a @jkbrzt Documented config.
authored
1128
1129 To use a session without updating it from the request/response exchange
1130 once it is created, specify the session name via
1131 ``--session-read-only=SESSION_NAME`` instead.
1132
87c59ae @jkbrzt Added anonymous sessions (--session=/file/path.json).
authored
1133 Named sessions' data is stored in JSON files in the directory
4a615e7 @jkbrzt Updated session docs.
authored
1134 ``~/.httpie/sessions/<host>/<name>.json``
4a6f32a @jkbrzt Documented config.
authored
1135 (``%APPDATA%\httpie\sessions\<host>\<name>.json`` on Windows).
87c59ae @jkbrzt Added anonymous sessions (--session=/file/path.json).
authored
1136
1137 ------------------
1138 Anonymous Sessions
1139 ------------------
1140
1141 Instead of a name, you can also directly specify a path to a session file. This
8e112a6 @jkbrzt test_download_no_Content_Length
authored
1142 allows for sessions to be re-used across multiple hosts:
87c59ae @jkbrzt Added anonymous sessions (--session=/file/path.json).
authored
1143
1144 .. code-block:: bash
1145
1146 $ http --session=/tmp/session.json example.org
1147 $ http --session=/tmp/session.json admin.example.org
1148 $ http --session=~/.httpie/sessions/another.example.org/test.json example.org
1149 $ http --session-read-only=/tmp/session.json example.org
1150
1151
4a615e7 @jkbrzt Updated session docs.
authored
1152 **Warning:** All session data, including credentials, cookie data,
1153 and custom headers are stored in plain text.
4a6f32a @jkbrzt Documented config.
authored
1154
87c59ae @jkbrzt Added anonymous sessions (--session=/file/path.json).
authored
1155 Note that session files can also be created and edited manually in a text
1156 editor; they are plain JSON.
4a615e7 @jkbrzt Updated session docs.
authored
1157
5cc5b13 @jkbrzt Removed the management command.
authored
1158 See also `Config`_.
4a6f32a @jkbrzt Documented config.
authored
1159
1160
1161 ======
1162 Config
1163 ======
1164
e25d64a @jkbrzt 0.3.0
authored
1165 HTTPie uses a simple configuration file that contains a JSON object with the
1166 following keys:
4a6f32a @jkbrzt Documented config.
authored
1167
1168 ========================= =================================================
2cdcadd @jkbrzt Added docs for `httpie`.
authored
1169 ``__meta__`` HTTPie automatically stores some metadata here.
4a6f32a @jkbrzt Documented config.
authored
1170 Do not change.
1171
1172 ``implicit_content_type`` A ``String`` specifying the implicit content type
1173 for request data. The default value for this
1174 option is ``json`` and can be changed to
1175 ``form``.
1176
1177 ``default_options`` An ``Array`` (by default empty) of options
1178 that should be applied to every request.
4a24cd2 @jkbrzt Clean up.
authored
1179
bbc702f @jkbrzt Improved README.
authored
1180 For instance, you can use this option to change
1181 the default style and output options:
1182 ``"default_options": ["--style=fruity", "--body"]``
9ec328f @jkbrzt Session commands.
authored
1183
1184 Another useful default option is
1185 ``"--session=default"`` to make HTTPie always
1186 use `sessions`_.
1187
5d96985 @jkbrzt Added --no-option's and made args more config-friendly.
authored
1188 Default options from config file can be unset
9ec328f @jkbrzt Session commands.
authored
1189 for a particular invocation via
1190 ``--no-OPTION`` arguments passed on the
1191 command line (e.g., ``--no-style``
1192 or ``--no-session``).
4a6f32a @jkbrzt Documented config.
authored
1193 ========================= =================================================
1194
9ec328f @jkbrzt Session commands.
authored
1195 The default location of the configuration file is ``~/.httpie/config.json``
1196 (or ``%APPDATA%\httpie\config.json`` on Windows).
4a6f32a @jkbrzt Documented config.
authored
1197
1198 The config directory location can be changed by setting the
1199 ``HTTPIE_CONFIG_DIR`` environment variable.
1200
1201
381e60f @jkbrzt Extended README.
authored
1202 =========
1203 Scripting
1204 =========
1205
1206 When using HTTPie from **shell scripts**, it can be handy to set the
2646eba @jkbrzt Replaced --ignore-http-status with --check-status.
authored
1207 ``--check-status`` flag. It instructs HTTPie to exit with an error if the
1208 HTTP status is one of ``3xx``, ``4xx``, or ``5xx``. The exit status will
da0eb7d @jkbrzt Renamed --allow-redirects to --follow.
authored
1209 be ``3`` (unless ``--follow`` is set), ``4``, or ``5``,
f7b703b @jkbrzt Added --ignore-stdin
authored
1210 respectively.
1211
1212 The ``--ignore-stdin`` option prevents HTTPie from reading data from ``stdin``,
1213 which is usually not desirable during non-interactive invocations.
1214
1215 Also, the ``--timeout`` option allows to overwrite the default 30s timeout:
5e7bb1f @jkbrzt Syntax-highlighting for examples in the README.
authored
1216
381e60f @jkbrzt Extended README.
authored
1217 .. code-block:: bash
2646eba @jkbrzt Replaced --ignore-http-status with --check-status.
authored
1218
1219 #!/bin/bash
1220
f7b703b @jkbrzt Added --ignore-stdin
authored
1221 if http --check-status --ignore-stdin --timeout=2.5 HEAD example.org/health &> /dev/null; then
2646eba @jkbrzt Replaced --ignore-http-status with --check-status.
authored
1222 echo 'OK!'
1223 else
1224 case $? in
c01dd8d @jkbrzt Added exit status for timed-out requests.
authored
1225 2) echo 'Request timed out!' ;;
381e60f @jkbrzt Extended README.
authored
1226 3) echo 'Unexpected HTTP 3xx Redirection!' ;;
1227 4) echo 'HTTP 4xx Client Error!' ;;
1228 5) echo 'HTTP 5xx Server Error!' ;;
2646eba @jkbrzt Replaced --ignore-http-status with --check-status.
authored
1229 *) echo 'Other Error!' ;;
1230 esac
1231 fi
1232
c7657e3 @jkbrzt Streamed terminal output
authored
1233
381e60f @jkbrzt Extended README.
authored
1234 ================
1235 Interface Design
1236 ================
1237
1238 The syntax of the command arguments closely corresponds to the actual HTTP
1239 requests sent over the wire. It has the advantage that it's easy to remember
1240 and read. It is often possible to translate an HTTP request to an HTTPie
1241 argument list just by inlining the request elements. For example, compare this
1242 HTTP request:
1243
1244 .. code-block:: http
1245
1246 POST /collection HTTP/1.1
1247 X-API-Key: 123
1248 User-Agent: Bacon/1.0
1249 Content-Type: application/x-www-form-urlencoded
1250
1251 name=value&name2=value2
1252
1253
1254 with the HTTPie command that sends it:
7ca6191 @jkbrzt v0.1.5
authored
1255
381e60f @jkbrzt Extended README.
authored
1256 .. code-block:: bash
1257
1258 $ http -f POST example.org/collection \
1259 X-API-Key:123 \
1260 User-Agent:Bacon/1.0 \
1261 name=value \
1262 name2=value2
1263
1264
1265 Notice that both the order of elements and the syntax is very similar,
1266 and that only a small portion of the command is used to control HTTPie and
1267 doesn't directly correspond to any part of the request (here it's only ``-f``
1268 asking HTTPie to send a form request).
1269
bf03937 @jkbrzt Unified output processing options under --pretty.
authored
1270 The two modes, ``--pretty=all`` (default for terminal) and ``--pretty=none``
381e60f @jkbrzt Extended README.
authored
1271 (default for redirected output), allow for both user-friendly interactive use
1272 and usage from scripts, where HTTPie serves as a generic HTTP client.
1273
27f0892 @jkbrzt Improved examples.
authored
1274 As HTTPie is still under heavy development, the existing command line
1275 syntax and some of the ``--OPTIONS`` may change slightly before
1276 HTTPie reaches its final version ``1.0``. All changes are recorded in the
b7fc89a @jkbrzt README fixes
authored
1277 `change log`_.
1278
1279
1280
fb43759 @jkbrzt Include AUTHORS.rst in dist; metadata cleanup
authored
1281 =======
1282 Authors
1283 =======
27f0892 @jkbrzt Improved examples.
authored
1284
381e60f @jkbrzt Extended README.
authored
1285
fa4bd03 @jkbrzt Updated links.
authored
1286 `Jakub Roztocil`_ (`@jkbrzt`_) created HTTPie and `these fine people`_
fb43759 @jkbrzt Include AUTHORS.rst in dist; metadata cleanup
authored
1287 have contributed.
9cdbd6b @jkbrzt Added a Contribute section to README.
authored
1288
381e60f @jkbrzt Extended README.
authored
1289
887f70f @jkbrzt Added CONTRIBUTING.rst.
authored
1290 ====
d97a610 @jkbrzt Added new logo by @claudiatd :sparkles:
authored
1291 Logo
887f70f @jkbrzt Added CONTRIBUTING.rst.
authored
1292 ====
d97a610 @jkbrzt Added new logo by @claudiatd :sparkles:
authored
1293
887f70f @jkbrzt Added CONTRIBUTING.rst.
authored
1294 Please see `claudiatd/httpie-artwork`_
b53d483 @jkbrzt v0.2.6
authored
1295
b7fc89a @jkbrzt README fixes
authored
1296
fb43759 @jkbrzt Include AUTHORS.rst in dist; metadata cleanup
authored
1297 ==========
1298 Contribute
1299 ==========
5e7bb1f @jkbrzt Syntax-highlighting for examples in the README.
authored
1300
fa4bd03 @jkbrzt Updated links.
authored
1301 Please see `CONTRIBUTING <https://github.com/jkbrzt/httpie/blob/master/CONTRIBUTING.rst>`_.
5e7bb1f @jkbrzt Syntax-highlighting for examples in the README.
authored
1302
b7fc89a @jkbrzt README fixes
authored
1303
1304 ==========
1305 Change Log
1306 ==========
1307
fa4bd03 @jkbrzt Updated links.
authored
1308 Please see `CHANGELOG <https://github.com/jkbrzt/httpie/blob/master/CHANGELOG.rst>`_.
b7fc89a @jkbrzt README fixes
authored
1309
1310
381e60f @jkbrzt Extended README.
authored
1311 =======
1312 Licence
1313 =======
1314
fa4bd03 @jkbrzt Updated links.
authored
1315 Please see `LICENSE <https://github.com/jkbrzt/httpie/blob/master/LICENSE>`_.
381e60f @jkbrzt Extended README.
authored
1316
b53d483 @jkbrzt v0.2.6
authored
1317
1318
1319 .. _Requests: http://python-requests.org
1320 .. _Pygments: http://pygments.org/
1321 .. _pip: http://www.pip-installer.org/en/latest/index.html
381e60f @jkbrzt Extended README.
authored
1322 .. _Github API: http://developer.github.com/v3/issues/comments/#create-a-comment
fa4bd03 @jkbrzt Updated links.
authored
1323 .. _these fine people: https://github.com/jkbrzt/httpie/contributors
1324 .. _Jakub Roztocil: http://roztocil.co
1325 .. _@jkbrzt: https://twitter.com/jkbrzt
d97a610 @jkbrzt Added new logo by @claudiatd :sparkles:
authored
1326 .. _claudiatd/httpie-artwork: https://github.com/claudiatd/httpie-artwork
5c29a4e @jkbrzt Added windows build status icon to README.
authored
1327
1328
5760b78 @jkbrzt README
authored
1329 .. |pypi| image:: https://img.shields.io/pypi/v/httpie.svg?style=flat-square&label=latest%20version
3b3eff0 @jkbrzt Use shields.io badges
authored
1330 :target: https://pypi.python.org/pypi/httpie
5760b78 @jkbrzt README
authored
1331 :alt: Latest version released on PyPi
5c29a4e @jkbrzt Added windows build status icon to README.
authored
1332
fa4bd03 @jkbrzt Updated links.
authored
1333 .. |coverage| image:: https://img.shields.io/coveralls/jkbrzt/httpie/master.svg?style=flat-square
1334 :target: https://coveralls.io/r/jkbrzt/httpie?branch=master
5760b78 @jkbrzt README
authored
1335 :alt: Test coverage
92a4352 @jkbrzt Added a coveralls badge.
authored
1336
fa4bd03 @jkbrzt Updated links.
authored
1337 .. |unix_build| image:: https://img.shields.io/travis/jkbrzt/httpie/master.svg?style=flat-square&label=unix%20build
1338 :target: http://travis-ci.org/jkbrzt/httpie
5760b78 @jkbrzt README
authored
1339 :alt: Build status of the master branch on Mac/Linux
5c29a4e @jkbrzt Added windows build status icon to README.
authored
1340
fa4bd03 @jkbrzt Updated links.
authored
1341 .. |windows_build| image:: https://img.shields.io/appveyor/ci/jkbrzt/httpie.svg?style=flat-square&label=windows%20build
1342 :target: https://ci.appveyor.com/project/jkbrzt/httpie
5760b78 @jkbrzt README
authored
1343 :alt: Build status of the master branch on Windows
Something went wrong with that request. Please try again.