Man page - xh(1)

Packages contains this manual

Package:  xh
apt-get install xh

Manuals in package:
• xhs(1)
• xh(1)
Documentations in package:
• xh

Manual

XH

NAME
SYNOPSIS
DESCRIPTION
POSITIONAL ARGUMENTS
OPTIONS
EXIT STATUS
ENVIRONMENT
FILES
EXAMPLES
REPORTING BUGS
SEE ALSO

---

NAME

xh - Friendly and fast tool for sending HTTP requests

SYNOPSIS

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

DESCRIPTION

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.

POSITIONAL ARGUMENTS

[ 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: "pfp@ra.jpg;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.

OPTIONS

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.

--debug

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.

--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.

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

-S , --stream

Always stream the response body.

-x , --compress

Content compressed (encoded) with Deflate algorithm.

The Content-Encoding header is set to deflate.

Compression is skipped if it appears that compression ratio is negative. Compression can be forced by repeating this option.

Note: Compression cannot be used if the Content-Encoding request header is present.

-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: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.

--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]

--https

Make HTTPS requests if not specified in the URL.

--http-version = VERSION

HTTP version to use.

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

--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.

--generate = KIND

Generate shell completions or man pages. Possible values are:

complete-bash
complete-elvish
complete-fish
complete-powershell
complete-zsh
man

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

--help

Print help.

-V , --version

Print version.

EXIT STATUS

	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.

ENVIRONMENT

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>

RUST_LOG

Configure low-level debug messages. See <https://docs.rs/env_logger/0.11.3/env_logger/#enabling-logging>

FILES

˜/.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.

EXAMPLES

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.

REPORTING BUGS

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

SEE ALSO

curl (1), http (1)

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

---