HTTPie CLI docs

Unstable version

If you want to try out the latest version of HTTPie that hasn't been officially released yet, you can install the development or unstable version directly from the master branch on GitHub. However, keep in mind that the development version is a work in progress and may not be as reliable as the stable version.

You can use the following command to install the development version of HTTPie on Linux, macOS, Windows, or FreeBSD operating systems. With this command, the code present in the master branch is downloaded and installed using pip.

$ python -m pip install --upgrade https://github.com/httpie/cli/archive/master.tar.gz

There are other ways to install the development version of HTTPie on macOS and Linux.

You can install it using Homebrew by running the following commands:

$ brew uninstall --force httpie
$ brew install --HEAD httpie

You can install it using Snapcraft by running the following commands:

$ snap remove httpie
$ snap install httpie --edge

To verify the installation, you can compare the version identifier on GitHub with the one available on your machine. You can check the version of HTTPie on your machine by using the command http --version.

$ http --version
# 3.X.X.dev0

Note that on your machine, the version name will have the .dev0 suffix.

Examples

Custom HTTP method, HTTP headers and JSON data:

$ http PUT pie.dev/put X-API-Token:123 name=John

Submitting forms:

$ http -f POST pie.dev/post hello=World

See the request that is being sent using one of the output options:

$ http -v pie.dev/get

Build and print a request without sending it using offline mode:

$ http --offline pie.dev/post hello=offline

Use GitHub API to post a comment on an issue with authentication:

$ http -a USERNAME POST https://api.github.com/repos/httpie/cli/issues/83/comments body='HTTPie is awesome! :heart:'

Upload a file using redirected input:

$ http pie.dev/post < files/data.json

Download a file and save it via redirected output:

$ http pie.dev/image/png > image.png

Download a file wget style:

$ http --download pie.dev/image/png

Use named sessions to make certain aspects of the communication persistent between requests to the same host:

$ http --session=logged-in -a username:password pie.dev/get API-Key:123

$ http --session=logged-in pie.dev/headers

Set a custom Host header to work around missing DNS records:

$ http localhost:8000 Host:example.com

Optional GET and POST

The METHOD argument is optional, and when you don’t specify it, HTTPie defaults to:

• GET for requests without body
• POST for requests with body

Here we don’t specify any request data, so both commands will send the same GET request:

$ http GET pie.dev/get

$ http pie.dev/get

Here, on the other hand, we do have some data, so both commands will make the same POST request:

$ http POST pie.dev/post hello=world

$ http pie.dev/post hello=world

Querystring parameters

If you find yourself manually constructing URLs with querystring parameters on the terminal, you may appreciate the param==value syntax for appending URL parameters.

With that, you don’t have to worry about escaping the & separators for your shell. Additionally, any special characters in the parameter name or value get automatically URL-escaped (as opposed to the parameters specified in the full URL, which HTTPie doesn’t modify).

$ http https://api.github.com/search/repositories q==httpie per_page==1

GET /search/repositories?q=httpie&per_page=1 HTTP/1.1

You can even retrieve the value from a file by using the param==@file syntax. This would also effectively strip the newlines from the end. See file based separators for more examples.

$ http pie.dev/get text==@files/text.txt

URL shortcuts for localhost

Additionally, curl-like shorthand for localhost is supported. This means that, for example, :3000 would expand to http://localhost:3000. If the port is omitted, then port 80 is assumed.

$ http :/foo

GET /foo HTTP/1.1
Host: localhost

$ http :3000/bar

GET /bar HTTP/1.1
Host: localhost:3000

$ http :

GET / HTTP/1.1
Host: localhost

Other default schemes

When HTTPie is invoked as https then the default scheme is https:// ($ https example.org will make a request to https://example.org).

You can also use the --default-scheme <URL_SCHEME> option to create shortcuts for other protocols than HTTP (possibly supported via plugins). Example for the httpie-unixsocket plugin:

# Before
$ http http+unix://%2Fvar%2Frun%2Fdocker.sock/info

