### Install xh via Winget (Windows)

Source: https://github.com/ducaale/xh/blob/master/README.md

Install xh on Windows using Winget.

```bash
winget add ducaale.xh
```

--------------------------------

### Install xh via Scoop (Windows)

Source: https://github.com/ducaale/xh/blob/master/README.md

Install xh on Windows using Scoop.

```bash
scoop install xh
```

--------------------------------

### Common xh Examples

Source: https://github.com/ducaale/xh/blob/master/_autodocs/00-index.md

Illustrates various common use cases for xh, including GET and POST requests, adding headers, authentication, downloading files, following redirects, using sessions, offline mode, and showing equivalent curl commands.

```bash
# GET request
xh example.com
```

```bash
# POST with JSON body
xh POST example.com name=alice age:=25
```

```bash
# With headers
xh example.com x-api-key:secret authorization:@token.txt
```

```bash
# With authentication
xh -a user:password example.com
xh --bearer "$TOKEN" example.com
```

```bash
# Download file
xh -d example.com/data.csv
```

```bash
# Follow redirects
xh --follow example.com/old-path
```

```bash
# Use session for persistence
xh --session=myapi -a admin:secret example.com
xh --session=myapi example.com/api/users  # Auth auto-reused
```

```bash
# Offline mode (construct request without sending)
xh --offline POST example.com name=value
```

```bash
# Show equivalent curl command
xh --curl example.com
```

--------------------------------

### Install xh via pkgin (NetBSD)

Source: https://github.com/ducaale/xh/blob/master/README.md

Install xh on NetBSD using the pkgin package manager.

```bash
pkgin install xh
```

--------------------------------

### Auth::from_str Examples

Source: https://github.com/ducaale/xh/blob/master/_autodocs/03-authentication.md

Examples demonstrating how to use Auth::from_str for Basic and Bearer authentication.

```rust
// Basic auth with password
Auth::from_str("user:pass", AuthType::Basic, "example.com")?
// Basic auth with prompt
Auth::from_str("user", AuthType::Basic, "example.com")?
// Bearer token
Auth::from_str("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", AuthType::Bearer, _)?
```

--------------------------------

### Install xh via Chocolatey (Windows)

Source: https://github.com/ducaale/xh/blob/master/README.md

Install xh on Windows using Chocolatey.

```bash
choco install xh
```

--------------------------------

### Install xh via Nixpkgs (Linux & macOS)

Source: https://github.com/ducaale/xh/blob/master/README.md

Install xh on Linux and macOS using Nixpkgs.

```bash
nix-env -iA nixpkgs.xh
```

--------------------------------

### xh Configuration File Example

Source: https://github.com/ducaale/xh/blob/master/doc/md-template.md

Example of the xh configuration file (config.json) specifying default options to be passed to xh.

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

--------------------------------

### Install xh via Flox (Linux & macOS)

Source: https://github.com/ducaale/xh/blob/master/README.md

Install xh on Linux and macOS using Flox.

```bash
flox install xh
```

--------------------------------

### Install xh via Homebrew (Linux & macOS)

Source: https://github.com/ducaale/xh/blob/master/README.md

Install xh on Linux and macOS using Homebrew.

```bash
brew install xh
```

--------------------------------

### Install xh via Huber

Source: https://github.com/ducaale/xh/blob/master/README.md

Install xh using the Huber package manager.

```bash
huber install xh
```

--------------------------------

### Install xh via Hermit (Linux & macOS)

Source: https://github.com/ducaale/xh/blob/master/README.md

Install xh on Linux and macOS using Hermit.

```bash
hermit install xh
```

--------------------------------

### CLI examples for format options

Source: https://github.com/ducaale/xh/blob/master/_autodocs/05-printing-formatting.md

Demonstrates how to use the --format-options flag to customize JSON indentation, JSON formatting, and header sorting.

```bash
xh --format-options=json.indent:2 example.com        # 2-space JSON indent
```

```bash
xh --format-options=json.format:false example.com    # No JSON formatting
```

```bash
xh --format-options=headers.sort:false example.com   # Don't sort headers
```

```bash
xh --format-options=json.indent:2,xml.indent:4 example.com
```

--------------------------------

### Install xh via MacPorts (macOS)

Source: https://github.com/ducaale/xh/blob/master/README.md

Install xh on macOS using MacPorts.

```bash
sudo port install xh
```

--------------------------------

### Install xh via Pacman (Arch Linux)

Source: https://github.com/ducaale/xh/blob/master/README.md

Install xh on Arch Linux using the Pacman package manager.

```bash
pacman -S xh
```

--------------------------------

### Install xh via Powershell (Windows)

Source: https://github.com/ducaale/xh/blob/master/README.md

Use this command to install xh on Windows systems using Powershell.

```powershell
iwr -useb https://raw.githubusercontent.com/ducaale/xh/master/install.ps1 | iex
```

--------------------------------

### Basic Authentication CLI Usage

Source: https://github.com/ducaale/xh/blob/master/_autodocs/03-authentication.md

Examples of how to use Basic Authentication via the xh CLI, including prompting for a password.

```bash
xh -A basic -a user:password example.com
xh -A basic -a user: example.com              # Prompt for password
xh -A basic -a user example.com               # Prompt for password
```

--------------------------------

### Install xh via MMRL (Magisk/KernelSU)

Source: https://github.com/ducaale/xh/blob/master/README.md

Install xh on Android devices with Magisk or KernelSU using the MMRL CLI.

```bash
mmrl install xhhttp
```

--------------------------------

### Using .netrc for Authentication

Source: https://github.com/ducaale/xh/blob/master/_autodocs/03-authentication.md

Provides an example of setting up a .netrc file with credentials for different machines and then using xh to automatically authenticate with those services. This simplifies repeated access to authenticated APIs.

