LinuxCommandLibrary

xh

Execute commands across multiple hosts

TLDR

Send a GET request (shows response headers and content)

$ xh [https://postman-echo.com/get]
copy

Send a POST request with a JSON body (key-value pairs are added to a top-level JSON object - e.g. {"name": "john", "age": 25})
$ xh post [https://postman-echo.com/post] [name=john] [age=25]
copy

Send a GET request with query parameters (e.g. https://postman-echo.com/response-headers?foo1=bar1&foo2=bar2)
$ xh get [https://postman-echo.com/response-headers] [foo1==bar1] [foo2==bar2]
copy

Send a GET request with a custom header
$ xh get [https://postman-echo.com] [header-name:header-value]
copy

Make a GET request and save the response body to a file
$ xh [[-d|--download]] [https://example.com] [[-o|--output]] [path/to/file]
copy

Construct a request but do not send it (similar to a dry-run)
$ xh --offline [get|delete|...] [https://example.com]
copy

Show equivalent curl command (this will not send any request)
$ xh --[curl|curl-long] [--follow --verbose get https://example.com user-agent:curl]
copy

SYNOPSIS

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

Where REQUEST_ITEM can be:
KEY=VALUE (form/data), KEY:=VALUE (JSON data), KEY==VALUE (query parameter), KEY:VALUE (header), @FILE (request body from file), KEY@FILE (file upload), KEY=@FILE (inline file content).

PARAMETERS

-v, --verbose
    Print the whole request as well as the response.

-h, --headers
    Print only the response headers.

-b, --body
    Print only the response body.

-j, --json
    Force data items to be serialized as JSON (default for POST/PUT/PATCH).

-f, --form
    Force data items to be serialized as application/x-www-form-urlencoded.

-F, --multipart
    Force data items to be serialized as multipart/form-data.

-x, --pretty {all|colors|format|none}
    Controls output formatting and syntax highlighting.

-o, --output FILE
    Save the response body to a specified file.

-d, --download
    Download the response to a file, showing progress.

-a, --auth USER:PASS
    Provide credentials for HTTP basic authentication.

-A, --auth-bearer TOKEN
    Provide a bearer token for authentication.

-k, --insecure
    Allow insecure (unverified) SSL/TLS connections.

--follow
    Follow HTTP 3xx redirects.

-e, --error
    Exit with a non-zero status code on HTTP 4xx or 5xx responses.

DESCRIPTION

xh is a powerful and intuitive command-line HTTP client, designed as a modern, user-friendly alternative to curl and HTTPie. It prioritizes simplicity, clear output, and convenience, making it effortless to send various HTTP requests and inspect responses. xh intelligently handles common tasks such as JSON formatting, syntax highlighting, and content type detection. It supports a wide range of HTTP methods (GET, POST, PUT, DELETE, etc.), custom headers, query parameters, form data, file uploads, and authentication. Its syntax is highly readable and often requires less typing for common operations. Built in Rust, it ensures speed and reliability, making it an excellent tool for API testing, web development debugging, and general interaction with web services directly from the terminal.

CAVEATS

xh is a powerful and generally reliable tool, but users should be aware of a few aspects. While highly feature-rich for most use cases, it might not offer the same exhaustive range of low-level control and obscure options as curl, which has accumulated decades of specialized features. Being a relatively newer utility, xh may not be pre-installed on all Linux distributions, especially older ones, requiring manual installation via package managers or compiling from source. Additionally, its behavior concerning SSL/TLS might depend on the underlying system's certificate stores or specific build configurations.

REQUEST ITEM SYNTAX

xh introduces a highly intuitive syntax for constructing HTTP requests. Key-value pairs are used to specify various parts of the request: KEY=VALUE for form data or request body (defaulting to JSON for POST/PUT), KEY:=VALUE to force JSON data, KEY==VALUE for URL query parameters, and KEY:VALUE for custom HTTP headers. It also supports sending raw request bodies from files (@FILE) or uploading files as multipart form data (KEY@FILE).

INTELLIGENT OUTPUT FORMATTING

One of xh's standout features is its intelligent and visually appealing output. It automatically detects and pretty-prints JSON and HTML responses, applying syntax highlighting for improved readability. This makes debugging APIs and inspecting web content directly in the terminal significantly more pleasant and efficient compared to tools that simply dump raw response bodies.

HISTORY

xh emerged as a modern spiritual successor to HTTPie, a popular command-line HTTP client. Its development, primarily in Rust, began with the aim of providing a faster, more robust, and equally, if not more, user-friendly alternative. While curl has been the industry standard for decades, its syntax can be verbose and complex for simple tasks. HTTPie simplified this, and xh built upon that simplification, focusing on performance advantages offered by Rust while maintaining or enhancing the intuitive user experience, especially regarding automatic JSON handling and syntax highlighting. It has gained popularity quickly in the developer community for its efficiency and ease of use.

SEE ALSO

curl(1), http(1), wget(1)

Copied to clipboard