mirror of
https://github.com/httpie/cli.git
synced 2024-11-28 08:38:44 +02:00
370 lines
16 KiB
ReStructuredText
370 lines
16 KiB
ReStructuredText
HTTPie: cURL for humans
|
|
=======================
|
|
|
|
`☞ README for stable version <https://github.com/jkbr/httpie/tree/0.2.5#readme>`_
|
|
|
|
**HTTPie is a CLI HTTP utility** built out of frustration with existing tools.
|
|
The goal is to make CLI interaction with HTTP-based services as
|
|
human-friendly as possible.
|
|
|
|
HTTPie does so by providing an ``http`` command that allows for issuing
|
|
arbitrary HTTP requests using a **simple and natural syntax** and displaying
|
|
**colorized responses**:
|
|
|
|
.. image:: https://github.com/jkbr/httpie/raw/master/httpie.png
|
|
:alt: HTTPie compared to cURL
|
|
|
|
Under the hood, HTTPie uses the excellent
|
|
`Requests <http://python-requests.org>`_ and
|
|
`Pygments <http://pygments.org/>`_ Python libraries. Python 2.6+ is supported
|
|
(including 3.x).
|
|
|
|
Installation
|
|
------------
|
|
|
|
The latest **stable version** of HTTPie can always be installed
|
|
(or updated to) via
|
|
`pip <http://www.pip-installer.org/en/latest/index.html>`_::
|
|
|
|
pip install -U httpie
|
|
|
|
You can also use `easy_install` (``pip`` is prefered, though)::
|
|
|
|
easy_install httpie
|
|
|
|
Or, you can install the **development version** directly from GitHub:
|
|
|
|
.. image:: https://secure.travis-ci.org/jkbr/httpie.png
|
|
:target: http://travis-ci.org/jkbr/httpie
|
|
:alt: Build Status of the master branch
|
|
|
|
::
|
|
|
|
pip install -U https://github.com/jkbr/httpie/tarball/master
|
|
|
|
|
|
There are packages available for
|
|
`Ubuntu <http://packages.ubuntu.com/httpie>`_,
|
|
`Debian <http://packages.debian.org/httpie>`_ and
|
|
possibly other major distros as well.
|
|
|
|
|
|
Usage
|
|
-----
|
|
|
|
Hello world::
|
|
|
|
http httpie.org
|
|
|
|
Synopsis::
|
|
|
|
http [flags] [METHOD] URL [items]
|
|
|
|
There are five types of key-value pair items available:
|
|
|
|
Headers (``Name:Value``)
|
|
Arbitrary HTTP headers. The ``:`` character is used to separate a header's
|
|
name from its value, e.g., ``X-API-Token:123``.
|
|
|
|
Simple data fields (``field=value``)
|
|
Data items are included in the request body. Depending on the
|
|
``Content-Type``, they are automatically serialized as a JSON ``Object``
|
|
(default) or ``application/x-www-form-urlencoded`` (the ``-f`` flag).
|
|
Data items use ``=`` as the separator, e.g., ``hello=world``.
|
|
|
|
Raw JSON fields (``field:=value``)
|
|
This item type is needed when ``Content-Type`` is JSON and a field's value
|
|
is a ``Boolean``, ``Number``, nested ``Object`` or an ``Array``, because
|
|
simple data items are always serialized as ``String``.
|
|
E.g. ``pies:=[1,2,3]``.
|
|
|
|
File fields (``field@/path/to/file``)
|
|
Only available with ``-f`` / ``--form``. Use ``@`` as the separator, e.g.,
|
|
``screenshot@/path/to/file.png``. The presence of a file field results into
|
|
a ``multipart/form-data`` request.
|
|
|
|
Query string parameters (``name==value``)
|
|
Appends the given name/value pair as a query string parameter to the URL.
|
|
|
|
|
|
Examples
|
|
^^^^^^^^
|
|
::
|
|
|
|
http PATCH api.example.com/person/1 X-API-Token:123 name=John email=john@example.org age:=29
|
|
|
|
|
|
The following request is issued::
|
|
|
|
PATCH /person/1 HTTP/1.1
|
|
User-Agent: HTTPie/0.1
|
|
X-API-Token: 123
|
|
Content-Type: application/json; charset=utf-8
|
|
|
|
{"name": "John", "email": "john@example.org", "age": 29}
|
|
|
|
|
|
It can easily be changed to a **form** request using the ``-f``
|
|
(or ``--form``) flag, which produces::
|
|
|
|
PATCH /person/1 HTTP/1.1
|
|
User-Agent: HTTPie/0.1
|
|
X-API-Token: 123
|
|
Content-Type: application/x-www-form-urlencoded; charset=utf-8
|
|
|
|
age=29&name=John&email=john%40example.org
|
|
|
|
It is also possible to send ``multipart/form-data`` requests, i.e., to
|
|
simulate a **file upload form** submission. It is done using the
|
|
``--form`` / ``-f`` flag and passing one or more file fields::
|
|
|
|
http -f POST example.com/jobs name=John cv@~/Documents/cv.pdf
|
|
|
|
The above will send the same request as if the following HTML form were submitted::
|
|
|
|
<form enctype="multipart/form-data" method="post" action="http://example.com/jobs">
|
|
<input type="text" name="name" />
|
|
<input type="file" name="cv" />
|
|
</form>
|
|
|
|
**Query string parameters** can be added to any request without having to quote
|
|
the ``&`` characters::
|
|
|
|
http GET example.com/ search==donuts in==fridge
|
|
|
|
Will ``GET` the URL ``http://example.com/?search=donuts&in=fridge``.
|
|
|
|
A whole request body can be passed in via **``stdin``** instead, in which
|
|
case it will be used with no further processing::
|
|
|
|
echo '{"name": "John"}' | http PATCH example.com/person/1 X-API-Token:123
|
|
# Or:
|
|
http POST example.com/person/1 X-API-Token:123 < person.json
|
|
|
|
That can be used for **piping services together**. The following example
|
|
``GET``-s JSON data from the Github API and ``POST``-s it to httpbin.org::
|
|
|
|
http GET https://api.github.com/repos/jkbr/httpie | http POST httpbin.org/post
|
|
|
|
The above can be further simplified by omitting ``GET`` and ``POST`` because
|
|
they are both default here. The first command has no request data, whereas
|
|
the second one does via ``stdin``::
|
|
|
|
http https://api.github.com/repos/jkbr/httpie | http httpbin.org/post
|
|
|
|
Note that when the **output is redirected** (like the examples above), HTTPie
|
|
applies a different set of defaults then for console output. Namely colors
|
|
aren't used (can be forced with ``--pretty``) and only the response body
|
|
gets printed (can be overwritten with ``--print``).
|
|
|
|
An alternative to ``stdin`` is to pass a file name whose content will be used
|
|
as the request body. It has the advantage that the ``Content-Type`` header
|
|
will automatically be set to the appropriate value based on the filename
|
|
extension (using the ``mimetypes`` module). Therefore, the following will
|
|
request will send the verbatim contents of the file with
|
|
``Content-Type: application/xml``::
|
|
|
|
http PUT httpbin.org/put @/data/file.xml
|
|
|
|
When using HTTPie from **shell scripts**, you might want to use the
|
|
``--check-status`` flag. It instructs HTTPie to exit with an error if the
|
|
HTTP status is one of ``3xx``, ``4xx``, or ``5xx``. The exit status will
|
|
be ``3`` (unless ``--allow-redirects`` is set), ``4``, or ``5``
|
|
respectivelly::
|
|
|
|
#!/bin/bash
|
|
|
|
if http --check-status HEAD example.org/health &> /dev/null; then
|
|
echo 'OK!'
|
|
else
|
|
case $? in
|
|
3) echo 'Unexpected 3xx Redirection!' ;;
|
|
4) echo '4xx Client Error!' ;;
|
|
5) echo '5xx Server Error!' ;;
|
|
*) echo 'Other Error!' ;;
|
|
esac
|
|
fi
|
|
|
|
|
|
Flags
|
|
^^^^^
|
|
Most of the flags mirror the arguments understood by ``requests.request``.
|
|
See ``http -h`` for more details::
|
|
|
|
$ http --help
|
|
usage: http [-h] [--version] [--json | --form] [--traceback]
|
|
[--pretty | --ugly]
|
|
[--print OUTPUT_OPTIONS | --verbose | --headers | --body]
|
|
[--style STYLE] [--check-status] [--auth AUTH]
|
|
[--auth-type {basic,digest}] [--verify VERIFY] [--proxy PROXY]
|
|
[--allow-redirects] [--timeout TIMEOUT]
|
|
[METHOD] URL [ITEM [ITEM ...]]
|
|
|
|
HTTPie - cURL for humans. <http://httpie.org>
|
|
|
|
positional arguments:
|
|
METHOD The HTTP method to be used for the request (GET, POST,
|
|
PUT, DELETE, PATCH, ...). If this argument is omitted,
|
|
then HTTPie will guess the HTTP method. If there is
|
|
some data to be sent, then it will be POST, otherwise
|
|
GET.
|
|
URL The protocol defaults to http:// if the URL does not
|
|
include one.
|
|
ITEM A key-value pair whose type is defined by the
|
|
separator used. It can be an HTTP header
|
|
(header:value), a data field to be used in the request
|
|
body (field_name=value), a raw JSON data field
|
|
(field_name:=value), a query parameter (name=value),
|
|
or a file field (field_name@/path/to/file). You can
|
|
use a backslash to escape a colliding separator in the
|
|
field name.
|
|
|
|
optional arguments:
|
|
-h, --help show this help message and exit
|
|
--version show program's version number and exit
|
|
--json, -j (default) Data items from the command line are
|
|
serialized as a JSON object. The Content-Type and
|
|
Accept headers are set to application/json (if not
|
|
specified).
|
|
--form, -f Data items from the command line are serialized as
|
|
form fields. The Content-Type is set to application/x
|
|
-www-form-urlencoded (if not specified). The presence
|
|
of any file fields results into a multipart/form-data
|
|
request.
|
|
--traceback Print exception traceback should one occur.
|
|
--pretty If stdout is a terminal, the response is prettified by
|
|
default (colorized and indented if it is JSON). This
|
|
flag ensures prettifying even when stdout is
|
|
redirected.
|
|
--ugly, -u Do not prettify the response.
|
|
--print OUTPUT_OPTIONS, -p OUTPUT_OPTIONS
|
|
String specifying what the output should contain: "H"
|
|
stands for the request headers, and "B" for the
|
|
request body. "h" stands for the response headers and
|
|
"b" for response the body. The default behaviour is
|
|
"hb" (i.e., the response headers and body is printed),
|
|
if standard output is not redirected. If the output is
|
|
piped to another program or to a file, then only the
|
|
body is printed by default.
|
|
--verbose, -v Print the whole request as well as the response.
|
|
Shortcut for --print=HBhb.
|
|
--headers, -t Print only the response headers. Shortcut for
|
|
--print=h.
|
|
--body, -b Print only the response body. Shortcut for --print=b.
|
|
--style STYLE, -s STYLE
|
|
Output coloring style, one of autumn, borland, bw,
|
|
colorful, default, emacs, friendly, fruity, manni,
|
|
monokai, murphy, native, pastie, perldoc, rrt,
|
|
solarized, tango, trac, vim, vs. Defaults to
|
|
solarized. For this option to work properly, please
|
|
make sure that the $TERM environment variable is set
|
|
to "xterm-256color" or similar (e.g., via `export TERM
|
|
=xterm-256color' in your ~/.bashrc).
|
|
--check-status By default, HTTPie exits with 0 when no network or
|
|
other fatal errors occur. This flag instructs HTTPie
|
|
to also check the HTTP status code and exit with an
|
|
error if the status indicates one. When the server
|
|
replies with a 4xx (Client Error) or 5xx (Server
|
|
Error) status code, HTTPie exits with 4 or 5
|
|
respectively. If the response is a 3xx (Redirect) and
|
|
--allow-redirects hasn't been set, then the exit
|
|
status is 3. Also an error message is written to
|
|
stderr if stdout is redirected.
|
|
--auth AUTH, -a AUTH username:password. If only the username is provided
|
|
(-a username), HTTPie will prompt for the password.
|
|
--auth-type {basic,digest}
|
|
The authentication mechanism to be used. Defaults to
|
|
"basic".
|
|
--verify VERIFY Set to "no" to skip checking the host's SSL
|
|
certificate. You can also pass the path to a CA_BUNDLE
|
|
file for private certs. You can also set the
|
|
REQUESTS_CA_BUNDLE environment variable. Defaults to
|
|
"yes".
|
|
--proxy PROXY String mapping protocol to the URL of the proxy (e.g.
|
|
http:foo.bar:3128).
|
|
--allow-redirects Set this flag if full redirects are allowed (e.g. re-
|
|
POST-ing of data at new ``Location``)
|
|
--timeout TIMEOUT Float describes the timeout of the request (Use
|
|
socket.setdefaulttimeout() as fallback).
|
|
|
|
|
|
|
|
Contribute
|
|
-----------
|
|
|
|
`View contributors on GitHub <https://github.com/jkbr/httpie/contributors>`_.
|
|
|
|
If you have found a bug or have a feature request, the
|
|
`issue tracker <https://github.com/jkbr/httpie/issues?state=open>`_ is the
|
|
place to start a discussion about it.
|
|
|
|
To contribute code or documentation, please first browse the existing issues
|
|
to see if the feature/bug has previously been discussed. Then fork
|
|
`the repository <https://github.com/jkbr/httpie>`_, make changes in your
|
|
develop branch and submit a pull request. Note: Pull requests with tests and
|
|
documentation are 53.6% more awesome :)
|
|
|
|
To point the ``http`` command to your working copy you can install HTTPie in
|
|
the editable mode::
|
|
|
|
pip install --editable .
|
|
|
|
It's a good idea to run the existing suite of tests before a pull requests is
|
|
submitted::
|
|
|
|
python setup.py test
|
|
|
|
`Tox <http://tox.testrun.org/>`_ can used to conveniently run tests in all of
|
|
the
|
|
`supported Python environments <https://github.com/jkbr/httpie/blob/master/tox.ini>`_::
|
|
|
|
# Install tox
|
|
pip install tox
|
|
|
|
# Run tests
|
|
tox
|
|
|
|
Changelog
|
|
---------
|
|
|
|
* `0.2.6dev <https://github.com/jkbr/httpie/compare/0.2.5...master>`_
|
|
* Form data and URL params can now have mutiple fields with the same name
|
|
(e.g.,``http -f url a=1 a=2``).
|
|
* Added ``--check-status`` to exit with an error for HTTP 3xx, 4xx and
|
|
5xx (3, 4, 5).
|
|
* If the output is piped to another program or redirected to a file,
|
|
the new default behaviour is to only print the response body.
|
|
(It can still be overriden via the ``--print`` flag.)
|
|
* Improved highlighing of HTTP headers.
|
|
* Added query string parameters (param==value).
|
|
* Added support for terminal colors under Windows.
|
|
* `0.2.5 <https://github.com/jkbr/httpie/compare/0.2.2...0.2.5>`_ (2012-07-17)
|
|
* Unicode characters in prettified JSON now don't get escaped for
|
|
improved readability.
|
|
* --auth now prompts for a password if only a username provided.
|
|
* Added support for request payloads from a file path with automatic
|
|
``Content-Type`` (``http URL @/path``).
|
|
* Fixed missing query string when displaing the request headers via
|
|
``--verbose``.
|
|
* Fixed Content-Type for requests with no data.
|
|
* `0.2.2 <https://github.com/jkbr/httpie/compare/0.2.1...0.2.2>`_ (2012-06-24)
|
|
* The ``METHOD`` positional argument can now be omitted (defaults to
|
|
``GET``, or to ``POST`` with data).
|
|
* Fixed --verbose --form.
|
|
* Added support for `Tox <http://tox.testrun.org/>`_.
|
|
* `0.2.1 <https://github.com/jkbr/httpie/compare/0.2.0...0.2.1>`_ (2012-06-13)
|
|
* Added compatibility with ``requests-0.12.1``.
|
|
* Dropped custom JSON and HTTP lexers in favor of the ones newly included
|
|
in ``pygments-1.5``.
|
|
* `0.2.0 <https://github.com/jkbr/httpie/compare/0.1.6...0.2.0>`_ (2012-04-25)
|
|
* Added Python 3 support.
|
|
* Added the ability to print the HTTP request as well as the response
|
|
(see ``--print`` and ``--verbose``).
|
|
* Added support for Digest authentication.
|
|
* Added file upload support
|
|
(``http -f POST file_field_name@/path/to/file``).
|
|
* Improved syntax highlighting for JSON.
|
|
* Added support for field name escaping.
|
|
* Many bug fixes.
|
|
* `0.1.6 <https://github.com/jkbr/httpie/compare/0.1.4...0.1.6>`_ (2012-03-04)
|