httpie 0.2.6

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 escape the & characters. The following request will contain ?search=donuts&in=fridge as the query string part of the URL:

http GET example.com search==donuts in==fridge

The whole request body can also be passed in via stdin, 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 as the first command has no request data whereas the second one has 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 than for a console output. Namely, colors aren’t used (unless --pretty is set) and only the response body is printed (unless --print options specified).

An alternative to stdin is to pass a filename 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. Thus, 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 it can be useful 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, respectively:

#!/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

$ http --help:

usage: http [--help] [--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:
  --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, -h         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).