# Create an alias
$ alias http-unix='http --default-scheme="http+unix"'

# Now the scheme can be omitted
$ http-unix %2Fvar%2Frun%2Fdocker.sock/info

--path-as-is

The standard behavior of HTTP clients is to normalize the path portion of URLs by squashing dot segments as a typical filesystem would:

$ http -v example.org/./../../etc/password

GET /etc/password HTTP/1.1

The --path-as-is option allows you to disable this behavior:

$ http --path-as-is -v example.org/./../../etc/password

GET /../../etc/password HTTP/1.1

File based separators

Using file contents as values for specific fields is a very common use case, which can be achieved through adding the @ suffix to the operators above. For example, instead of using a static string as the value for some header, you can use :@ operator to pass the desired value from a file.

$ http POST pie.dev/post \
    X-Data:@files/text.txt             # Read a header from a file
    token==@files/text.txt             # Read a query parameter from a file
    name=@files/text.txt               # Read a data field’s value from a file
    bookmarks:=@files/data.json        # Embed a JSON object from a file

Escaping rules

You can use \ to escape characters that shouldn’t be used as separators (or parts thereof). For instance, foo\==bar will become a data key/value pair (foo= and bar) instead of a URL parameter.

Often it is necessary to quote the values, e.g. foo='bar baz'.

If any of the field names or headers starts with a minus (e.g. -fieldname), you need to place all such items after the special token -- to prevent confusion with --arguments:

$ http pie.dev/post -- -name-starting-with-dash=foo -Unusual-Header:bar

POST /post HTTP/1.1
-Unusual-Header: bar
Content-Type: application/json

{
    "-name-starting-with-dash": "foo"
}

Default behavior

If your command includes some data request items, they are serialized as a JSON object by default. HTTPie also automatically sets the following headers, both of which can be overwritten:

Explicit JSON

You can use --json, -j to explicitly set Accept to application/json regardless of whether you are sending data (it’s a shortcut for setting the header via the usual header notation: http url Accept:'application/json, */*;q=0.5'). Additionally, HTTPie will try to detect JSON responses even when the Content-Type is incorrectly text/plain or unknown.

Non-string JSON fields

Non-string JSON fields use the := separator, which allows you to embed arbitrary JSON data into the resulting JSON object. Additionally, text and raw JSON files can also be embedded into fields using =@ and :=@:

$ http PUT pie.dev/put \
    name=John \                        # String (default)
    age:=29 \                          # Raw JSON — Number
    married:=false \                   # Raw JSON — Boolean
    hobbies:='["http", "pies"]' \      # Raw JSON — Array
    favorite:='{"tool": "HTTPie"}' \   # Raw JSON — Object
    bookmarks:=@files/data.json \      # Embed JSON file
    description=@files/text.txt        # Embed text file

