curl -I / --head: Headers-Only Health Checks
-I fetches just the headers, which is ideal for a cheap liveness probe.
When you only need the status or a header, a HEAD request avoids downloading the body. It is the lightest health check curl offers.
What it does
-I / --head issues an HTTP HEAD request and prints the response headers only. The server returns the same headers it would for a GET but no body, so it is cheap. Note that some endpoints do not implement HEAD and return 405; in that case use a GET with -o /dev/null instead.
Common usage
curl -I https://api.example.com/health
curl -sI https://api.example.com/health | head -n1
curl -fsI https://api.example.com/health # fail on >= 400
# status without HEAD, when HEAD is unsupported:
curl -s -o /dev/null -w '%{http_code}' https://api.example.com/healthFlags
| Flag | What it does |
|---|---|
| -I / --head | Send HEAD; print response headers only |
| -s | Hide the progress meter for clean output |
| -f | Fail on HTTP >= 400 |
| -o /dev/null -w '%{http_code}' | GET-based status check when HEAD is unsupported |
In CI
A HEAD check is a good readiness probe because it does not transfer the body, so it is fast and cheap on bandwidth. If the service returns 405 to HEAD, fall back to a GET that discards the body with -o /dev/null and reads %{http_code} via -w.
Common errors in CI
A 405 Method Not Allowed to -I means the endpoint does not support HEAD; switch to a GET status check. curl: (52) Empty reply from server on -I usually means the service is not up yet; wrap it in a wait-until-ready loop.