The essentials
Quick reference
One focused task per row. Jump to the related section for complete, working examples.
| Use | Syntax | Examples |
|---|---|---|
| Include response headers | curl --include https://example.com/health | View examples |
| Request headers only | curl --head https://example.com/asset | View examples |
| Trace protocol exchange | curl --verbose https://example.com/health | View examples |
| Follow redirects | curl --location --max-redirs 5 https://example.com/old | View examples |
| Fail on HTTP errors | curl --fail-with-body https://example.com/api | View examples |
| Print status metadata | curl --silent --output /dev/null --write-out \
'%{http_code}\n' https://example.com/ | View examples |
| Send JSON | curl --json @payload.json https://api.example.com/items | View examples |
| Add a header | curl --header 'Accept: application/json' \
https://api.example.com/items | View examples |
| Upload a file body | curl --upload-file ./artifact.bin \
https://upload.example.com/artifact.bin | View examples |
| Bound time | curl --connect-timeout 5 --max-time 30 \
https://example.com/ | View examples |
| Retry transient failures | curl --retry 3 --retry-all-errors --max-time 30 \
https://example.com/ | View examples |
| Save to an exact path | curl --fail --output ./artifact.tar.gz \
https://example.com/artifact.tar.gz | View examples |
| Use an explicit CA bundle | curl --cacert ./ca.pem https://internal.example/ | View examples |
| Measure phases | curl --output /dev/null --write-out \
'dns=%{time_namelookup} connect=%{time_connect} total=%{time_total}\n' \
https://example.com/ | View examples |
curl is both a transfer client and a precise HTTP diagnostic tool. Keep secrets out of command history and process arguments, distinguish response bodies from diagnostics, fail automation on HTTP errors, bound connection and total time, and verify certificates rather than disabling TLS checks.
Step by step
Detailed examples
Separate body output from diagnostic output
curl writes response bodies to stdout and verbose diagnostics to stderr, so redirect them independently. --include prints response headers with the body; --head sends HEAD, which servers may implement differently from GET. Verbose output can expose authorization headers and cookies.
curl --silent --show-error \
--dump-header ./response.headers \
--output ./response.body \
https://example.com/health
sed -n '1,20p' ./response.headersMake redirect and status policy explicit
curl normally treats HTTP error status as a successful transfer and does not follow redirects. --fail-with-body changes 400+ into a nonzero result, while --location follows redirects. Credentials can cross trust boundaries, so review redirect targets and avoid broad credential forwarding.
curl --silent --show-error --fail-with-body \
--location --max-redirs 5 \
--output ./response.json \
https://api.example.com/v1/statusLet curl construct content headers where possible
--json sends data and defaults Content-Type and Accept to JSON. @file reads a file and @- reads stdin. Prefer config files, stdin, netrc with protected permissions, or external credential helpers over secrets directly in arguments; arguments may appear in history and process listings.
curl --silent --show-error --fail-with-body \
--json @payload.json \
--output ./created.json \
https://api.example.com/itemsBound waits and retry only safe operations
Connection timeout covers establishment; max-time bounds an attempt. Retries can duplicate non-idempotent operations if the server processed a request before failure. Use retry policy primarily for idempotent reads or endpoints with idempotency keys, and cap total orchestration time outside curl as needed.
curl --silent --show-error --fail \
--connect-timeout 5 --max-time 20 \
--retry 3 --retry-delay 1 \
https://example.com/healthVerify transport and artifact identity
TLS verification authenticates the endpoint against trusted CAs; --insecure disables that protection and should not become a workaround. A successful HTTPS download still needs an expected hash or signature when artifact integrity matters. Save to a staging path and verify before replacing live files.
curl --fail --location --output ./artifact.tar.gz https://example.com/artifact.tar.gz
printf '%s %s\n' 'EXPECTED_SHA256' './artifact.tar.gz' | sha256sum --check -Note: Replace EXPECTED_SHA256 with a value obtained through the publisher's trusted release channel.
Measure phases before diagnosing the network
write-out exposes DNS, connection, TLS, first-byte, and total timing. Proxy environment variables can silently change the route; inspect them without printing embedded secrets. A single request is not a benchmark, but phase timings help locate name resolution, connection, server, or transfer delays.
curl --silent --show-error --output /dev/null \
--write-out 'remote=%{remote_ip} dns=%{time_namelookup} connect=%{time_connect} tls=%{time_appconnect} first=%{time_starttransfer} total=%{time_total}\n' \
https://example.com/Sources and further reading
References
Authoritative documentation used to verify and expand this cheat sheet.
Help us improve
Found a typo or missing example?
Tell us what would make this cheat sheet clearer, more complete, or more useful.