xh Documentation

xh is designed as a faster, single-binary alternative to HTTPie.

Advantages of xh:

• Improved startup speed.
• Single statically linked binary for easy portability.
• Native HTTP/2 support.
• Built-in translation to cURL commands using the --curl flag.
• Concise, cheatsheet-style --help output (use help for detailed documentation).

Disadvantages of xh:

• Fewer features than HTTPie.
• No plugin system.
• Less mature/tested than HTTPie.
• Less extensive documentation.

You can omit the scheme (http/https) and use shorthand for localhost:

• :8000 is equivalent to localhost:8000.
• :/path is equivalent to localhost/path.
• ://example.com allows quick conversion of a full URL into an xh command.

xh :3000/users                 # resolves to http://localhost:3000/users
xh :/users                      # resolves to http://localhost:80/users
xh ://example.com              # resolves to http://example.com

The basic syntax for xh is:

xh [OPTIONS] <[METHOD] URL> [REQUEST_ITEM]...

Common Usage Examples

GET request:

xh httpbin.org/json

POST request with JSON body: Use = for strings and := for other JSON types (numbers, booleans, objects).

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

GET request with query strings: Use == to add query parameters.

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

Adding Headers: Use : to add a header.

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

Downloading a file:

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

xh defaults to HTTPS if the binary is named xhs, https, or xhttps. If your package manager didn't provide these, you can create a symlink:

cd /path/to/xh && ln -s ./xh ./xhs
xhs httpbin.org/get  # resolves to https://httpbin.org/get

To make an HTTPS request by default, use the xhs binary instead of xh.

xhs example.com

You can configure xh using a configuration file located at ~/.config/xh/config.json. The only supported configuration option is default_options, which accepts a list of default shell arguments that are automatically passed to every xh command.

Other relevant files include:

• ~/.netrc or ~/_netrc: Used for auto-login information.
• ~/.config/xh/sessions: Directory where session data is stored, grouped by domain and port.

{
  "default_options": ["--native-tls", "--style=solarized"]
}

Use xh to send HTTP requests from the command line. The basic syntax is:

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

• Method: Defaults to GET, or POST if a body is present.
• URL: The target URL. Defaults to http:// unless using the xhs binary (which defaults to https://).
• Shorthand for localhost: Use a leading colon (e.g., :8000 for localhost:8000).
• Reading from files: Prefix a value with @ to read it from a file (e.g., x-api-key:@api-key.txt).

When providing arguments after the URL, xh uses special separators to determine how to include data:

Example of complex JSON: numbers:=[1,2,3] enabled:=true

The xh tool can translate its command-line arguments into a curl command. This is useful for generating standard curl requests from xh syntax. The translation logic handles headers, authentication, request bodies (JSON, form, multipart), and various HTTP options.

Note that some xh features (like --pretty, --style, or specific signature components) do not have direct curl equivalents and will be ignored with a warning printed to stderr.

You can send POST requests with JSON bodies using shorthand syntax for different types of values:

• key=value: Sets a string value.
• key:=value: Sets a JSON type (number, boolean, etc.).
• key==value: Sets a query parameter.

Example of sending a POST request with a JSON body {"name": "ahmed", "age": 24}:

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