curl — The Real Tool That Doesn't Lie

"curl is on every Mac, every Linux box, every container image. It speaks every version of HTTP. It shows you what your library hides. When an API call misbehaves, curl is the first move — not the last."

The Flags You Use Daily

A handful of flags cover 90% of debugging:

• -v — verbose. Shows request lines (>), response lines (<), and curl's connection/TLS commentary (*). Your first debugging move.
• -i — include response headers in output. Just headers; not the connection chatter.
• -I (capital) — HEAD request only. Get headers without downloading the body.
• -X METHOD — use this HTTP method. -X POST, -X DELETE, etc.
• -H 'Name: value' — add a request header. Can repeat for multiple.
• -d 'body' — send a body. -d @file.json reads from a file. Implies POST.
• --data-binary @file — send file bytes verbatim, no line-ending translation. Use for binary uploads.
• -u user:pass — HTTP Basic auth (shortcut for -H 'Authorization: Basic ...').
• -N — no buffering of curl's own output. Essential for SSE / streaming.
• --compressed — request and decompress gzip/br. Lets you compare compressed vs uncompressed sizes.
• -L — follow redirects automatically. Without it, you see the 3xx response and stop.
• -o file / -O — write body to a file (named or from URL).
• -w '%{http_code}\n' — print specific transfer info (status code, size, time) after the response.

The X-Ray Move

curl -v is the canonical "why isn't this working" tool:

# Watch every byte sent and received
curl -v -X POST https://api.example.com/users \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer abc.def.ghi' \
  -d '{"name":"Pippa"}'

# Output shape:
# *   Trying 1.2.3.4:443...               (TCP connect)
# * TLSv1.3 (OUT), TLS handshake, ...    (TLS handshake)
# > POST /users HTTP/1.1                  (request line)
# > Host: api.example.com                 (request header)
# > Authorization: Bearer abc.def.ghi     (request header)
# > Content-Type: application/json        (request header)
# > Content-Length: 17                    (request header)
# >
# > {"name":"Pippa"}                       (request body)
# < HTTP/1.1 201 Created                  (status line)
# < Location: /users/u_abc                 (response header)
# < Content-Type: application/json         (response header)
# < {"id":"u_abc","name":"Pippa"}          (response body)

You see EXACTLY what went on the wire and EXACTLY what came back. No library magic, no framework abstractions. Half of "my httpx call returns 401 but my curl returns 200" mysteries dissolve when you compare the verbose output.

The Power Combos

Timing breakdown — see DNS / TCP / TLS / response phases separately:

curl -w 'dns=%{time_namelookup}s connect=%{time_connect}s tls=%{time_appconnect}s ttfb=%{time_starttransfer}s total=%{time_total}s\n' -o /dev/null -s https://api.example.com/

SSE stream with no buffering:

curl -N -H 'Accept: text/event-stream' https://api.example.com/stream

Test rate limiting — hammer an endpoint 100 times, count statuses:

for i in {1..100}; do
  curl -s -o /dev/null -w '%{http_code}\n' https://api.example.com/
done | sort | uniq -c

Reproduce a browser fetch — Chrome DevTools' Network panel has "Copy as cURL" — paste straight into terminal and reproduce the bug locally.

cwkPippa's curl Usage