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.
|
URL |
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:
key==value
Add a query string to the URL.
key=value
Add a JSON property (−−json) or form field (−−form) to the request body.
key:=value
Add a field with a literal JSON value to the request body.
Example: "numbers:=[1,2,3] enabled:=true"
key@filename
Upload a file (requires −−form or −−multipart).
To set the filename and mimetype, ";type=" and ";filename=" can be used respectively.
Example: "[email protected];type=image/jpeg;filename=profile.jpg"
@filename
Use a file as the request body.
header:value
Add a header, e.g. "user−agent:foobar"
header:
Unset a header, e.g. "connection:"
header;
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.
−j, −−json
(default) Serialize data items from the command line as a JSON object.
Overrides both −−form and −−multipart.
−f, −−form
Serialize data items from the command line as form fields.
Overrides both −−json and −−multipart.
−−multipart
Like −−form, but force a multipart/form−data request even without files.
Overrides both −−json and −−form.
−−raw=RAW
Pass raw request data without extra processing.
−−pretty=STYLE
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.
−−format−options=FORMAT_OPTIONS
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.
−s, −−style=THEME
Output coloring style.
[possible values: auto, solarized, monokai, fruity]
−−response−charset=ENCODING
Override the response encoding for terminal display purposes.
Example: −−response−charset=latin1.
−−response−mime=MIME_TYPE
Override the response mime type for coloring and formatting for the terminal.
Example: −−response−mime=application/json.
−p, −−print=FORMAT
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.
−h, −−headers
Print only the response headers. Shortcut for −−print=h.
−b, −−body
Print only the response body. Shortcut for −−print=b.
−m, −−meta
Print only the response metadata. Shortcut for −−print=m.
−v, −−verbose
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.
−−all
Show any intermediary requests/responses while following redirects with −−follow.
−P, −−history−print=FORMAT
The same as −−print but applies only to intermediary requests/responses.
−q, −−quiet
Do not print to stdout or stderr.
−S, −−stream
Always stream the response body.
−o, −−output=FILE
Save output to FILE instead of stdout.
−d, −−download
Download the body to a file instead of printing it.
The Accept−Encoding header is set to identify and any redirects will be followed.
−c, −−continue
Resume an interrupted download. Requires −−download and −−output.
−−session=FILE
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.
−−session−read−only=FILE
Create or read a session without updating it form the request/response exchange.
−A, −−auth−type=AUTH_TYPE
Specify the auth mechanism.
[possible values: basic, bearer, digest]
−a, −−auth=USER[:PASS] | TOKEN
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.
−−ignore−netrc
Do not use credentials from .netrc.
−−offline
Construct HTTP requests without sending them anywhere.
−−check−status
(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.
−F, −−follow
Do follow redirects.
−−max−redirects=NUM
Number of redirects to follow. Only respected if −−follow is used.
−−timeout=SEC
Connection timeout of the request.
The default value is "0", i.e., there is no timeout limit.
−−proxy=PROTOCOL:URL
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:[email protected]: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.
−−verify=VERIFY
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").
−−cert=FILE
Use a client side certificate for SSL.
−−cert−key=FILE
A private key file to use with −−cert.
Only necessary if the private key is not contained in the cert file.
−−ssl=VERSION
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]
−−native−tls
Use the system TLS library instead of rustls (if enabled at compile time).
−−https
Make HTTPS requests if not specified in the URL.
−−http−version=VERSION
HTTP version to use.
[possible values: 1.0, 1.1, 2]
−−resolve=HOST:ADDRESS
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.
−−interface=NAME
Bind to a network interface or local IP address.
Example: −−interface=eth0 −−interface=192.168.0.2.
−4, −−ipv4
Resolve hostname to ipv4 addresses only.
−6, −−ipv6
Resolve hostname to ipv6 addresses only.
−I, −−ignore−stdin
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.
−−curl
Print a translation to a curl command.
For translating the other way, try https://curl2httpie.online/.
−−curl−long
Use the long versions of curl’s flags.
−−help
Print help.
−V, −−version
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. |
XH_CONFIG_DIR
Specifies where to look for config.json and named session data. The default is ˜/.config/xh for Linux/macOS and %APPDATA%\xh for Windows.
XH_HTTPIE_COMPAT_MODE
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.
REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE
Sets a custom CA bundle path.
http_proxy=[protocol://]<host>[:port]
Sets the proxy server to use for HTTP.
HTTPS_PROXY=[protocol://]<host>[:port]
Sets the proxy server to use for HTTPS.
NO_PROXY
List of comma-separated hosts for which to ignore the other proxy environment variables. "*" matches all host names.
NETRC
Location of the .netrc file.
NO_COLOR
Disables output coloring. See <https://no-color.org>
˜/.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.
xh httpbin.org/json
Send a GET request.
xh httpbin.org/post name=ahmed age:=24
Send a POST request with body {"name": "ahmed", "age": 24}.
xh get httpbin.org/json id==5 sort==true
Send a GET request to http://httpbin.org/json?id=5&sort=true.
xh get httpbin.org/json x-api-key:12345
Send a GET request and include a header named X-Api-Key with value 12345.
echo "[1, 2, 3]" | xh post httpbin.org/post
Send a POST request with body read from stdin.
xh put httpbin.org/put id:=49 age:=25 | less
Send a PUT request and pipe the result to less.
xh -d httpbin.org/json -o res.json
Download and save to res.json.
xh httpbin.org/get user-agent:foobar
Make a request with a custom user agent.
xhs example.com
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>