XH(1) User Commands XH(1) 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: json.format: headers.sort: 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: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] --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, 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. --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://][:port] Sets the proxy server to use for HTTP. HTTPS_PROXY=[protocol://][: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 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 SEE ALSO curl(1), http(1) HTTPie's online documentation 0.22.0 2024-04-12 XH(1)