xh git:20260923.2988db2A

Immutable. This exact content is served forever at /api/v1/blob/ed08529087453c6e.

---
name: xh
description: "Inspect HTTP endpoints with bounded, credential-safe requests using xh."
license: MIT
metadata:
  kind: connector
  author: Médéric HURIER (Fmind)
  source: github.com/fmind/dot/tree/main/skills/xh
  created: "2026-09-05"
  updated: "2026-09-23"
---

# xh HTTP Inspection

Use xh for bounded read-only HTTP inspection; debugging a known failure belongs to [systematic-debugging](../systematic-debugging/SKILL.md), and API research to [research-brief](../implementation-plan/references/research-brief.md).

## Workflow

1. **Confirm the target**: use an explicit trusted URL, ignore stdin, and start with headers so redirects and advertised size are visible without fetching a body.

   ```bash
   xh --ignore-stdin --check-status --timeout 10 HEAD https://example.com/health
   ```

1. **Limit the displayed body**: request at most 64 KiB and cap displayed output even when a server ignores `Range`; do not add `--follow` until the redirect target is reviewed.

   ```bash
   xh --ignore-stdin --check-status --timeout 10 GET https://example.com/api Range:bytes=0-65535 | head -c 65536
   ```

1. **Protect credentials**: pass synthetic or environment-sourced authorization only to the intended origin. Use `--print=h` or `--body`; never `--verbose`, `--debug`, `--curl`, sessions, or request-header printing around secrets.
1. **Interpret honestly**: `--timeout` covers an individual request, including response-body reads in xh 0.26.2, despite its help calling it a connection timeout; the byte cap bounds displayed output. Use a process supervisor for a hard deadline across redirects, authentication retries, and output processing; a Range request is not a guaranteed transfer limit. In Bash, retain `PIPESTATUS` immediately after the pipeline and report truncation/SIGPIPE separately from HTTP success. Record status, relevant response headers, truncation, and any untested redirect or authentication boundary.
1. **Require authority for writes**: POST, PUT, PATCH, DELETE, uploads, and state-changing form or JSON bodies need explicit authorization for the exact target and effect.

## Gotchas

- `--follow` can forward a request to another origin; inspect `Location` first and never follow an untrusted redirect with credentials.
- `--verify=no` disables TLS verification and is not an acceptable workaround.
- `--session` persists cookies and credentials; prefer no session, or use `--session-read-only` only with an explicitly approved synthetic fixture.
- A truncated body is inspection evidence, not proof that the full response is valid.

## Official Skills

xh has no upstream skill bundle. Use the installed CLI and verify flags with `xh --help`.

## Documentation

- [xh](https://github.com/ducaale/xh) · [command reference](https://github.com/ducaale/xh#usage) · [request timeout implementation](https://github.com/ducaale/xh/blob/v0.26.2/src/main.rs)
- Releases: [xh](https://github.com/ducaale/xh/releases) · [changelog](https://github.com/ducaale/xh/blob/master/CHANGELOG.md)
- Companion skills: [research-brief](../implementation-plan/references/research-brief.md), [systematic-debugging](../systematic-debugging/SKILL.md), [gws](../gws/SKILL.md) (authenticated Google Workspace operations).