XH(1) User Commands XH(1)

xh - Friendly and fast tool for sending HTTP requests

xh [OPTIONS] [METHOD] URL [--] [REQUEST_ITEM ...]

xh is an HTTP client with a friendly command line interface. It strives to have readable output and easy-to-use options.

xh is mostly compatible with HTTPie: see http(1).

The --curl option can be used to print a curl(1) translation of the command instead of sending a request.

[METHOD]
The HTTP method to use for the request.

This defaults to GET, or to POST if the request contains a body.

The URL to request.

The URL scheme defaults to "http://" normally, or "https://" if the program is invoked as "xhs".

A leading colon works as shorthand for localhost. ":8000" is equivalent to "localhost:8000", and ":/path" is equivalent to "localhost/path".

[REQUEST_ITEM ...]
Optional key-value pairs to be included in the request.

The separator is used to determine the type:

Add a query string to the URL.
Add a JSON property (--json) or form field (--form) to the request body.
Add a field with a literal JSON value to the request body.

Example: "numbers:=[1,2,3] enabled:=true"

Upload a file (requires --form or --multipart).

To set the filename and mimetype, ";type=" and ";filename=" can be used respectively.

Example: "pfp@ra.jpg;type=image/jpeg;filename=profile.jpg"

@filename
Use a file as the request body.
Add a header, e.g. "user-agent:foobar"
Unset a header, e.g. "connection:"
Add a header with an empty value.

An "@" prefix can be used to read a value from a file. For example: "x-api-key:@api-key.txt".

A backslash can be used to escape special characters, e.g. "weird\:key=value".

To construct a complex JSON object, the REQUEST_ITEM's key can be set to a JSON path instead of a field name. For more information on this syntax, refer to https://httpie.io/docs/cli/nested-json.

Each --OPTION can be reset with a --no-OPTION argument.

(default) Serialize data items from the command line as a JSON object.

Overrides both --form and --multipart.

Serialize data items from the command line as form fields.

Overrides both --json and --multipart.

Like --form, but force a multipart/form-data request even without files.

Overrides both --json and --form.

Pass raw request data without extra processing.
Controls output processing. Possible values are:


all (default) Enable both coloring and formatting
colors Apply syntax highlighting to output
format Pretty-print json and sort headers
none Disable both coloring and formatting

Defaults to "format" if the NO_COLOR env is set and to "none" if stdout is not tty.

Set output formatting options. Supported option are:


json.indent:<NUM>
json.format:<true|false>
headers.sort:<true|false>

Example: --format-options=json.indent:2,headers.sort:false.

Output coloring style.

[possible values: auto, solarized, monokai, fruity]

Override the response encoding for terminal display purposes.

Example: --response-charset=latin1.

Override the response mime type for coloring and formatting for the terminal.

Example: --response-mime=application/json.

String specifying what the output should contain


'H' request headers
'B' request body
'h' response headers
'b' response body
'm' response metadata

Example: --print=Hb.

Print only the response headers. Shortcut for --print=h.
Print only the response body. Shortcut for --print=b.
Print only the response metadata. Shortcut for --print=m.
Print the whole request as well as the response.

Additionally, this enables --all for printing intermediary requests/responses while following redirects.

Using verbose twice i.e. -vv will print the response metadata as well.

Equivalent to --print=HhBb --all.

Print full error stack traces and debug log messages.

Logging can be configured in more detail using the `$RUST_LOG` environment variable. Set `RUST_LOG=trace` to show even more messages. See https://docs.rs/env_logger/0.11.3/env_logger/#enabling-logging.

Show any intermediary requests/responses while following redirects with --follow.
The same as --print but applies only to intermediary requests/responses.
Do not print to stdout or stderr.

Using quiet twice i.e. -qq will suppress warnings as well.

Always stream the response body.
Save output to FILE instead of stdout.
Download the body to a file instead of printing it.

The Accept-Encoding header is set to identify and any redirects will be followed.

Resume an interrupted download. Requires --download and --output.
Create, or reuse and update a session.

Within a session, custom headers, auth credentials, as well as any cookies sent by the server persist between requests.

Create or read a session without updating it form the request/response exchange.
Specify the auth mechanism.

[possible values: basic, bearer]

Authenticate as USER with PASS (-A basic|digest) or with TOKEN (-A bearer).

PASS will be prompted if missing. Use a trailing colon (i.e. "USER:") to authenticate with just a username.

