README.md
1# xh
2[](https://crates.io/crates/xh)
3[](https://repology.org/project/xh/versions)
4
5`xh` is a friendly and fast tool for sending HTTP requests. It reimplements as much
6as possible of [HTTPie's](https://httpie.io/) excellent design, with a focus
7on improved performance.
8
9[](https://asciinema.org/a/390748)
10
11## Installation
12
13### via cURL (Linux & macOS)
14
15```
16curl -sfL https://raw.githubusercontent.com/ducaale/xh/master/install.sh | sh
17```
18
19### via a package manager
20
21| OS | Method | Command |
22|---------------- |------------|-------------------------|
23| Any | Cargo\* | `cargo install xh` |
24| Any | [Huber] | `huber install xh` |
25| Arch Linux | Pacman | `pacman -S xh` |
26| Debian & Ubuntu | Apt** | `sudo apt install xh` |
27| FreeBSD | FreshPorts | `pkg install xh` |
28| Linux & macOS | Nixpkgs | `nix-env -iA nixpkgs.xh`|
29| Linux & macOS | Homebrew | `brew install xh` |
30| macOS | MacPorts | `sudo port install xh` |
31| Windows | Scoop | `scoop install xh` |
32
33\* Make sure that you have Rust 1.46 or later installed
34
35\*\* You will need to add the apt repository from https://apt.cli.rs/
36
37[Huber]: https://github.com/innobead/huber#installing-huber
38
39
40### via pre-built binaries
41The [release page](https://github.com/ducaale/xh/releases) contains prebuilt binaries for Linux, macOS and Windows.
42
43## Usage
44```
45USAGE:
46 xh [OPTIONS] <[METHOD] URL> [--] [REQUEST_ITEM]...
47
48OPTIONS:
49 -j, --json (default) Serialize data items from the command line as a JSON object
50 -f, --form Serialize data items from the command line as form fields
51 -m, --multipart Like --form, but force a multipart/form-data request even without files
52 --pretty <STYLE> Controls output processing [possible values: all, colors, format, none]
53 -s, --style <THEME> Output coloring style [possible values: auto, solarized, monokai]
54 --response-charset <ENCODING> Override the response encoding for terminal display purposes
55 --response-mime <MIME_TYPE> Override the response mime type for coloring and formatting for the terminal
56 -p, --print <FORMAT> String specifying what the output should contain
57 -h, --headers Print only the response headers, shortcut for --print=h
58 -b, --body Print only the response body, Shortcut for --print=b
59 -v, --verbose Print the whole request as well as the response
60 --all Show any intermediary requests/responses while following redirects with --follow
61 -P, --history-print <FORMAT> The same as --print but applies only to intermediary requests/responses
62 -q, --quiet Do not print to stdout or stderr
63 -S, --stream Always stream the response body
64 -o, --output <FILE> Save output to FILE instead of stdout
65 -d, --download Download the body to a file instead of printing it
66 -c, --continue Resume an interrupted download. Requires --download and --output
67 --session <FILE> Create, or reuse and update a session
68 --session-read-only <FILE> Create or read a session without updating it form the request/response exchange
69 -A, --auth-type <auth-type> Specify the auth mechanism [possible values: basic, bearer, digest]
70 -a, --auth <USER[:PASS] | TOKEN> Authenticate as USER with PASS or with TOKEN
71 --ignore-netrc Do not use credentials from .netrc
72 --offline Construct HTTP requests without sending them anywhere
73 --check-status (default) Exit with an error status code if the server replies with an error
74 -F, --follow Do follow redirects
75 --max-redirects <NUM> Number of redirects to follow, only respected if `follow` is set
76 --timeout <SEC> Connection timeout of the request
77 --proxy <PROTOCOL:URL>... Use a proxy for a protocol. For example: `--proxy https:http://proxy.host:8080`
78 --verify <VERIFY> If "no", skip SSL verification. If a file path, use it as a CA bundle
79 --cert <FILE> Use a client side certificate for SSL
80 --cert-key <FILE> A private key file to use with --cert
81 --ssl <VERSION> Force a particular TLS version [possible values: auto, ssl2.3, tls1, tls1.1, tls1.2, tls1.3]
82 --native-tls Use the system TLS library instead of rustls (if enabled at compile time)
83 --https Make HTTPS requests if not specified in the URL
84 --http-version <VERSION> HTTP version to use [possible values: 1, 1.0, 1.1, 2]
85 -I, --ignore-stdin Do not attempt to read stdin
86 --curl Print a translation to a `curl` command
87 --curl-long Use the long versions of curl's flags
88 --help Prints help information
89 -V, --version Prints version information
90
91ARGS:
92 <[METHOD] URL> The request URL, preceded by an optional HTTP method
93 <REQUEST_ITEM>... Optional key-value pairs to be included in the request
94
95Each option can be reset with a --no-OPTION argument.
96```
97
98Run `xh help` for more detailed information.
99
100### Request Items
101
102`xh` uses [HTTPie's request-item syntax](https://httpie.io/docs#request-items) to set headers, request body, query string, etc.
103
104- `=`/`:=` for setting the request body's JSON or form fields (`=` for strings and `:=` for other JSON types).
105- `==` for adding query strings.
106- `@` for including files in multipart requests e.g `picture@hello.jpg` or `picture@hello.jpg;type=image/jpeg;filename=goodbye.jpg`.
107- `:` for adding or removing headers e.g `connection:keep-alive` or `connection:`.
108- `;` for including headers with empty values e.g `header-without-value;`.
109- `=@`/`:=@` for setting the request body's JSON or form fields from a file (`=@` for strings and `:=@` for other JSON types).
110
111The request body can also be read from standard input, or from a file using `@filename`.
112
113### Shorthand form for URLs
114
115Similar to HTTPie, specifying the scheme portion of the request URL is optional. `xh` also supports
116omitting `localhost` from the URL as long it starts with colon plus an optional port number.
117
118```sh
119xh http://localhost:3000/users # resolves to http://localhost:3000/users
120xh localhost:3000/users # resolves to http://localhost:3000/users
121xh :3000/users # resolves to http://localhost:3000/users
122xh :/users # resolves to http://localhost:80/users
123xh example.com # resolves to http://example.com
124```
125
126### Making HTTPS requests by default
127
128`xh` will default to HTTPS scheme if the binary name is one of `xhs`, `https`, or `xhttps`. If you have installed `xh`
129via a package manager, both `xh` and `xhs` should be available by default. Otherwise, you need to create one like this:
130
131```sh
132cd /path/to/xh && ln -s ./xh ./xhs
133xh httpbin.org/get # resolves to http://httpbin.org/get
134xhs httpbin.org/get # resolves to https://httpbin.org/get
135```
136
137### Strict compatibility mode
138
139If `xh` is invoked as `http` or `https` (by renaming the binary), or if the `XH_HTTPIE_COMPAT_MODE` environment variable is set,
140it will run in HTTPie compatibility mode. The only current difference is that `--check-status` is not enabled by default.
141
142## Examples
143
144```sh
145# Send a GET request
146xh httpbin.org/json
147
148# Send a POST request with body {"name": "ahmed", "age": 24}
149xh httpbin.org/post name=ahmed age:=24
150
151# Send a GET request with querystring id=5&sort=true
152xh get httpbin.org/json id==5 sort==true
153
154# Send a GET request and include a header named x-api-key with value 12345
155xh get httpbin.org/json x-api-key:12345
156
157# Send a PUT request and pipe the result to less
158xh put httpbin.org/put id:=49 age:=25 | less
159
160# Download and save to res.json
161xh -d httpbin.org/json -o res.json
162
163# Make a request with a custom user agent
164xh httpbin.org/get user-agent:foobar
165```
166
167## How xh compares to HTTPie
168
169### Advantages
170
171- Improved startup speed.
172- Available as a single statically linked binary that's easy to install and carry around.
173- HTTP/2 support.
174- Builtin translation to curl commands with the `--curl` flag.
175- Short, cheatsheet-style output from `--help`. (For longer output, pass `help`.)
176
177### Disadvantages
178
179- Not all of HTTPie's features are implemented. ([#4](https://github.com/ducaale/xh/issues/4))
180- Header names are not case-sensitive.
181- No plugin system.
182- General immaturity. HTTPie is old and well-tested.
183- Worse documentation.
184
185### Other differences
186
187- `--check-status` is enabled unless `xh` is being used in
188 [strict compatibility mode](https://github.com/ducaale/xh#strict-compatibility-mode).
189- `rustls` is used by default instead of the system's TLS library. (If enabled at compile time, the `--native-tls` flag can be used.)
190- JSON keys are not sorted.
191- Formatted output is always UTF-8.
192
193## Similar or related Projects
194
195- [curlie](https://github.com/rs/curlie) - frontend to cURL that adds the ease of use of httpie
196- [httpie-go](https://github.com/nojima/httpie-go) - httpie-like HTTP client written in Go
197- [curl2httpie](https://github.com/dcb9/curl2httpie) - convert command arguments between cURL and HTTPie
198
){kind=link}
){kind=link}
