Curl Power User

Secure defaults, auth, JSON, and debugging with curl.

Quick recipes

Secure defaults

Harden curl for production scripts. These flags fail fast, avoid silent downgrade, and add resilience.

curl --fail-with-body --proto '=https' --tlsv1.2 \
  --retry 5 --retry-all-errors --retry-connrefused \
  --connect-timeout 5 --max-time 30 \
  -H 'User-Agent: curl-probe/1.0' \
  https://example.com/health

Auth recipes

Bearer token

curl -H "Authorization: Bearer $TOKEN" https://api.example.com/v1/me

Basic via .netrc

# ~/.netrc
machine api.example.com login USER password PASS
# usage
curl --netrc https://api.example.com/private

mTLS (client cert)

curl --cert client.crt --key client.key https://mtls.example.internal/status

JSON & APIs

# POST JSON from file
curl -H 'Content-Type: application/json' \
  --data @payload.json https://api.example.com/items

# PATCH with jq inline
jq -n '{enabled:true}' | curl -H 'Content-Type: application/json' \
  --data-binary @- https://api.example.com/feature/flag

Debugging

# Verbose TLS/HTTP
curl -v https://example.com

# Full trace (sanitize later!)
curl --trace-ascii trace.log https://example.com

# Time phases (DNS, connect, TLS, TTFB)
curl -w '\nnamelookup: %{time_namelookup}\nconnect: %{time_connect}\nappconnect: %{time_appconnect}\nstarttransfer: %{time_starttransfer}\ntotal: %{time_total}\n' -o /dev/null -s https://example.com

CI/CD health checks

# Retry and fail pipeline on non-2xx
curl --fail-with-body --retry 5 --retry-all-errors --max-time 20 \
  https://service.example.internal/ready

Checksum verification

# Download and verify sha256
target=tool.tar.gz; sum=tool.sha256
curl -sSLo $target https://dl.example.com/$target
curl -sSLo $sum https://dl.example.com/$sum
sha256sum -c $sum # expects "$hash  $target"

Common pitfalls

Using -k/--insecure in scripts. Avoid; fix CA chain or use mTLS.
Silent failures without --fail-with-body and proper exit code handling.
Forgetting timeouts; defaults can hang. Use --connect-timeout and --max-time.

Production checklist

Set timeouts and retries appropriate to SLOs.
Lock HTTPS only: --proto '=https'; pin minimum TLS: --tlsv1.2.
Emit clear logs: include URL, exit status, and timings (-w).
Never log secrets (redact tokens if tracing).

Follow Redirects with Headers

Follow redirects; print response headers (HEAD).

curl -L -I https://example.com

Options: -L follows redirects, -I shows headers only (HEAD request)

POST JSON Data

POST a JSON body (example values are placeholders, not real secrets).

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"secret"}' \
  https://api.example.com/login

Tip: Use @filename.json instead of inline JSON: -d @payload.json

Download with Progress Bar

Download to a file with a progress meter instead of default output.

curl -# -o filename.zip https://example.com/downloads/file.zip

Alternative: Use --progress-bar instead of -# for the same effect

Measure Response Time

Print timing and size via -w while discarding the body.

curl -w "Total time: %{time_total}s\nSize: %{size_download} bytes\n" \
  -o /dev/null -s https://api.example.com/endpoint

More metrics: %{time_connect}, %{time_starttransfer}, %{http_code}

Save Cookies and Headers

Save cookies (-c), dump response headers (-D), reuse cookies with -b.

curl -c cookies.txt -D headers.txt https://example.com/login

# Use saved cookies in subsequent request
curl -b cookies.txt https://example.com/dashboard

Options: -c saves cookies, -b sends cookies, -D dumps headers