http (HTTPie): Usage, Options & Common CI Errors
HTTPie sends expressive HTTP requests with a concise, curl-free syntax.
HTTPie is the readable alternative to curl for smoke-testing APIs in pipelines. The CI essential is --check-status, because by default http exits 0 even on a 500.
What it does
http (HTTPie) builds and sends HTTP requests with a simple key=value / key:=raw-json syntax, pretty-prints JSON, and colorizes output. By default it exits 0 regardless of the HTTP status, so a 4xx/5xx passes silently unless you opt in.
Common usage
http GET https://api.example.com/health
http --check-status GET https://api/health # exit non-zero on 4xx/5xx
http POST https://api/x name=ci active:=true # := sends raw JSON
http -b GET https://api/x # body only, no headers
http GET https://api/x Authorization:"Bearer ${TOKEN}"Options
| Flag | What it does |
|---|---|
| --check-status | Exit 3/4/5 on 3xx/4xx/5xx instead of 0 |
| -b / --body | Print only the response body |
| -h / --headers | Print only the response headers |
| --json / -j | Force JSON Content-Type/Accept |
| --ignore-stdin | Do not read request body from stdin |
| --timeout=SECS | Fail after SECS of inactivity |
Common errors in CI
Without --check-status, a 500 returns exit 0 and the job "passes" - always add --check-status so http exits 4 (4xx) or 5 (5xx). Exit 2 = request timed out or a network error; exit 3 = a 3xx with --check-status and no --follow. In a pipeline HTTPie may hang waiting on stdin for a request body - pass --ignore-stdin. "http: command not found" means the package is httpie (the binary is http), which collides with no standard tool but is absent on slim images.