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).
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.
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).
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](#file-based-separators) for more examples.
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/fooHTTP/1.1
Host:localhost
```
```bash
$ http :3000/bar
```
```http
GET/barHTTP/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:
| Data Fields `field=value` | 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.
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 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
```
### 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'`).
Letās start with a simple example, and build a simple search query:
```bash
$ http --offline --print=B pie.dev/post \
category=tools \
search[type]=id \
search[id]:=1
```
In the example above, the `search[type]` is an instruction for creating an object called `search`, and setting the `type` field of it to the given value (`"id"`).
Also note that, just as the regular syntax, you can use the `:=` operator to directly pass raw JSON values (e.g, numbers in the case above).
Building arrays is also possible, through `[]` suffix (an append operation). This tells HTTPie to create an array in the given path (if there is not one already), and append the given value to that array.
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`.
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:
There are a couple of default headers that HTTPie sets:
```http
GET/HTTP/1.1
Accept:*/*
Accept-Encoding:gzip, deflate
User-Agent:HTTPie/<version>
Host:<taken-from-URL>
```
Any of these can be overwritten and some of them 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.
```bash
$ 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:`:
```bash
$ http pie.dev/headers Accept: User-Agent:
```
To send a header with an empty value, use `Header;`, with a semicolon:
```bash
$ http pie.dev/headers 'Header;'
```
Please note that some internal headers, such as `Content-Length`, canāt be unset if
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` 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=180i=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 either a `username:password` pair or a `token` as the argument. If the selected authenticated method requires username/password combination and 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`, `bearer` 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
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
exportHTTP_PROXY=http://10.10.1.10:3128
exportHTTPS_PROXY=https://10.10.1.10:1080
exportNO_PROXY=localhost,example.com
```
### SOCKS
Usage for SOCKS is the same as for other types of [proxies](#proxies):
The response metadata section currently includes the total time elapsed. Itās the number of seconds between opening the network connection and downloading the last byte of response the body.
The [extra verbose `-vv` output](#extra-verbose-output) includes the meta section by default. You can also show it in combination with other parts of the exchange via [`--print=m`](#what-parts-of-the-http-exchange-should-be-printed). For example, here we print it together with the response headers:
Please note that it also includes time spent on formatting the output, which adds a small penalty. Also, if the body is not part of the output, [we donāt spend time downloading it](#conditional-body-download).
If you [use `--style` with one of the Pie themes](#colors-and-formatting), youāll see the time information color-coded (green/yellow/orange/red) based on how long the exchange took.
### Verbose output
`--verbose` can often be useful for debugging the request and generating documentation examples:
When there is a new release available for your platform (for example; if you installed HTTPie through `pip`, it will check the latest version on `PyPI`), HTTPie will regularly warn you about the new update (once a week). If you want to disable this behavior, you can set `disable_update_warnings` to `true` in your [config](#config) file.
### Viewing intermediary requests/responses
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).
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:
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 are 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.
You may also use `--chunked` to enable streaming via [chunked transfer encoding](#chunked-transfer-encoding)
or `--compress, -x` to [compress the request body](#compressed-request-body).
There are multiple useful ways to use piping:
Redirect from a file:
```bash
$ http PUT pie.dev/put X-API-Token:123 < files/data.json
| `auto` | Follows your terminal ANSI color styles. This is the default style used by HTTPie |
| `default` | Default styles of the underlying Pygments library. Not actually used by default by HTTPie. You can enable it with `--style=default` |
| `pie-dark` | HTTPieās original brand style. Also used in [HTTPie for Web and Desktop](https://httpie.io/product). |
| `pie-light` | Like `pie-dark`, but for terminals with light background colors. |
| `pie` | A generic version of `pie-dark` and `pie-light` themes that can work with any terminal background. Its universality requires compromises in terms of legibility, but itās useful if you frequently switch your terminal between dark and light backgrounds. |
| `monokai` | A popular color scheme. Enable with `--style=monokai` |
| `fruity` | A bold, colorful scheme. Enable with `--style=fruity` |
| ā¦ | See `$ http --help` for all the possible `--style` values |
Use one of these options to control output processing:
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`:
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:
Force colorizing and formatting, and show both the request and the response in `less` pager:
```bash
$ http --pretty=all --verbose pie.dev/get | less -R
```
The `-R` flag tells `less` to interpret color escape sequences included HTTPieās output.
You can create a shortcut for invoking HTTPie with colorized and paged output by adding the following to your `~/.bash_profile`:
```bash
function httpless {
# `httpless example.org'
http --pretty=all --print=hb "$@"| less -R;
}
```
### Binary data
Binary data is suppressed for terminal output, which makes it safe to perform requests to URLs that send back binary data.
Binary data is also suppressed in redirected but prettified output.
The connection is closed as soon as we know that the response body is binary,
```bash
$ http pie.dev/bytes/2000
```
You will nearly instantly see something like this:
```http
HTTP/1.1200OK
Content-Type:application/octet-stream
```
### Display encoding
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.
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).
The `--stream` option is automatically enabled when the response headers include `Content-Type: text/event-stream`.
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, prompted passwords, 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).
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.
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:
To make a cookie domain _unbound_ (i.e., to make it available to all hosts, including throughout a cross-domain redirect chain), you can set the `domain` field to `null` in the session file:
There are three possible sources of persisted cookies within a session. They have the following storage priority: 1āresponse; 2ācommand line; 3āsession file.
HTTPie may introduce changes in the session file format. When HTTPie detects an obsolete format, it shows a warning. You can upgrade your session files using the following commands:
Upgrade all existing [named sessions](#named-sessions) inside the `sessions` subfolder of your [config directory](https://httpie.io/docs/cli/config-file-directory):
```bash
$ httpie cli sessions upgrade-all
Upgraded 'api_auth' @ 'pie.dev' to v3.1.0
Upgraded 'login_cookies' @ 'httpie.io' to v3.1.0
```
Upgrading individual sessions requires you to specify the session's hostname. That allows HTTPie to find the correct file in the case of name sessions. Additionally, it allows it to correctly bind cookies when upgrading with [`--bind-cookies`](#session-upgrade-options).
Upgrade a single [named session](#named-sessions):
| `--bind-cookies` | Bind all previously [unbound cookies](#host-based-cookie-policy) to the sessionās host ([context](https://github.com/httpie/httpie/security/advisories/GHSA-9w4w-cpc8-h2fq)). |
The default location of the configuration file on most platforms is `$XDG_CONFIG_HOME/httpie/config.json` (defaulting to `~/.config/httpie/config.json`).
Technically, it is possible to include any HTTPie options in there.
However, it is not recommended modifying the default behavior in a way that would break your compatibility with the wider world as that may become confusing.
#### `plugins_dir`
The directory where the plugins will be installed. HTTPie needs to have read/write access on that directory, since
`httpie cli plugins install` will download new plugins to there. See [plugin manager](#plugin-manager) for more information.
### 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.
## Plugin manager
HTTPie offers extensibility through a [plugin API](https://github.com/httpie/httpie/blob/master/httpie/plugins/base.py),
and there are dozens of plugins available to try!
They add things like new authentication methods ([akamai/httpie-edgegrid](https://github.com/akamai/httpie-edgegrid)),
transport mechanisms ([httpie/httpie-unixsocket](https://github.com/httpie/httpie-unixsocket)),
message convertors ([banteg/httpie-image](https://github.com/banteg/httpie-image)), or simply
change how a response is formatted.
> Note: Plugins are usually made by our community members, and thus have no direct relationship with
> the HTTPie project. We do not control / review them at the moment, so use them at your own discretion.
For managing these plugins; starting with 3.0, we are offering a new plugin manager.
This command is currently in beta.
### `httpie cli`
#### `httpie cli check-updates`
You can check whether a new update is available for your system by running `httpie cli check-updates`:
| `json` | Export the parser spec in JSON. The schema includes a top-level `version` parameter which should be interpreted in [semver](https://semver.org/). |
You can use any of these formats with `--format` parameter, but the default one is `json`.
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).
### Community and Support
HTTPie has the following community channels:
- [GitHub Issues](https://github.com/httpie/httpie/issues) for bug reports and feature requests
- [Discord server](https://httpie.io/discord) to ask questions, discuss features, and for general API development discussion
- [StackOverflow](https://stackoverflow.com) to ask questions (make sure to use the [httpie](https://stackoverflow.com/questions/tagged/httpie) tag)
### Related projects
#### Dependencies
Under the hood, HTTPie uses these two amazing libraries:
- [Requests](https://python-requests.org) ā Python HTTP library for humans
[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.