```bash
machine api.github.com
login octocat
password ghp_1234567890abcdef

machine api.example.com
login user
password pass

xh api.github.com/user         # Automatically uses GitHub credentials
xh api.example.com/profile     # Automatically uses example.com credentials
```

--------------------------------

### Send a GET Request with Custom Header

Source: https://github.com/ducaale/xh/blob/master/doc/md-template.md

Include custom headers in a request by specifying 'Header-Name:Value'. This example adds an 'X-Api-Key' header.

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

--------------------------------

### File Not Found Error Example

Source: https://github.com/ducaale/xh/blob/master/_autodocs/07-error-handling.md

Illustrates the error output when a referenced file is not found.

```bash
# File not found
xh example.com photo@missing.jpg
# Error: Failed to open the cert file: No such file or directory
```

--------------------------------

### Install xh via cURL (Linux & macOS)

Source: https://github.com/ducaale/xh/blob/master/README.md

Use this command to install xh on Linux and macOS systems using cURL.

```bash
curl -sfL https://raw.githubusercontent.com/ducaale/xh/master/install.sh | sh
```

--------------------------------

### Install xh via Apt (Debian & Ubuntu)

Source: https://github.com/ducaale/xh/blob/master/README.md

Install xh on Debian and Ubuntu systems using the Apt package manager. Available since Debian 13 and Ubuntu 25.04. Built with native-tls only.

```bash
sudo apt install xh
```

--------------------------------

### Example JSON Configuration for xh

Source: https://github.com/ducaale/xh/blob/master/_autodocs/01-cli-arguments.md

This JSON snippet shows how to configure default options for xh in its configuration file. The `default_options` array is prepended to CLI arguments.

```json
{
  "default_options": [
    "--pretty=colors",
    "--print=hb"
  ]
}
```

--------------------------------

### Configuration System Levels

Source: https://github.com/ducaale/xh/blob/master/_autodocs/08-architecture.md

Outlines the three levels of configuration priority: default (hardcoded), config file, and CLI arguments. Shows an example of config file format.

```json
{
  "default_options": ["--pretty=colors", "--print=hb"]
}
```

--------------------------------

### Install xh via Termux (Android)

Source: https://github.com/ducaale/xh/blob/master/README.md

Install xh on Android using Termux's pkg package manager.

```bash
pkg install xh
```

--------------------------------

### Install xh via Apk (Alpine Linux)

Source: https://github.com/ducaale/xh/blob/master/README.md

Install xh on Alpine Linux using the apk package manager. Note: Built with native-tls only.

```bash
apk add xh
```

--------------------------------

### Response Metadata Example

Source: https://github.com/ducaale/xh/blob/master/_autodocs/05-printing-formatting.md

Illustrates the output format for response metadata, including HTTP status, headers, timing, and size information.

```text
HTTP/1.1 200 OK

    Headers
    -------
    Content-Type: application/json
    Content-Length: 1024
    ...

    Timing
    ------
    Request:       250ms
    Receive:       50ms
    Total:         300ms

    Size
    ----
    Downloaded:    1.5 KB
```

--------------------------------

### Permission Denied Error Example

Source: https://github.com/ducaale/xh/blob/master/_autodocs/07-error-handling.md

Shows the error message when the program lacks the necessary permissions to write to a file.

```bash
# Permission denied
xh -o /root/file.json example.com
# Error: Permission denied (os error 13)
```

--------------------------------

### Install xh via Cargo

Source: https://github.com/ducaale/xh/blob/master/README.md

Install xh using Cargo, the Rust package manager. Requires Rust 1.85 or later.

```bash
cargo install xh --locked
```

--------------------------------

### Example .netrc File Format

Source: https://github.com/ducaale/xh/blob/master/_autodocs/03-authentication.md

Credentials can be stored in a .netrc file for automatic authentication. Ensure the file has 0600 permissions for security.

```plaintext
machine example.com
login username
password secretpassword

machine api.service.io
login another_user
password another_secret
```

--------------------------------

### URL Shorthand Notation Examples

Source: https://github.com/ducaale/xh/blob/master/_autodocs/09-advanced-features.md

xh supports HTTPie-style URL shorthands for convenience, including localhost, default schemes, and clipboard pasting.

```bash
# Colon shorthand for localhost
xh :8000                # http://localhost:8000
xh :8000/api/users      # http://localhost:8000/api/users
xh :/admin              # http://localhost/admin

# No scheme (defaults to http)
xh example.com          # http://example.com
xh example.com/api      # http://example.com/api

# Leading :// (clipboard paste convenience)
xh ://example.com       # http://example.com (useful for pasting)

# Scheme + domain only
xh https://example.com  # https://example.com
```

--------------------------------

### Resume Interrupted Downloads

Source: https://github.com/ducaale/xh/blob/master/_autodocs/09-advanced-features.md

Provides an example command for resuming an interrupted file download using the `--continue` flag.

```bash
# Example command for resuming download (command itself not provided in source)
# xh --download --continue -o large-file.bin example.com/downloads/large
```

--------------------------------

### RequestItem Parsing Examples

Source: https://github.com/ducaale/xh/blob/master/_autodocs/02-request-items.md

Demonstrates parsing various string formats into RequestItem enum variants using the parse::<RequestItem>() method.

```rust
"id==5".parse::<RequestItem>()  // Ok(UrlParam("id", "5"))
```

```rust
"name=alice".parse::<RequestItem>()  // Ok(DataField { key: "name", raw_key: "name", value: "alice" })
```

```rust
"count:=10".parse::<RequestItem>()  // Ok(JsonField("count", Number(10)))
```

