xh · diff
git:20260919.4491844 to git:20260923.2988db2
3 added, 3 removed. Audit A to A.
---
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-19"
+ 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` bounds connection establishment, while the byte cap bounds displayed output. Use a process supervisor for a hard wall-clock deadline; 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. **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)
+ - [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).