This documentation is best viewed at [httpie.io/docs](https://httpie.org/docs).
You can select your corresponding HTTPie version as well as run examples directly from the browser using a [termible.io](https://termible.io?utm_source=httpie-readme) embedded terminal.
If you are reading this on GitHub, then this text covers the current *development* version.
You are invited to submit fixes and improvements to the docs by editing [this file](https://github.com/httpie/httpie/blob/master/docs/README.md).
To install [Spack](https://spack.readthedocs.io/en/latest/index.html), see [its installation](https://spack.readthedocs.io/en/latest/getting_started.html#installation).
Also works for other Debian-derived distributions like MX Linux, Linux Mint, deepin, Pop!_OS, KDE neon, Zorin OS, elementary OS, Kubuntu, Devuan, Linux Lite, Peppermint OS, Lubuntu, antiX, Xubuntu, etc.
To install [Spack](https://spack.readthedocs.io/en/latest/index.html), see [its installation](https://spack.readthedocs.io/en/latest/getting_started.html#installation).
Verify that now you have the [current development version identifier](https://github.com/httpie/httpie/blob/master/httpie/__init__.py#L6) with the `.dev0` suffix, for example:
Custom [HTTP method](#http-method), [HTTP headers](#http-headers) and [JSON](#json) data:
```bash
$ http PUT pie.dev/put X-API-Token:123 name=John
```
Submitting [forms](#forms):
```bash
$ http -f POST pie.dev/post hello=World
```
See the request that is being sent using one of the [output options](#output-options):
```bash
$ http -v pie.dev/get
```
Build and print a request without sending it using [offline mode](#offline-mode):
```bash
$ http --offline pie.dev/post hello=offline
```
Use [GitHub API](https://developer.github.com/v3/issues/comments/#create-a-comment) to post a comment on an [issue](https://github.com/httpie/httpie/issues/83) with [authentication](#authentication):
```bash
$ http -a USERNAME POST https://api.github.com/repos/httpie/httpie/issues/83/comments body='HTTPie is awesome! :heart:'
```
Upload a file using [redirected input](#redirected-input):
```bash
$ http pie.dev/post <files/data.json
```
Download a file and save it via [redirected output](#redirected-output):
```bash
$ http pie.dev/image/png > image.png
```
Download a file `wget` style:
```bash
$ http --download pie.dev/image/png
```
Use named [sessions](#sessions) to make certain aspects of the communication persistent between requests to the same host:
```bash
$ http --session=logged-in -a username:password pie.dev/get API-Key:123
```
```bash
$ http --session=logged-in pie.dev/headers
```
Set a custom `Host` header to work around missing DNS records:
```bash
$ http localhost:8000 Host:example.com
```
## HTTP method
The name of the HTTP method comes right before the URL argument:
```bash
$ http DELETE pie.dev/delete
```
Which looks similar to the actual `Request-Line` that is sent:
When you paste a URL into the terminal, you can even keep the `://` bit in the URL argument to quickly convert the URL into an HTTPie call just by adding a space after the protocol name.
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).
GET /search/repositories?q=httpie&per_page=1 HTTP/1.1
```
### 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.
```bash
$ http :/foo
```
```http
GET /foo HTTP/1.1
Host: localhost
```
```bash
$ http :3000/bar
```
```http
GET /bar HTTP/1.1
Host: localhost:3000
```
```bash
$ http :
```
```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](https://pypi.org/search/?q=httpie)). Example for the [httpie-unixsocket](https://github.com/httpie/httpie-unixsocket) plugin:
There are a few different *request item* types that provide a convenient mechanism for specifying HTTP headers, simple JSON and form data, files, and URL parameters.
They are key/value pairs specified after the URL. All have in common that they become part of the actual request that is sent and that their type is distinguished only by the separator used: `:`, `=`, `:=`, `==`, `@`, `=@`, and `:=@`. The ones with an `@` expect a file path as value.
| URL parameters `name==value` | Appends the given name/value pair as a querystring parameter to the URL. The `==` separator is used. |
| Data Fields `field=value`, `field=@file.txt` | Request data fields to be serialized as a JSON object (default), to be form-encoded (with `--form, -f`), or to be serialized as `multipart/form-data` (with `--multipart`) |
| Raw JSON fields `field:=json` | Useful when sending JSON and one or more fields need to be a `Boolean`, `Number`, nested `Object`, or an `Array`, e.g., `meals:='["ham","spam"]'` or `pies:=[1,2,3]` (note the quotes) |
| File upload fields `field@/dir/file`, `field@file;type=mime` | Only available with `--form`, `-f` and `--multipart`. For example `screenshot@~/Pictures/img.png`, or `'cv@cv.txt;type=text/markdown'`. With `--form`, the presence of a file field results in a `--multipart` request |
Note that the structured data fields aren’t the only way to specify request data:
[raw request body](#raw-request-body) is a mechanism for passing arbitrary request data.
### 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`:
JSON is the *lingua franca* of modern web services and it is also the **implicit content type** HTTPie uses by default.
Simple example:
```bash
$ http PUT pie.dev/put name=John email=john@example.org
```
```http
PUT / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Content-Type: application/json
Host: pie.dev
{
"name": "John",
"email": "john@example.org"
}
```
### Default behavior
If your command includes some data [request items](#request-items), they are serialized as a JSON object by default. HTTPie also automatically sets the following headers, both of which can be overwritten:
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 `:=@`:
```bash
$ 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
```
```http
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",
}
}
```
### Raw and complex JSON
Please note that with the [request items](#request-items) data field syntax, commands can quickly become unwieldy when sending complex structures.
In such cases, it’s better to pass the full raw JSON data via [raw request body](#raw-request-body), for example:
```bash
$ echo -n '{"hello": "world"}' | http POST pie.dev/post
```
```bash
$ http --raw '{"hello": "world"}' POST pie.dev/post
```
```bash
$ http POST pie.dev/post <files/data.json
```
Furthermore, the structure syntax only allows you to send an object as the JSON document, but not an array, etc.
Here, again, the solution is to use [redirected input](#redirected-input).
## Forms
Submitting forms is very similar to sending [JSON](#json) requests.
Often the only difference is in adding the `--form, -f` option, which ensures that data fields are serialized as, and `Content-Type` is set to `application/x-www-form-urlencoded; charset=utf-8`.
It is possible to make form data the implicit content type instead of JSON via the [config](#config) file.
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:
The `--max-headers=n` options allows you to control the number of headers HTTPie reads before giving up (the default `0`, i.e., there’s no limit).
```bash
$ http --max-headers=100 pie.dev/get
```
## Offline mode
Use `--offline` to construct HTTP requests without sending them anywhere.
With `--offline`, HTTPie builds a request based on the specified options and arguments, prints it to `stdout`, and then exits. It works completely offline; no network connection is ever made. This has a number of use cases, including:
Generating API documentation examples that you can copy & paste without sending a request:
```bash
$ http --offline POST server.chess/api/games API-Key:ZZZ w=magnus b=hikaru t=180 i=2
If you often deal with cookies in your requests, then you’d appreciate
the [sessions](#sessions) feature.
## Authentication
The currently supported authentication schemes are Basic and Digest (see [auth plugins](#auth-plugins) for more). There are two flags that control authentication:
| `--auth, -a` | Pass a `username:password` pair as the argument. Or, if you only specify a username (`-a username`), you’ll be prompted for the password before the request is sent. To send an empty password, pass `username:`. The `username:password@hostname` URL syntax is supported as well (but credentials passed via `-a` have higher priority) |
| `--auth-type, -A` | Specify the auth mechanism. Possible values are `basic`, `digest`, or the name of any [auth plugins](#auth-plugins) you have installed. The default value is `basic` so it can often be omitted |
### Basic auth
```bash
$ http -a username:password pie.dev/basic-auth/username/password
```
### Digest auth
```bash
$ http -A digest -a username:password pie.dev/digest-auth/httpie/username/password
```
### Password prompt
```bash
$ http -a username pie.dev/basic-auth/username/password
```
### Empty password
```bash
$ http -a username: pie.dev/headers
```
### `.netrc`
Authentication information from your `~/.netrc` file is by default honored as well.
For example:
```bash
$ cat ~/.netrc
machine pie.dev
login httpie
password test
```
```bash
$ http pie.dev/basic-auth/httpie/test
HTTP/1.1 200 OK
[...]
```
This can be disabled with the `--ignore-netrc` option:
You can specify proxies to be used through the `--proxy` argument for each protocol (which is included in the value in case of redirects across protocols):
You can also configure proxies by environment variables `ALL_PROXY`, `HTTP_PROXY` and `HTTPS_PROXY`, and the underlying [Requests library](https://python-requests.org/) will pick them up.
If you want to disable proxies configured through the environment variables for certain hosts, you can specify them in `NO_PROXY`.
In your `~/.bash_profile`:
```bash
export HTTP_PROXY=http://10.10.1.10:3128
export HTTPS_PROXY=https://10.10.1.10:1080
export NO_PROXY=localhost,example.com
```
### SOCKS
Usage for SOCKS is the same as for other types of [proxies](#proxies):
To see all the HTTP communication, i.e. the final request/response as well as any possible intermediary requests/responses, use the `--all` option.
The intermediary HTTP communication include followed redirects (with `--follow`), the first unauthorized request when HTTP digest authentication is used (`--auth=digest`), etc.
```bash
# Include all responses that lead to the final one:
$ http --all --follow pie.dev/redirect/3
```
The intermediary requests/responses are by default formatted according to `--print, -p` (and its shortcuts described above).
If you’d like to change that, use the `--history-print, -P` option.
It takes the same arguments as `--print, -p` but applies to the intermediary requests only.
```bash
# Print the intermediary requests/responses differently than the final one:
$ http -A digest -a foo:bar --all -p Hh -P H pie.dev/digest-auth/auth/foo/bar
```
### Conditional body download
As an optimization, the response body is downloaded from the server only if it’s part of the output.
This is similar to performing a `HEAD` request, except that it applies to any HTTP method you use.
Let’s say that there is an API that returns the whole resource when it is updated, but you are only interested in the response headers to see the status code after an update:
Since you are only printing the HTTP headers here, the connection to the server is closed as soon as all the response headers have been received.
Therefore, bandwidth and time isn’t wasted downloading the body which you don’t care about.
The response headers are downloaded always, even if they are not part of the output
## Raw request body
In addition to crafting structured [JSON](#json) and [forms](#forms) requests with the [request items](#request-items) syntax, you can provide a raw request body that will be sent without further processing.
These two approaches for specifying request data (i.e., structured and raw) cannot be combined.
There’re three methods for passing raw request data: piping via `stdin`,
`--raw='data'`, and `@/file/path`.
### Redirected Input
The universal method for passing request data is through redirected `stdin`
(standard input)—piping.
By default, `stdin` data is buffered and then with no further processing used as the request body.
If you provide `Content-Length`, then the request body is streamed without buffering.
HTTPie looks at `Content-Type` to select the right syntax highlighter and formatter for each message body. If that fails (e.g., the server provides the wrong type), or you prefer a different treatment, you can manually overwrite the mime type for a response with `--response-mime`:
There are also two shortcuts that allow you to quickly disable and re-enable
sorting-related format options (currently it means JSON keys and headers):
`--unsorted` and `--sorted`.
This is something you will typically store as one of the default options in your [config](#config) file.
### Redirected output
HTTPie uses a different set of defaults for redirected output than for [terminal output](#terminal-output).
The differences being:
- Formatting and colors aren’t applied (unless `--pretty` is specified).
- Only the response body is printed (unless one of the [output options](#output-options) is set).
- Also, binary data isn’t suppressed.
The reason is to make piping HTTPie’s output to another programs and downloading files work with no extra flags.
Most of the time, only the raw response body is of an interest when the output is redirected.
Download a file:
```bash
$ http pie.dev/image/png > image.png
```
Download an image of an [Octocat](https://octodex.github.com/images/original.jpg), resize it using [ImageMagick](https://imagemagick.org/), and upload it elsewhere:
HTTPie tries to do its best to decode message bodies when printing them to the terminal correctly. It uses the encoding specified in the `Content-Type``charset` attribute. If a message doesn’t define its charset, we auto-detect it. For very short messages (1–32B), where auto-detection would be unreliable, we default to UTF-8. For cases when the response encoding is still incorrect, you can manually overwrite the response charset with `--response-charset`:
HTTPie features a download mode in which it acts similarly to `wget`.
When enabled using the `--download, -d` flag, response headers are printed to the terminal (`stderr`), and a progress bar is shown while the response body is being saved to a file.
There are three mutually exclusive ways through which HTTPie determines
the output filename (with decreasing priority):
1. You can explicitly provide it via `--output, -o`. The file gets overwritten if it already exists (or appended to with `--continue, -c`).
2. The server may specify the filename in the optional `Content-Disposition` response header. Any leading dots are stripped from a server-provided filename.
3. The last resort HTTPie uses is to generate the filename from a combination of the request URL and the response `Content-Type`. The initial URL is always used as the basis for the generated filename — even if there has been one or more redirects.
To prevent data loss by overwriting, HTTPie adds a unique numerical suffix to the filename when necessary (unless specified with `--output, -o`).
### Piping while downloading
You can also redirect the response body to another program while the response headers and progress are still shown in the terminal:
```bash
$ http -d https://github.com/httpie/httpie/archive/master.tar.gz | tar zxf -
```
### Resuming downloads
If `--output, -o` is specified, you can resume a partial download using the `--continue, -c` option.
This only works with servers that support `Range` requests and `206 Partial Content` responses.
If the server doesn’t support that, the whole file will simply be downloaded:
```bash
$ http -dco file.zip example.org/file
```
`-dco` is shorthand for `--download``--continue``--output`.
### Other notes
- The `--download` option only changes how the response body is treated.
- You can still set custom headers, use sessions, `--verbose, -v`, etc.
-`--download` always implies `--follow` (redirects are followed).
-`--download` also implies `--check-status` (error HTTP status will result in a non-zero exist static code).
- HTTPie exits with status code `1` (error) if the body hasn’t been fully downloaded.
-`Accept-Encoding` can't be set with `--download`.
## Streamed responses
Responses are downloaded and printed in chunks.
This allows for streaming and large file downloads without using too much memory.
However, when [colors and formatting](#colors-and-formatting) are applied, the whole response is buffered and only then processed at once.
### Disabling buffering
You can use the `--stream, -S` flag to make two things happen:
1. The output is flushed in much smaller chunks without any buffering, which makes HTTPie behave kind of like `tail -f` for URLs.
2. Streaming becomes enabled even when the output is prettified: It will be applied to each line of the response and flushed immediately. This makes it possible to have a nice output for long-lived requests, such as one to the [Twitter streaming API](https://developer.twitter.com/en/docs/tutorials/consuming-streaming-data).
### Example use cases
Prettified streamed response:
```bash
$ http --stream pie.dev/stream/3
```
Streamed output by small chunks à la `tail -f`:
```bash
# Send each new line (JSON object) to another URL as soon as it arrives from a streaming API:
$ http --stream pie.dev/stream/3 | while read line; do echo "$line" | http pie.dev/post ; done
```
## Sessions
By default, every request HTTPie makes is completely independent of any previous ones to the same host.
However, HTTPie also supports persistent sessions via the `--session=SESSION_NAME_OR_PATH` option.
In a session, custom [HTTP headers](#http-headers) (except for the ones starting with `Content-` or `If-`), [authentication](#authentication), and [cookies](#cookies) (manually specified or sent by the server) persist between requests to the same host.
# Re-use the existing session — the API-Token header will be set:
$ http --session=./session.json pie.dev/headers
```
All session data, including credentials, cookie data, and custom headers are stored in plain text.
That means session files can also be created and edited manually in a text editor—they are regular JSON.
It also means that they can be read by anyone who has access to the session file.
### Named sessions
You can create one or more named session per host. For example, this is how you can create a new session named `user1` for `pie.dev`:
```bash
$ http --session=user1 -a user1:password pie.dev/get X-Foo:Bar
```
From now on, you can refer to the session by its name (`user1`).
When you choose to use the session again, all previously specified authentication or HTTP headers will automatically be set:
```bash
$ http --session=user1 pie.dev/get
```
To create or reuse a different session, simply specify a different name:
```bash
$ http --session=user2 -a user2:password pie.dev/get X-Bar:Foo
```
Named sessions’ data is stored in JSON files inside the `sessions` subdirectory of the [config](#config) directory, typically `~/.config/httpie/sessions/<host>/<name>.json` (`%APPDATA%\httpie\sessions\<host>\<name>.json` on Windows).
If you have executed the above commands on a Unix machine, you should be able list the generated sessions files using:
```bash
$ ls -l ~/.config/httpie/sessions/pie.dev
```
### Anonymous sessions
Instead of giving it a name, you can also directly specify a path to a session file.
This allows for sessions to be re-used across multiple hosts:
```bash
# Create a session:
$ http --session=/tmp/session.json example.org
```
```bash
# Use the session to make a request to another host:
When creating anonymous sessions, please remember to always include at least one `/`, even if the session files is located in the current directory (i.e. `--session=./session.json` instead of just `--session=session.json`), otherwise HTTPie assumes a named session instead.
### Readonly session
To use the original session file without updating it from the request/response exchange after it has been created, specify the session name via `--session-read-only=SESSION_NAME_OR_PATH` instead.
```bash
# If the session file doesn’t exist, then it is created:
Cookies will be set in the session file with the priority specified above.
For example, a cookie set through the command line will overwrite a cookie of the same name stored in the session file.
If the server returns a `Set-Cookie` header with a cookie of the same name, the returned cookie will overwrite the preexisting cookie.
Expired cookies are never stored.
If a cookie in a session file expires, it will be removed before sending a new request.
If the server expires an existing cookie, it will also be removed from the session file.
## Config
HTTPie uses a simple `config.json` file.
The file doesn’t exist by default but you can create it manually.
### Config file directory
To see the exact location for your installation, run `http --debug` and look for `config_dir` in the output.
The default location of the configuration file on most platforms is `$XDG_CONFIG_HOME/httpie/config.json` (defaulting to `~/.config/httpie/config.json`).
For backwards compatibility, if the directory `~/.httpie` exists, the configuration file there will be used instead.
On Windows, the config file is located at `%APPDATA%\httpie\config.json`.
The config directory can be changed by setting the `$HTTPIE_CONFIG_DIR` environment variable:
```bash
$ export HTTPIE_CONFIG_DIR=/tmp/httpie
$ http pie.dev/get
```
### Configurable options
Currently, HTTPie offers a single configurable option:
#### `default_options`
An `Array` (by default empty) of default options that should be applied to every invocation of HTTPie.
For instance, you can use this config option to change your default color theme:
```bash
$ cat ~/.config/httpie/config.json
```
```json
{
"default_options": [
"--style=fruity"
]
}
```
Technically, it is possible to include any HTTPie options in there.
However, it is not recommended to modify the default behavior in a way that would break your compatibility with the wider world as that may become confusing.
### Un-setting previously specified options
Default options from the config file, or specified any other way, can be unset for a particular invocation via `--no-OPTION` arguments passed via the command line (e.g., `--no-style` or `--no-session`).
## Scripting
When using HTTPie from shell scripts, it can be handy to set 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 `--follow` is set), `4`, or `5`, respectively.
```bash
#!/bin/bash
if http --check-status --ignore-stdin --timeout=2.5 HEAD pie.dev/get &> /dev/null; then
The default behavior of automatically reading `stdin` is typically not desirable during non-interactive invocations.
You most likely want to use the `--ignore-stdin` option to disable it.
It is a common *gotcha* that without this option HTTPie seemingly hangs.
What happens is that when HTTPie is invoked, for example, from a cron job, `stdin` is not connected to a terminal.
Therefore, the rules for [redirected input](#redirected-input) apply, i.e. HTTPie starts to read it expecting that the request body will be passed through.
And since there’s neither data nor `EOF`, it will get stuck. So unless you’re piping some data to HTTPie, the `--ignore-stdin` flag should be used in scripts.
Also, it might be good to set a connection `--timeout` limit to prevent your program from hanging if the server never responds.
## Meta
### Interface design
The syntax of the command arguments closely correspond to the actual HTTP requests sent over the wire.
It has the advantage that it’s easy to remember and read.
You can often translate an HTTP request to an HTTPie argument list just by inlining the request elements.
For example, compare this HTTP request:
```http
POST /post HTTP/1.1
Host: pie.dev
X-API-Key: 123
User-Agent: Bacon/1.0
Content-Type: application/x-www-form-urlencoded
name=value&name2=value2
```
with the HTTPie command that sends it:
```bash
$ http -f POST pie.dev/post \
X-API-Key:123 \
User-Agent:Bacon/1.0 \
name=value \
name2=value2
```
Notice that both the order of elements and the syntax are very similar, and that only a small portion of the command is used to control HTTPie and doesn’t directly correspond to any part of the request (here, it’s only `-f` asking HTTPie to send a form request).
The two modes, `--pretty=all` (default for terminal) and `--pretty=none` (default for [redirected output](#redirected-output)), allow for both user-friendly interactive use and usage from scripts, where HTTPie serves as a generic HTTP client.
In the future, the command line syntax and some of the `--OPTIONS` may change slightly, as HTTPie improves and new features are added.
All changes are recorded in the [change log](#change-log).
[Jakub Roztocil](https://roztocil.co) ([@jakubroztocil](https://twitter.com/jakubroztocil)) created HTTPie and [these fine people](https://github.com/httpie/httpie/blob/master/AUTHORS.md) have contributed.