```rust
"x-api-key:secret".parse::<RequestItem>()  // Ok(HttpHeader("x-api-key", "secret"))
```

--------------------------------

### Bearer Token Authentication CLI Usage

Source: https://github.com/ducaale/xh/blob/master/_autodocs/03-authentication.md

Examples of how to use Bearer Token Authentication via the xh CLI.

```bash
xh -A bearer -a "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." example.com
xh --bearer "token-string" example.com        # Shorthand
```

--------------------------------

### Pretty-Printing with Custom Settings

Source: https://github.com/ducaale/xh/blob/master/_autodocs/00-index.md

Configures pretty-printing options using `--format-options`. Examples include JSON indentation, disabling header sorting, and applying multiple options simultaneously.

```bash
# JSON with 2-space indentation
xh --format-options=json.indent:2 example.com/api
```

```bash
# Disable header sorting
xh --format-options=headers.sort:false example.com
```

```bash
# Multiple options
xh --format-options=json.indent:2,xml.indent:4,headers.sort:false example.com
```

--------------------------------

### Send a GET Request with Query Parameters

Source: https://github.com/ducaale/xh/blob/master/doc/md-template.md

Specify query parameters for a GET request using the '==' operator. Multiple parameters can be added.

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

--------------------------------

### Example of Option Negation in xh

Source: https://github.com/ducaale/xh/blob/master/_autodocs/01-cli-arguments.md

Demonstrates how to negate an option using the `--no-OPTION` prefix. This is useful when overriding default settings, such as disabling colors after enabling them.

```bash
xh --pretty=colors --no-pretty example.com  # First enables, then disables colors
```

--------------------------------

### xh Network Options

Source: https://github.com/ducaale/xh/blob/master/_autodocs/00-index.md

Provides examples of configuring network-related options such as timeouts, proxies, SSL verification, client certificates, IP version preference, Unix sockets, host resolution, and HTTP version.

```bash
xh --timeout=30 example.com                    # 30 second timeout
xh --proxy=http:socks5://user:pass@host example.com
xh --verify=no example.com                     # Skip SSL verification
xh --cert=client.crt --cert-key=client.key example.com
xh --ipv4 example.com                          # IPv4 only
xh --ipv6 example.com                          # IPv6 only
xh --unix-socket=/var/run/app.sock :/api example.com
xh --resolve=example.com:127.0.0.1 example.com
xh --https example.com                         # Force HTTPS
xh --http-version=2 example.com                # HTTP/2
```

--------------------------------

### Send a GET request with a header

Source: https://github.com/ducaale/xh/blob/master/README.md

Includes a custom header in a GET request using the `header-name:value` syntax.

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

--------------------------------

### Digest Authentication CLI Usage

Source: https://github.com/ducaale/xh/blob/master/_autodocs/03-authentication.md

Examples of how to use Digest Authentication via the xh CLI, including prompting for a password.

```bash
xh -A digest -a user:password example.com
xh -A digest -a user: example.com             # Prompt for password
```

--------------------------------

### Send a GET Request

Source: https://github.com/ducaale/xh/blob/master/doc/md-template.md

Basic usage for sending a GET request to a specified URL. The URL scheme defaults to http://.

```bash
xh httpbin.org/json
```

--------------------------------

### Authentication Error Handling Examples

Source: https://github.com/ducaale/xh/blob/master/_autodocs/03-authentication.md

Illustrates common authentication errors and their causes, such as invalid auth strings, password prompt failures, unauthorized responses (401), and invalid header values. The `--debug` flag can provide more detailed logs.

```bash
xh -a ":::invalid" ...
xh -a user ... < /dev/null
```

--------------------------------

### Authenticate with Bearer Token

Source: https://github.com/ducaale/xh/blob/master/_autodocs/00-index.md

Examples of how to use the `--bearer` option to authenticate requests with a bearer token, either directly from a variable, a file, or a persistent session.

```bash
# From variable
TOKEN="eyJhbGciOi..."
xh --bearer "$TOKEN" api.example.com/data
```

```bash
# From file
xh --bearer "$(cat ~/.tokens/api)" example.com
```

```bash
# With session (token persists)
xh --session=api --bearer "$TOKEN" example.com/users
xh --session=api example.com/posts  # Token auto-reused
```

--------------------------------

### Generate Man Page

Source: https://github.com/ducaale/xh/blob/master/_autodocs/09-advanced-features.md

Generates man pages in roff or markdown format for documentation. The generated man page includes synopsis, description, options, and examples.

```bash
# Generate man page in roff format
xh --generate=man > xh.1
man ./xh.1

# Generate man page in markdown
xh --generate=man-markdown > xh.md
```

```bash
mkdir -p ~/.local/share/man/man1
xh --generate=man > ~/.local/share/man/man1/xh.1
```

--------------------------------

### Session Headers - New Format

Source: https://github.com/ducaale/xh/blob/master/_autodocs/04-sessions.md

Example of the new array-based format for storing headers in an xh session file. This format allows for duplicate header names.

```json
"headers": [
  { "name": "Authorization", "value": "Bearer token" },
  { "name": "X-Custom", "value": "value1" },
  { "name": "X-Custom", "value": "value2" }
]
```

--------------------------------

### Resetting a Session

Source: https://github.com/ducaale/xh/blob/master/_autodocs/04-sessions.md

To reset a session and start fresh, delete the corresponding session file. The next request using that session name will create a new session file.

```bash
# Delete session file to start fresh
rm ~/.xh/sessions/myapi.json

# Next request will create new session
xh --session=myapi example.com
```

--------------------------------

### Access Detailed Help

Source: https://github.com/ducaale/xh/blob/master/README.md

Run 'xh help' or consult the man page for comprehensive usage instructions and detailed information about the xh tool.

```bash
xh help
```

