xh.1.md

May 8, 2026 ยท View on GitHub

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>
    • xml.indent:<NUM>
    • xml.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 identity 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 from 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 all, http or https.

    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 ALL_PROXY, 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, 3-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.

  • --unix-socket=FILE: Connect using a Unix domain socket.

    Example: xh :/index.html --unix-socket=/var/run/temp.sock.

  • -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: Generate completions for bash
    • complete-elvish: Generate completions for elvish
    • complete-fish: Generage completions for fish
    • complete-nushell: Generate completions for nushell
    • complete-powershell: Generate completions for powershell
    • complete-zsh: Generate completions for zsh
    • man: Generate manual page in roff format
    • man-markdown: Generate manual page in markdown format

    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.

  • ALL_PROXY=[protocol://]<host>[:port]: Sets the proxy server for all requests (unless overridden for a specific protocol).

  • 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

Send a GET request:

xh httpbin.org/json

Send a POST request with body {"name": "ahmed", "age": 24}:

xh httpbin.org/post name=ahmed age:=24

Send a GET request to http://httpbin.org/json?id=5&sort=true:

xh get httpbin.org/json id==5 sort==true

Send a GET request and include a header named X-Api-Key with value 12345:

xh get Ihttpbin.org/json x-api-key:12345

Send a POST request with body read from stdin:

echo "[1, 2, 3]" | xh post httpbin.org/post

Send a PUT request and pipe the result to less:

xh put httpbin.org/put id:=49 age:=25 | less

Download and save to res.json:

xh -d httpbin.org/json -o res.json

Make a request with a custom user agent:

xh httpbin.org/get user-agent:foobar

Make an HTTPS request to https://example.com:

xhs 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