PUT /person/1 HTTP/1.1
Accept: application/json, */*;q=0.5
Content-Type: application/json
Host: pie.dev

{
    "age": 29,
    "hobbies": [
        "http",
        "pies"
    ],
    "description": "John is a nice guy who likes pies.",
    "married": false,
    "name": "John",
    "favorite": {
        "tool": "HTTPie"
    },
    "bookmarks": {
        "HTTPie": "https://httpie.org",
    }
}

The :=/:=@ syntax is JSON-specific. You can switch your request to --form or --multipart, and string, float, and number values will continue to be serialized (as string form values). Other JSON types, however, are not allowed with --form or --multipart.

Nested JSON

If your use case involves sending complex JSON objects as part of the request body, HTTPie can help you build them right from your terminal. You still use the existing data field operators (=/:=) but instead of specifying a top-level field name (like key=value), you specify a path declaration. This tells HTTPie where and how to put the given value inside an object:

http pie.dev/post \
  platform[name]=HTTPie \
  platform[about][mission]='Make APIs simple and intuitive' \
  platform[about][homepage]=httpie.io \
  platform[about][homepage]=httpie.io \
  platform[about][stars]:=54000 \
  platform[apps][]=Terminal \
  platform[apps][]=Desktop \
  platform[apps][]=Web \
  platform[apps][]=Mobile

{
    "platform": {
        "name": "HTTPie",
        "about": {
            "mission": "Make APIs simple and intuitive",
            "homepage": "httpie.io",
            "stars": 54000
        },
        "apps": [
            "Terminal",
            "Desktop",
            "Web",
            "Mobile"
        ]
    }
}

$ http --offline --print=B pie.dev/post \
  category=tools \
  search[type]=id \
  search[id]:=1

{
    "category": "tools",
    "search": {
        "id": 1,
        "type": "id"
    }
}

$ http --offline --print=B pie.dev/post \
  category=tools \
  search[type]=keyword \
  search[keywords][]=APIs \
  search[keywords][]=CLI

{
    "category": "tools",
    "search": {
        "keywords": [
            "APIs",
            "CLI"
        ],
        "type": "keyword"
    }
}

$ http --offline --print=B pie.dev/post \
  category=tools \
  search[type]=keyword \
  search[keywords][1]=APIs \
  search[keywords][0]=CLI

{
    "category": "tools",
    "search": {
        "keywords": [
            "CLIs",
            "API"
        ],
        "type": "keyword"
    }
}

$ http --offline --print=B pie.dev/post \
  category=tools \
  search[type]=platforms \
  search[platforms][]=Terminal \
  search[platforms][1]=Desktop \
  search[platforms][3]=Mobile

{
    "category": "tools",
    "search": {
        "platforms": [
            "Terminal",
            "Desktop",
            null,
            "Mobile"
        ],
        "type": "platforms"
    }
}

$ http --offline --print=B pie.dev/post \
  category=tools \
  search[type]=platforms \
  'search[platforms]:=["Terminal", "Desktop"]' \
  search[platforms][]=Web \
  search[platforms][]=Mobile

{
    "category": "tools",
    "search": {
        "platforms": [
            "Terminal",
            "Desktop",
            "Web",
            "Mobile"
        ],
        "type": "platforms"
    }
}

$ http PUT pie.dev/put \
    shallow=value \                                # Shallow key-value pair
    object[key]=value \                            # Nested key-value pair
    array[]:=1 \                                   # Array — first item
    array[1]:=2 \                                  # Array — second item
    array[2]:=3 \                                  # Array — append (third item)
    very[nested][json][3][httpie][power][]=Amaze   # Nested object

$ http --offline --print=B pie.dev/post \
    []:=1 \
    []:=2 \
    []:=3

[
    1,
    2,
    3
]

http --offline --print=B pie.dev/post \
    [0][type]=platform [0][name]=terminal \
    [1][type]=platform [1][name]=desktop

[
    {
        "type": "platform",
        "name": "terminal"
    },
    {
        "type": "platform",
        "name": "desktop"
    }
]

$ http --offline --print=B pie.dev/post \
  'foo\[bar\]:=1' \
  'baz[\[]:=2' \
  'baz[\]]:=3'

{
    "baz": {
        "[": 2,
        "]": 3
    },
    "foo[bar]": 1
}

$ http --offline --print=B pie.dev/post \
  'backslash[\\]:=1'

{
    "backslash": {
        "\\": 1
    }
}

$ http --offline --print=B pie.dev/post \
  'object[\1]=stringified' \
  'object[\100]=same' \
  'array[1]=indexified'

{
    "array": [
        null,
        "indexified"
    ],
    "object": {
        "1": "stringified",
        "100": "same"
    }
}

$ http --offline --print=B pie.dev/post \
  'foo[bar]=OK' \
  'foo[baz][quux=FAIL'

HTTPie Syntax Error: Expecting ']'
foo[baz][quux
             ^

$ http --offline --print=B pie.dev/post \
  'array[]:=1' \
  'array[]:=2' \
  'array[key]:=3'
HTTPie Type Error: Can't perform 'key' based access on 'array' which has a type of 'array' but this operation requires a type of 'object'.
array[key]
     ^^^^^

$ http --offline --print=B pie.dev/post \
  user[name]:=411     # Defined as an integer
  user[name]=string   # Overridden with a string

{
    "user": {
        "name": "string"
    }
}

Raw JSON

For very complex JSON structures, it may be more convenient to pass it as raw request body, for example:

$ echo -n '{"hello": "world"}' | http POST pie.dev/post

$ http POST pie.dev/post < files/data.json

Regular forms

$ http --form POST pie.dev/post name='John Smith'

POST /post HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=utf-8

name=John+Smith

File upload forms

If one or more file fields is present, the serialization and content type is multipart/form-data:

$ http -f POST pie.dev/post name='John Smith' cv@~/files/data.xml

The request above is the same 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>

Please note that @ is used to simulate a file upload form field, whereas =@ just embeds the file content as a regular text field value.

When uploading files, their content type is inferred from the file name. You can manually override the inferred content type:

$ http -f POST pie.dev/post name='John Smith' cv@'~/files/data.bin;type=application/pdf'

To perform a multipart/form-data request even without any files, use --multipart instead of --form:

$ http --multipart --offline example.org hello=world

POST / HTTP/1.1
Content-Length: 129
Content-Type: multipart/form-data; boundary=c31279ab254f40aeb06df32b433cbccb
Host: example.org

--c31279ab254f40aeb06df32b433cbccb
Content-Disposition: form-data; name="hello"

world
--c31279ab254f40aeb06df32b433cbccb--

File uploads are always streamed to avoid memory issues with large files.

By default, HTTPie uses a random unique string as the multipart boundary, but you can use --boundary to specify a custom string instead:

$ http --form --multipart --boundary=xoxo --offline example.org hello=world

POST / HTTP/1.1
Content-Length: 129
Content-Type: multipart/form-data; boundary=xoxo
Host: example.org

--xoxo
Content-Disposition: form-data; name="hello"

world
--xoxo--

If you specify a custom Content-Type header without including the boundary bit, HTTPie will add the boundary value (explicitly specified or auto-generated) to the header automatically:

$ http --form --multipart --offline example.org hello=world Content-Type:multipart/letter

POST / HTTP/1.1
Content-Length: 129
Content-Type: multipart/letter; boundary=c31279ab254f40aeb06df32b433cbccb
Host: example.org

--c31279ab254f40aeb06df32b433cbccb
Content-Disposition: form-data; name="hello"

world
--c31279ab254f40aeb06df32b433cbccb--

Default request headers

There are a couple of default headers that HTTPie sets:

GET / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
User-Agent: HTTPie/<version>
Host: <taken-from-URL>

All of these can be overwritten or unset (see below).

Reading headers from a file

You can read headers from a file by using the :@ operator. This would also effectively strip the newlines from the end. See file based separators for more examples.

$ http pie.dev/headers X-Data:@files/text.txt

Empty headers and header un-setting

To unset a previously specified header (such a one of the default headers), use Header::

$ http pie.dev/headers Accept: User-Agent:

To send a header with an empty value, use Header;, with a semicolon:

$ http pie.dev/headers 'Header;'

Please note that some internal headers, such as Content-Length, can’t be unset if they are automatically added by the client itself.

Multiple header values with the same name

If the request is sent with multiple headers that are sharing the same name, then the HTTPie will send them individually.

http --offline example.org Cookie:one Cookie:two

GET / HTTP/1.1
Cookie: one
Cookie: two

It is also possible to pass a single header value pair, where the value is a comma separated list of header values. Then the client will send it as a single header.

http --offline example.org Numbers:one,two

GET / HTTP/1.1
Numbers: one,two

Also be aware that if the current session contains any headers they will get overwritten by individual commands when sending a request instead of being joined together.

Limiting response headers

The --max-headers=n option allows you to control the number of headers HTTPie reads before giving up (the default 0, i.e., there’s no limit).

$ http --max-headers=100 pie.dev/get

Basic auth

$ http -a username:password pie.dev/basic-auth/username/password

Digest auth

$ http -A digest -a username:password pie.dev/digest-auth/httpie/username/password

Bearer auth