```bash
man xh
```

--------------------------------

### Setting up HTTPS Default

Source: https://github.com/ducaale/xh/blob/master/README.md

Shows how to create a symbolic link to make `xh` default to HTTPS requests when invoked as `xhs`.

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

--------------------------------

### File Upload Syntax with Options

Source: https://github.com/ducaale/xh/blob/master/_autodocs/02-request-items.md

Demonstrates the syntax for uploading a file with optional MIME type and display name parameters.

```bash
xh --form POST example.com \
  name=alice \
  photo@avatar.png \
  doc@report.pdf;type=application/pdf;filename=monthly_report.pdf
```

--------------------------------

### Verbose Output Equivalent

Source: https://github.com/ducaale/xh/blob/master/_autodocs/09-advanced-features.md

Demonstrates an equivalent command using the --print flag for verbose output.

```bash
xh -v example.com
# Equivalent to:
xh --print=HhBb --all example.com
```

--------------------------------

### Try Explicit Authentication

Source: https://github.com/ducaale/xh/blob/master/_autodocs/00-index.md

Demonstrates how to explicitly specify the authentication type and credentials using `-A` and `-a` flags. This can be used to override default authentication methods or troubleshoot issues.

```bash
# Try explicit auth
xh -A basic -a user:password example.com
```

--------------------------------

### Print Version

Source: https://github.com/ducaale/xh/blob/master/README.md

Use the -V or --version flags to display the current version of the xh tool.

```bash
xh -V
```

```bash
xh --version
```

--------------------------------

### Invalid JSON in File Error Example

Source: https://github.com/ducaale/xh/blob/master/_autodocs/07-error-handling.md

Demonstrates the error output when a JSON file used in a request is malformed.

```bash
# Invalid JSON in file
xh example.com config:=@malformed.json
# Error: expected value at line 1 column 5
```

--------------------------------

### Session with Persistent Authentication

Source: https://github.com/ducaale/xh/blob/master/_autodocs/03-authentication.md

Demonstrates how to use sessions to persist authentication credentials across multiple requests. The first request creates the session with credentials, and subsequent requests automatically reuse them.

```bash
# First request: provide credentials and create session
xh --session=myapi -a admin:secret example.com/config

# Subsequent requests: auth automatically used from session
xh --session=myapi example.com/users        # No -a needed
xh --session=myapi example.com/posts        # Auth persists
```

--------------------------------

### xh Formatting Options

Source: https://github.com/ducaale/xh/blob/master/_autodocs/00-index.md

Explains how to control the output formatting, including enabling/disabling colors and pretty-printing, and selecting different color themes.

```bash
xh --pretty=all example.com       # Colors + pretty-print (default)
xh --pretty=colors example.com    # Colors only
xh --pretty=format example.com    # Pretty-print only
xh --pretty=none example.com      # Plain output

xh --format-options=json.indent:2 example.com
xh --format-options=headers.sort:false example.com
xh --style=monokai example.com    # Color theme
```

--------------------------------

### Run Integration Tests

Source: https://github.com/ducaale/xh/blob/master/_autodocs/00-index.md

Commands to execute the project's integration tests. Use `--nocapture` to see test output and `RUST_LOG=debug` for detailed logging.

```bash
cargo test
```

```bash
cargo test -- --nocapture
```

```bash
RUST_LOG=debug cargo test
```

--------------------------------

### Session Headers - Legacy Format

Source: https://github.com/ducaale/xh/blob/master/_autodocs/04-sessions.md

Example of the legacy object-map format for headers, which is automatically migrated by xh. This format does not support duplicate header names.

```json
"headers": {
  "Authorization": "Bearer token",
  "X-Custom": "value1"
}
```

--------------------------------

### Session Cookies - Legacy Format

Source: https://github.com/ducaale/xh/blob/master/_autodocs/04-sessions.md

Example of the legacy object-map format for cookies, which is automatically migrated by xh. This format does not support duplicate cookie names.

```json
"cookies": {
  "session_id": {
    "value": "abc123",
    "expires": 1609459200,
    "path": "/",
    "secure": true
  }
}
```

--------------------------------

### Download and Resume Files

Source: https://github.com/ducaale/xh/blob/master/_autodocs/00-index.md

Shows how to download files using the `-d` option and resume interrupted downloads with the `-c` flag. The `-o` option specifies the output file name.

```bash
# Download file
xh -d -o large-file.zip example.com/downloads/file

# Resume if interrupted (Ctrl+C)
xh -d -c -o large-file.zip example.com/downloads/file
```

--------------------------------

### Basic Client Configuration

Source: https://github.com/ducaale/xh/blob/master/_autodocs/06-request-building.md

Configures a reqwest client with basic settings like HTTP version casing, adaptive windowing, redirect policy, timeout, and disabling compression.

```rust
let mut client = Client::builder()
    .http1_title_case_headers()
    .http2_adaptive_window(true)
    .redirect(reqwest::redirect::Policy::none())
    // ... TLS config
    .timeout(args.timeout.and_then(|t| t.as_duration()))
    .no_gzip()
    .no_deflate()
    .no_brotli();
```

--------------------------------

### Adding URL-Encoded Query Parameters

Source: https://github.com/ducaale/xh/blob/master/_autodocs/02-request-items.md

Adds query parameters to a URL using the '==' separator. Parameters are automatically URL-encoded. This example adds 'q' and 'type' parameters.

```bash
# Creates: http://example.com/search?q=hello%20world&type=document
xh example.com/search q==hello\ world type==document
```

--------------------------------

### Initialize and Use Cookie Jar with Session

Source: https://github.com/ducaale/xh/blob/master/_autodocs/06-request-building.md

Initializes a cookie jar and loads cookies from the session if available. Cookies from the session are automatically included in subsequent requests.

