Cheat sheet

curl

HTTP requests, headers, auth, TLS, downloads, and timing breakdowns.

Basic requests

# GET request
curl https://api.example.com/users

# POST with JSON body
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "role": "admin"}'

# PUT
curl -X PUT https://api.example.com/users/1 \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice Updated"}'

# DELETE
curl -X DELETE https://api.example.com/users/1

# Send form data
curl -X POST https://example.com/form \
  -F "username=alice" \
  -F "file=@/path/to/file.txt"

Headers & auth

# Custom header
curl -H "X-API-Key: abc123" https://api.example.com

# Bearer token
curl -H "Authorization: Bearer <token>" https://api.example.com

# Basic auth
curl -u username:password https://api.example.com

# Multiple headers
curl \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Request-ID: abc123" \
  https://api.example.com

# Show response headers
curl -I https://example.com

# Show both request and response headers
curl -v https://example.com

TLS & certificates

# Skip TLS verification (dev only)
curl -k https://self-signed.example.com

# Use custom CA certificate
curl --cacert /path/to/ca.crt https://internal.example.com

# Client certificate auth (mTLS)
curl --cert client.crt --key client.key \
  https://mtls.example.com

# Check TLS certificate details
curl -vI https://example.com 2>&1 | grep -A 10 "Server certificate"

# Connect with specific TLS version
curl --tls-max 1.2 https://example.com
curl --tlsv1.3 https://example.com

Output & download

# Save to file (preserving filename)
curl -O https://example.com/file.zip

# Save to specific file
curl -o output.json https://api.example.com/data

# Follow redirects
curl -L https://example.com

# Silent mode (no progress bar)
curl -s https://api.example.com | jq '.'

# Show only HTTP status code
curl -s -o /dev/null -w "%{http_code}" https://example.com

# Resume interrupted download
curl -C - -O https://example.com/large-file.zip

Debugging & timing

# Verbose output (headers, TLS handshake)
curl -v https://example.com

# Timing breakdown
curl -w "\n
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://example.com

# Trace all data (very verbose)
curl --trace-ascii - https://example.com

# Show effective URL after redirects
curl -Ls -o /dev/null -w "%{url_effective}" https://example.com

Useful flags

# Retry on transient errors
curl --retry 3 --retry-delay 2 \
  --retry-connrefused https://api.example.com

# Connection timeout (seconds)
curl --connect-timeout 5 https://api.example.com

# Max total time
curl --max-time 30 https://api.example.com

# Use specific DNS resolver
curl --resolve example.com:443:1.2.3.4 https://example.com

# Send request to specific IP (test without DNS)
curl -H "Host: example.com" https://1.2.3.4

# Compress response
curl --compressed https://api.example.com

# Send cookies
curl -b "session=abc123" https://example.com

About the curl cheat sheet

curl's defaults are quiet in ways that hide exactly what you are usually trying to diagnose. It prints the body and nothing else, so a redirect, a TLS negotiation or an unexpected status code passes without comment. The flags that show headers, follow redirects and report timing are what make it a debugging tool rather than a downloader.

For API work, three things matter most: setting the method and body correctly, sending the right content type, and seeing the response status. A surprising share of API problems are a missing content-type header, where the server rejects a perfectly valid body because it was not told what it was.

The timing breakdown is the underused feature. curl can report how long DNS resolution, connection, TLS handshake and first byte each took, which turns "the API is slow" into a specific answer. That distinction — slow DNS versus slow TLS versus a slow server — points at completely different fixes.

Frequently asked questions

How do I see the response headers and status code?

Include the flag that shows response headers along with the body, or request headers only when the body is irrelevant. For scripting, the write-out option can print just the status code, which is the cleanest way to assert on a response in a shell script or health check.

Why does my request fail with a TLS error?

Usually an untrusted certificate chain, a hostname mismatch, or a missing intermediate certificate that browsers paper over and curl does not. Use verbose mode to see the certificate presented and the negotiated protocol. Disabling verification proves the diagnosis but must never be left in a script — you have removed the guarantee, not fixed the problem.

How do I find out where the time is going?

Use the write-out option with the timing variables, which report DNS lookup, connect, TLS handshake, first byte and total. This separates a slow network path from a slow application, which the total alone cannot. It is the fastest way to disprove "the API is slow" when the real cost is DNS.

How do I send JSON correctly?

Set the content-type header explicitly and pass the body with the data option. Omitting the header sends a form content type, which many APIs reject with a confusing error that does not mention the header. For large or awkwardly quoted payloads, read the body from a file rather than fighting shell escaping.

Does curl follow redirects by default?

No, and that surprises people who expect browser behaviour. Without the follow flag you get the redirect response itself, which is sometimes exactly what you want to see. When following, be careful with credentials — headers are not sent to a different host on redirect unless you explicitly allow it, which is a safety feature rather than a bug.