TOKEN is expected if --auth-type=bearer.

Do not use credentials from .netrc.
Construct HTTP requests without sending them anywhere.
(default) Exit with an error status code if the server replies with an error.

The exit code will be 4 on 4xx (Client Error), 5 on 5xx (Server Error), or 3 on 3xx (Redirect) if --follow isn't set.

If stdout is redirected then a warning is written to stderr.

Do follow redirects.
Number of redirects to follow. Only respected if --follow is used.
Connection timeout of the request.

The default value is "0", i.e., there is no timeout limit.

Use a proxy for a protocol. For example: --proxy https:http://proxy.host:8080.

PROTOCOL can be "http", "https" or "all".

If your proxy requires credentials, put them in the URL, like so: --proxy http:socks5://user:password@proxy.host:8000.

You can specify proxies for multiple protocols by repeating this option.

The environment variables "http_proxy" and "https_proxy" can also be used, but are completely ignored if --proxy is passed.

If "no", skip SSL verification. If a file path, use it as a CA bundle.

Specifying a CA bundle will disable the system's built-in root certificates.

"false" instead of "no" also works. The default is "yes" ("true").

Use a client side certificate for SSL.
A private key file to use with --cert.

Only necessary if the private key is not contained in the cert file.

Force a particular TLS version.

"auto" gives the default behavior of negotiating a version with the server.

[possible values: auto, tls1, tls1.1, tls1.2, tls1.3]

Make HTTPS requests if not specified in the URL.
HTTP version to use.

[possible values: 1.0, 1.1, 2, 2-prior-knowledge]

Override DNS resolution for specific domain to a custom IP.

You can override multiple domains by repeating this option.

Example: --resolve=example.com:127.0.0.1.

Bind to a local IP address. (Debian: interface support is disabled due to unavailable dependency.)

Example: --interface=192.168.0.2.

-4, --ipv4
Resolve hostname to ipv4 addresses only.
-6, --ipv6
Resolve hostname to ipv6 addresses only.
Do not attempt to read stdin.

This disables the default behaviour of reading the request body from stdin when a redirected input is detected.

It is recommended to pass this flag when using xh for scripting purposes. For more information, refer to https://httpie.io/docs/cli/best-practices.

Print a translation to a curl command.

For translating the other way, try https://curl2httpie.online/.

Use the long versions of curl's flags.
Generate shell completions or man pages. Possible values are:


complete-bash
complete-elvish
complete-fish
//complete-nushell (Debian: not packaged)
complete-powershell
complete-zsh
man

Example: xh --generate=complete-bash > xh.bash.

Print help.
Print version.

0
Successful program execution.
1
Usage, syntax or network error.
2
Request timeout.
3
Unexpected HTTP 3xx Redirection.
4
HTTP 4xx Client Error.
5
HTTP 5xx Server Error.
6
Too many redirects.

Specifies where to look for config.json and named session data. The default is ~/.config/xh for Linux/macOS and %APPDATA%\xh for Windows.
Enables the HTTPie Compatibility Mode. The only current difference is that --check-status is not enabled by default. An alternative to setting this environment variable is to rename the binary to either http or https.
Sets a custom CA bundle path.
Sets the proxy server to use for HTTP.
Sets the proxy server to use for HTTPS.
List of comma-separated hosts for which to ignore the other proxy environment variables. "*" matches all host names.
Location of the .netrc file.
Disables output coloring. See <https://no-color.org>
Configure low-level debug messages. See <https://docs.rs/env_logger/0.11.3/env_logger/#enabling-logging>

~/.config/xh/config.json
xh configuration file. The only configurable option is "default_options" which is a list of default shell arguments that gets passed to xh. Example:

{ "default_options": ["--native-tls", "--style=solarized"] }
~/.netrc, ~/_netrc
Auto-login information file.
~/.config/xh/sessions
Session data directory grouped by domain and port number.

Send a GET request.
Send a POST request with body {"name": "ahmed", "age": 24}.
Send a GET request to http://httpbin.org/json?id=5&sort=true.
Send a GET request and include a header named X-Api-Key with value 12345.
Send a POST request with body read from stdin.
Send a PUT request and pipe the result to less.
Download and save to res.json.
Make a request with a custom user agent.
Make an HTTPS request to https://example.com.

xh's Github issues <https://github.com/ducaale/xh/issues>

curl(1), http(1)

HTTPie's online documentation <https://httpie.io/docs/cli>

2025-01-20 0.23.1