```rust
let cookie_jar = Arc::new(reqwest_cookie_store::CookieStoreMutex::default());
client = client.cookie_provider(cookie_jar.clone());

// Load session cookies
if let Some(ref mut s) = session {
    let mut jar = cookie_jar.lock().unwrap();
    *jar = CookieStore::from_cookies(s.cookies(), false)?;
}
```

--------------------------------

### Select Color Scheme

Source: https://github.com/ducaale/xh/blob/master/_autodocs/01-cli-arguments.md

Sets the color scheme for syntax highlighting. Options include 'auto', 'solarized', 'monokai', and 'fruity'.

```Shell
--style <THEME>
```

```Shell
-s
```

--------------------------------

### Add Context to Errors

Source: https://github.com/ducaale/xh/blob/master/_autodocs/07-error-handling.md

Errors are augmented with context at significant operation points. This example shows how to add context to a session loading operation, resulting in a detailed error chain.

```rust
Session::load_session(url.clone(), name_or_path.clone(), args.is_session_read_only)
    .with_context(|| {
        format!("couldn't load session {:?}", name_or_path.to_string_lossy())
    })?
```

--------------------------------

### Create a New Session via CLI

Source: https://github.com/ducaale/xh/blob/master/_autodocs/04-sessions.md

Use the `--session` flag with a session name to create a new session file on the first request to a given host. This file will store accumulated authentication, headers, and cookies.

```bash
# CLI usage - creates ~/.xh/sessions/myapi.json on first request
xh --session=myapi -a user:pass example.com/api
```

--------------------------------

### Command-Line Parsing with Clap

Source: https://github.com/ducaale/xh/blob/master/_autodocs/08-architecture.md

Demonstrates CLI argument parsing using the `clap` crate with derive macros. Features a two-phase parsing process for validation and derivation of final values.

```rust
#[derive(clap::Parser)]
#[clap(version, long_version = long_version(), disable_help_flag = true)]
pub struct Cli {
    // ~50 fields with attributes
}

impl Cli {
    pub fn parse() -> Self
    pub fn try_parse_from<I>(iter: I) -> clap::error::Result<Self>
    pub fn process_relations(&mut self, matches: &clap::ArgMatches) -> clap::error::Result<()>
    pub fn into_app() -> clap::Command
    pub fn logger_config(&self) -> env_logger::Builder
}
```

--------------------------------

### JSON Path Syntax for Nested Objects

Source: https://github.com/ducaale/xh/blob/master/_autodocs/02-request-items.md

Use JSON path syntax for keys when body_type is Json to construct nested JSON objects. This example shows how to create nested structures and arrays.

```bash
app[container][0][id]=090-5
nested.field.path=value
```

--------------------------------

### Build with Specific Features

Source: https://github.com/ducaale/xh/blob/master/_autodocs/00-index.md

Demonstrates how to build the project with specific feature flags enabled or disabled. Use `cargo build --no-default-features` to disable all default features.

```bash
cargo build --features rustls,http3
```

```bash
cargo build --no-default-features --features rustls
```

--------------------------------

### Enable Redirect Following Middleware

Source: https://github.com/ducaale/xh/blob/master/_autodocs/06-request-building.md

Configures the client to follow HTTP redirects (3xx responses) up to a specified limit. Optionally preserves HTTP Message Signatures.

```rust
if args.follow {
    #[cfg(feature = "http-message-signatures")]
    {
        let message_signature = args.m_sig.has_key_pair()
            .then_some(args.m_sig.clone());

        client = client.with(RedirectFollower::new(
            args.max_redirects.unwrap_or(10),
            message_signature,
        ));
    }
}
```

--------------------------------

### Debugging Error Chains

Source: https://github.com/ducaale/xh/blob/master/_autodocs/07-error-handling.md

Example of using the --debug flag to enable detailed error reporting, including debug log messages and detailed error context. This is useful for diagnosing complex issues.

```bash
$ xh --debug invalid.example.com
```

--------------------------------

### Session Cookies - New Format

Source: https://github.com/ducaale/xh/blob/master/_autodocs/04-sessions.md

Example of the new array-based format for storing cookies within an xh session file. Each cookie object contains details like name, value, domain, path, and security flags.

```json
"cookies": [
  {
    "name": "session_id",
    "value": "abc123",
    "expires": 1609459200,
    "path": "/",
    "secure": true,
    "domain": "example.com"
  }
]
```

--------------------------------

### xh CLI Usage Syntax

Source: https://github.com/ducaale/xh/blob/master/README.md

This is the general usage syntax for the xh command-line tool. It shows the basic structure for making requests.

