@kszongic/http-head-cli

Send HTTP HEAD requests and print response headers from the command line. Zero dependencies. Works on Windows, macOS, and Linux.

$ http-head example.com
HTTP/1.1 200 OK
content-type: text/html; charset=UTF-8
content-length: 1256
server: ECAcc (sac/254F)

Why?

Sometimes you just need to check headers — cache status, content type, redirects, CORS, security headers — without downloading the full response body. curl -I works, but it is not always available (Windows), and parsing its output is annoying.

http-head gives you:

• 🚀 Instant header inspection — HEAD requests download zero body bytes
• 📦 JSON output — pipe directly into jq for scripting
• 🔀 Redirect following — trace the full redirect chain
• ⏱️ Custom timeouts — do not hang on slow servers
• 🌐 Auto https:// — skip the protocol prefix, it just works

Install

npm i -g @kszongic/http-head-cli

Or run directly:

npx @kszongic/http-head-cli example.com

Usage

Print response headers

http-head https://example.com

Status code only

http-head -s https://example.com
# 200

JSON output

http-head -j https://example.com
# {"status":200,"headers":{"content-type":"text/html; charset=UTF-8",...}}

Follow redirects

http-head -L https://httpbin.org/redirect/2

Custom timeout

http-head -t 5000 https://example.com

Auto-prepend https://

http-head example.com
# Same as: http-head https://example.com

Options

Flag	Description
-s, --status	Print only the status code
-j, --json	Output headers as JSON
-L, --follow	Follow redirects (up to 10)
-t, --timeout	Timeout in milliseconds (default: 10000)
-h, --help	Show help
-v, --version	Show version

Recipes

Check cache headers across CDN nodes

for i in 1 2 3 4 5; do
  echo "--- Request $i ---"
  http-head -j cdn.example.com | jq '.headers["x-cache"], .headers["cf-cache-status"]'
done

Verify security headers in CI

# GitHub Actions step — fail if missing security headers
HEADERS=$(http-head -j https://mysite.com)
echo "$HEADERS" | jq -e '.headers["strict-transport-security"]' || exit 1
echo "$HEADERS" | jq -e '.headers["x-content-type-options"]' || exit 1
echo "$HEADERS" | jq -e '.headers["x-frame-options"]' || exit 1
echo "All security headers present"

Monitor site uptime

STATUS=$(http-head -s https://api.example.com)
if [ "$STATUS" != "200" ]; then
  echo "API returned $STATUS"
fi

Trace redirect chains

http-head -L -j https://bit.ly/xyz | jq '.status'

Check content-type before downloading

TYPE=$(http-head -j https://api.example.com/data | jq -r '.headers["content-type"]')
if [[ "$TYPE" == *"application/json"* ]]; then
  curl -s https://api.example.com/data | jq .
else
  echo "Not JSON: $TYPE"
fi

Batch uptime check

for domain in example.com google.com github.com; do
  STATUS=$(http-head -s "$domain")
  echo "$domain -> $STATUS"
done

Use Cases

• DevOps monitoring — Quick uptime and status checks without downloading bodies
• Security audits — Verify HSTS, CSP, X-Frame-Options, and other security headers
• CDN debugging — Check cache hit/miss, edge server, and age headers
• API development — Verify content-type, CORS headers, and rate limit headers
• CI/CD pipelines — Gate deployments on header compliance
• Redirect debugging — Trace 301/302 chains for SEO or migration validation

How It Works

Uses Node.js built-in https (or http) module to send a HEAD request — the server returns headers only, no response body. This makes it extremely fast and bandwidth-efficient. No external dependencies, no native bindings.

Comparison

Tool	Zero deps	Cross-platform	JSON output	Follow redirects	Status-only	Install
http-head	✅	✅ Win/Mac/Linux	✅	✅	✅	npx @kszongic/http-head-cli
curl -I	N/A	⚠️ Not on Windows by default	❌ (needs parsing)	✅ -L	❌ (needs grep)	Built-in (Unix)
wget --spider	N/A	⚠️ Not on Windows	❌	✅	❌	Built-in (Linux)
httpie	❌ (Python)	✅	✅	✅	❌	pip install httpie

Related Tools

• url-status-cli — Check HTTP status codes for URLs
• cert-days-cli — Check SSL certificate expiry
• port-scan-cli — Scan TCP ports on a host
• find-open-port-cli — Find an available port
• env-lint-cli — Lint .env files against .env.example

License

MIT © kszongic