```bash
Usage: xh [OPTIONS] <[METHOD] URL> [REQUEST_ITEM]...

Arguments:
  <[METHOD] URL>     The request URL, preceded by an optional HTTP method
  [REQUEST_ITEM]...  Optional key-value pairs to be included in the request.

Options:
  -j, --json                             (default) Serialize data items from the command line as a JSON object
  -f, --form                             Serialize data items from the command line as form fields
      --multipart                        Like --form, but force a multipart/form-data request even without files
      --raw <RAW>                        Pass raw request data without extra processing
      --pretty <STYLE>                   Controls output processing [possible values: all, colors, format, none]
      --format-options <FORMAT_OPTIONS>  Set output formatting options
  -s, --style <THEME>                    Output coloring style [possible values: auto, solarized, monokai, fruity]
      --response-charset <ENCODING>      Override the response encoding for terminal display purposes
      --response-mime <MIME_TYPE>        Override the response mime type for coloring and formatting for the terminal
  -p, --print <FORMAT>                   String specifying what the output should contain
  -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
      --debug                            Print full error stack traces and debug log messages
      --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
  -x, --compress...                      Content compressed (encoded) with Deflate algorithm
  -o, --output <FILE>                    Save output to FILE instead of stdout
  -d, --download                         Download the body to a file instead of printing it
  -c, --continue                         Resume an interrupted download. Requires --download and --output
      --session <FILE>                   Create, or reuse and update a session
      --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)
      --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
  -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
      --proxy <PROTOCOL:URL>             Use a proxy for a protocol. For example: --proxy https:http://proxy.host:8080
      --verify <VERIFY>                  If "no", skip SSL verification. If a file path, use it as a CA bundle
      --cert <FILE>                      Use a client side certificate for SSL
      --cert-key <FILE>                  A private key file to use with --cert
      --ssl <VERSION>                    Force a particular TLS version [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, 3-prior-knowledge]
      --resolve <HOST:ADDRESS>           Override DNS resolution for specific domain to a custom IP
      --interface <NAME>                 Bind to a network interface or local IP address
  -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
  -I, --ignore-stdin                     Do not attempt to read stdin
      --curl                             Print a translation to a curl command
      --curl-long                        Use the long versions of curl's flags
      --generate <KIND>                  Generate shell completions or man pages
      --help                             Print help
```

--------------------------------

### Handle Download Errors

Source: https://github.com/ducaale/xh/blob/master/_autodocs/07-error-handling.md

This section outlines common download errors and their scenarios, including file existence, permissions, unsupported resume ranges, and content length mismatches. It also details resume behavior using the --continue flag.

```markdown
Download Errors

| Error |
|-------|
| File already exists |
| Cannot create file |
| Range not satisfiable (416) |
| Content-Length mismatch |
```

--------------------------------

### Displaying All Intermediary Responses

Source: https://github.com/ducaale/xh/blob/master/_autodocs/09-advanced-features.md

Demonstrates using the `--all` flag to print all requests and responses within a redirect chain.

```bash
# Show all requests/responses in redirect chain
xh --follow --all example.com/redirect-chain

# Use custom format for intermediary responses
xh --follow --all --history-print=h example.com  # Headers only
```

--------------------------------

### Message Signature CLI Flags

Source: https://github.com/ducaale/xh/blob/master/_autodocs/09-advanced-features.md

Demonstrates how to use CLI flags to configure and apply message signatures for HTTP requests.

```bash
xh --unstable-m-sig-id "key-id" \
   --unstable-m-sig-key "key-material" \
   --unstable-m-sig-alg rsa-pss-sha256 \
   --unstable-m-sig-coverage "@method" \
   --unstable-m-sig-coverage "@path" \
   POST example.com/api
```

--------------------------------

### xh Command Line Usage

Source: https://github.com/ducaale/xh/blob/master/doc/xh.1.md

Basic syntax for invoking the xh command with options, method, URL, and request items.

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

--------------------------------

### Shorthand URL Forms

Source: https://github.com/ducaale/xh/blob/master/README.md

Demonstrates various shorthand forms for specifying URLs, including omitting the scheme and using a colon for localhost.

```sh
xh http://localhost:3000/users # resolves to http://localhost:3000/users
xh localhost:3000/users        # resolves to http://localhost:3000/users
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
xh ://example.com              # resolves to http://example.com
```

--------------------------------

### Format XML with quick-xml

Source: https://github.com/ducaale/xh/blob/master/_autodocs/05-printing-formatting.md

Formats XML content by re-parsing and re-indenting it. Configurable indentation is supported, and whitespace-only text nodes are removed while preserving meaningful content.

```rust
pub fn format_xml(indent: usize, text: &str) -> io::Result<Vec<u8>> {
    let mut reader = Reader::from_str(text);
    let mut writer = Writer::new_with_indent(Vec::new(), b' ', indent);
    // ...
}
```

--------------------------------

### Manage Sessions Across Multiple API Operations

Source: https://github.com/ducaale/xh/blob/master/_autodocs/04-sessions.md

Demonstrates how to use a session to maintain authentication and state across various API calls to the same host. The session is created on the first authenticated request and reused for subsequent operations.

```bash
# Authenticate and create session
xh --session=api POST api.example.com/login user=admin pass=secret

# Reuse credentials for multiple endpoints
xh --session=api api.example.com/users
xh --session=api api.example.com/posts
xh --session=api api.example.com/comments

# All requests use the same auth credentials and cookies
```

--------------------------------

### Handle Configuration File Parsing Errors

Source: https://github.com/ducaale/xh/blob/master/_autodocs/07-error-handling.md

This snippet shows how to parse a configuration file using serde_json. Errors during parsing are reported as warnings, and the configuration is ignored if it cannot be parsed.

```rust
match serde_json::from_str::<Config>(&content) {
    Ok(config) => Some(config.default_options),
    Err(err) => {
        eprintln!(
            "\n{}: warning: Unable to parse config file: {}\n",
            env!("CARGO_PKG_NAME"),
            err
        );
        None
    }
}
```

--------------------------------

### Use Sessions for Multi-Request Workflows

Source: https://github.com/ducaale/xh/blob/master/_autodocs/00-index.md

Demonstrates using sessions to manage authentication and reuse credentials across multiple API calls. The `--session` flag specifies the session to use.

```bash
# Authenticate and create session
xh --session=github -a octocat:password github.com/user

# Reuse credentials for multiple API calls
xh --session=github github.com/user/repos
xh --session=github -X GET github.com/user/gists
xh --session=github POST github.com/user/repos name=new-repo
```

--------------------------------

### Default Options Configuration

Source: https://github.com/ducaale/xh/blob/master/_autodocs/00-index.md

Specifies default command-line options to be applied to all requests. Useful for setting consistent formatting and output preferences.

```json
{
  "default_options": [
    "--pretty=colors",
    "--print=hb",
    "--format-options=json.indent:2"
  ]
}
```

--------------------------------

### Adding HTTP Headers

Source: https://github.com/ducaale/xh/blob/master/_autodocs/02-request-items.md

Demonstrates how to add custom HTTP headers to a request. Simply append key-value pairs after the URL.

```bash
xh httpbin.org/get x-api-key:secret user-agent:MyApp/1.0
```

--------------------------------

### Automatic Authentication with .netrc

Source: https://github.com/ducaale/xh/blob/master/_autodocs/09-advanced-features.md

xh automatically reads credentials from .netrc files for seamless authentication. Ensure your .netrc file has 0600 permissions for security.

```bash
machine github.com
login octocat
password ghp_1234567890abcdef

machine api.example.com
login user
password secret
```

--------------------------------

### Verify Request Construction

Source: https://github.com/ducaale/xh/blob/master/_autodocs/00-index.md

Use this command to verify how xh constructs a POST request with form data. It helps in debugging issues related to how fields are sent.

```bash
# Verify request construction
xh --offline POST example.com field1=value1 field2=value2
```

--------------------------------

### Download Mode Flags

Source: https://github.com/ducaale/xh/blob/master/_autodocs/09-advanced-features.md

Illustrates common flags used for downloading files, including specifying output, resuming interrupted downloads, and enabling download mode.

```bash
xh --download example.com/file.pdf
xh -d -o downloaded.pdf example.com/file.zip
xh -d --continue -o large-file.bin example.com/downloads/large
```

--------------------------------

### Print Configuration Struct

Source: https://github.com/ducaale/xh/blob/master/_autodocs/08-architecture.md

Controls output composition for requests and responses. Derived from CLI flags or a --print string parameter.

```rust
pub struct Print {
    pub request_headers: bool,
    pub request_body: bool,
    pub response_headers: bool,
    pub response_body: bool,
    pub response_meta: bool,
}
```

--------------------------------

### Bearer Token Authentication (JWT)

Source: https://github.com/ducaale/xh/blob/master/_autodocs/03-authentication.md

Demonstrates how to use a bearer token for authentication, either for a single request or by reading the token from a file. This is commonly used for JWT authentication.

```bash
# Single-shot request
xh --bearer "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0..." \
  example.com/api/data

# Or read from file
TOKEN=$(cat ~/.secrets/jwt_token)
xh --bearer "$TOKEN" example.com/api/data
```

--------------------------------

### Construct File Request Body

Source: https://github.com/ducaale/xh/blob/master/_autodocs/06-request-building.md

Opens a file and streams its content as the request body. Sets the 'Content-Type' header, inferring if necessary.

```rust
Body::File { file_name, file_type, .. } => {
    request_builder
        .body(File::open(file_name)?)
        .header(CONTENT_TYPE, file_type.unwrap_or_else(|| /* infer */))
}
```

--------------------------------

### Specify Output Content (Print)

Source: https://github.com/ducaale/xh/blob/master/_autodocs/01-cli-arguments.md

Selects which parts of the request and response to print. 'H' for request headers, 'B' for request body, 'h' for response headers, 'b' for response body, 'm' for response metadata.

```Shell
--print <FORMAT>
```

```Shell
-p
```

```Shell
--print=Hb
```

--------------------------------

### HTTPS with URL Shorthand

Source: https://github.com/ducaale/xh/blob/master/_autodocs/09-advanced-features.md

Use the --https flag with URL shorthands to force HTTPS connections.

```bash
xh --https example.com  # https://example.com
xh --https :8000/api    # https://localhost:8000/api
```

--------------------------------

### HTTP Version Configuration

Source: https://github.com/ducaale/xh/blob/master/_autodocs/06-request-building.md

Configures the HTTP version for the client based on command-line arguments, supporting HTTP/1.0, 1.1, 2, and 3.

```rust
client = match args.http_version {
    Some(HttpVersion::Http10) => client.http1_only(),
    Some(HttpVersion::Http11) => client.http1_only(),
    Some(HttpVersion::Http2PriorKnowledge) => client.http2_prior_knowledge(),
    Some(HttpVersion::Http2) => client,                      // Auto-negotiate
    Some(HttpVersion::Http3PriorKnowledge) => client.http3_prior_knowledge(),
    None => client,
};
```

--------------------------------

### Setting Max Redirects via CLI

Source: https://github.com/ducaale/xh/blob/master/_autodocs/09-advanced-features.md

Shows how to limit the number of redirects followed using the `--max-redirects` flag.

```bash
xh --follow --max-redirects=5 example.com/redirect
```

--------------------------------

### Make Request with Custom User Agent

Source: https://github.com/ducaale/xh/blob/master/doc/md-template.md

Set a custom User-Agent header for the request. This is done by specifying 'user-agent:value' as a request item.

```bash
xh httpbin.org/get user-agent:foobar
```

--------------------------------

### Print Response Metadata Only

Source: https://github.com/ducaale/xh/blob/master/_autodocs/01-cli-arguments.md

A shortcut to print only the response metadata.

```Shell
--meta
```

```Shell
-m
```

--------------------------------

### Skip SSL Verification

Source: https://github.com/ducaale/xh/blob/master/_autodocs/00-index.md

Demonstrates how to bypass SSL certificate verification using `--verify=no`. This is intended for development environments only due to security risks.

```bash
# Skip SSL verification (development only!)
xh --verify=no https://self-signed.example.com
```

--------------------------------

### Request Builder Initialization

Source: https://github.com/ducaale/xh/blob/master/_autodocs/06-request-building.md

Initializes a request builder with the specified HTTP method and URL, setting default headers for Accept-Encoding and User-Agent.

```rust
let mut request_builder = client
    .request(method, url.clone())
    .header(ACCEPT_ENCODING, HeaderValue::from_static("gzip, deflate, br, zstd"))
    .header(USER_AGENT, get_user_agent());
```

--------------------------------

### xh Request Item Syntax

Source: https://github.com/ducaale/xh/blob/master/_autodocs/00-index.md

Details the different syntaxes for specifying query parameters, string fields, JSON literals, headers, file uploads, and file bodies within xh requests.

```bash
| Syntax | Type | Example |
|--------|------|---------|
| `==` | Query param | `id==5 sort==name` |
| `=` | String field | `name=alice email=alice@example.com` |
| `:=` | JSON literal | `count:=10 enabled:=true ids:=[1,2,3]` |
| `:` | Header | `authorization:Bearer\ token x-api-key:secret` |
| `@` | File upload | `photo@image.jpg document@report.pdf;type=application/pdf` |
| `@file` | File body | `@request.json`
```

--------------------------------

### Rust struct for Highlighter

Source: https://github.com/ducaale/xh/blob/master/_autodocs/05-printing-formatting.md

Represents a syntax highlighter that uses the syntect library to colorize response bodies. It requires a syntax definition, a theme, and an output buffer.

```rust
pub struct Highlighter<'a> {
    highlighter: HighlightLines<'static>,
    syntax_set: &'static SyntaxSet,
    out: &'a mut Buffer,
}

impl<'a> Highlighter<'a> {
    pub fn new(syntax: &'static str, theme: Theme, out: &'a mut Buffer) -> Self
    pub fn highlight(&mut self, text: &str) -> io::Result<()>
    pub fn highlight_bytes(&mut self, line: &[u8]) -> io::Result<()>
    pub fn flush(&mut self) -> io::Result<()>
}
```

--------------------------------

### Print Response Body Only

Source: https://github.com/ducaale/xh/blob/master/_autodocs/01-cli-arguments.md

A shortcut to print only the response body.

```Shell
--body
```

```Shell
-b
```

--------------------------------

### Client Certificate Configuration

Source: https://github.com/ducaale/xh/blob/master/_autodocs/06-request-building.md

Sets a client certificate for mutual TLS authentication if provided via arguments.

```rust
if let Some(cert) = args.cert {
    let identity = reqwest::Identity::from_pem(&cert_material)?;
    client = client.identity(identity);
}
```

--------------------------------

### File Naming Logic for Downloads

Source: https://github.com/ducaale/xh/blob/master/_autodocs/09-advanced-features.md

Outlines the priority order for determining the filename when downloading a file, based on response headers, URL, and MIME type.

```rust
fn get_file_name(response: &Response, url: &Url) -> String {
    // Priority:
    // 1. Content-Disposition filename parameter
    // 2. URL path segment
    // 3. Guess from MIME type
    // 4. Default to "index"
}
```

--------------------------------

### Proxy Configuration

Source: https://github.com/ducaale/xh/blob/master/_autodocs/06-request-building.md

Configures HTTP proxies for the client, allowing specification for different protocols and overriding environment variables.

```rust
for proxy in args.proxy.into_iter().rev() {
    client = client.proxy(match proxy {
        Proxy::Http(url) => reqwest::Proxy::http(url),
        Proxy::Https(url) => reqwest::Proxy::https(url),
        Proxy::All(url) => reqwest::Proxy::all(url),
    })?;
}
```

--------------------------------

### URL Parameter from File Syntax

Source: https://github.com/ducaale/xh/blob/master/_autodocs/02-request-items.md

Specifies the syntax for reading a URL parameter's value from a file.

```text
id==@file.txt
```

--------------------------------

### Print Response Headers Only

Source: https://github.com/ducaale/xh/blob/master/_autodocs/01-cli-arguments.md

A shortcut to print only the response headers.

```Shell
--headers
```

```Shell
-h
```

--------------------------------

### Download and Save Response

Source: https://github.com/ducaale/xh/blob/master/doc/md-template.md

Download the response body and save it to a file using the '-o' option. The '-d' option indicates that the response should be downloaded.

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

--------------------------------

### Handle URL Construction Errors

Source: https://github.com/ducaale/xh/blob/master/_autodocs/07-error-handling.md

This code demonstrates how to construct a URL and map potential errors to a clap validation error. It handles invalid URL formats, schemes, and other parsing issues.

```rust
cli.url = construct_url(&raw_url, cli.default_scheme.as_deref())
    .map_err(|err| {
        app.error(
            clap::error::ErrorKind::ValueValidation,
            format!("Invalid <URL>: {err}"),
        )
    })?
```

--------------------------------

### Verbose Output

Source: https://github.com/ducaale/xh/blob/master/_autodocs/01-cli-arguments.md

Prints both request and response details. Higher verbosity levels add more information, with '-vv' including metadata. Equivalent to '--print=HhBb --all'.

```Shell
--verbose
```

```Shell
-v
```

```Shell
-vv
```

--------------------------------

### Compress File with brotli

Source: https://github.com/ducaale/xh/blob/master/tests/fixtures/responses/README.md

Use brotli to compress a file, creating a .br extension.

```sh
$ echo "Hello world" > hello_world
$ brotli hello_world # hello_world.br
```

--------------------------------

### Basic CLI Request Structure

Source: https://github.com/ducaale/xh/blob/master/_autodocs/01-cli-arguments.md

Defines the core structure for CLI requests, including optional HTTP method, required URL, and request items.

```Rust
pub struct Cli {
    // Core request parameters
    pub method: Option<Method>,
    pub url: Url,
    pub request_items: RequestItems,
}

// Invocation: xh [OPTIONS] <[METHOD] URL> [REQUEST_ITEM]...
```