The cURL Flags That Actually Matter

Of curl's roughly 230 options, about fifteen carry the entire internet. Learn these and you can read any "copy as cURL" from devtools, and our converter will handle the mapping to your language.

The request shape

• -X POST — method. Suspicious when present: if it's missing, curl inferred POST from -d.
• -H 'Key: value' — headers, repeatable. -H 'Content-Type: application/json' is the one that trips everyone; with -d, curl defaults to application/x-www-form-urlencoded, so the API sees a form POST you meant to be JSON.
• -d / --data-raw / --data-urlencode — body. -d mangles characters (@ reads a file, % is untouched); --data-raw sends your text byte-for-byte.
• -G — pairs with -d to turn the data into a query string on a GET. This is the flag that makes -d on a GET legitimate. See GET with a body for why that shape exists.

The transport details

• --compressed — asks for gzip/brotli. Without it you can time a slow API, conclude the server is slow, and be timing an uncompressed 4MB response.
• -L — follow redirects. Without it, a 301 from an HTTP endpoint gives you the redirect page, and your parse silently succeeds on the wrong document.
• --connect-timeout 5 --max-time 30 — CI scripts need both. Without them a hung TCP handshake waits 130+ seconds, and your pipeline's "timeout" fires at the wrong layer.
• -k / --insecure — skips TLS verification. Useful for a lab, indefensible in production; the fix for a self-signed cert is the CA bundle, --cacert.

The output details

• -i / -D - — response headers. Half of "it worked in curl" complaints are people not looking at the status line; -i forces you to see a 400 before the body pretends to be success.
• -s — silence. Combine with -S to keep errors visible while hiding the progress meter: the two flags together are the correct answer to 90% of "curl is noisy" advice.
• -w '%{http_code}\n' — status code alone, for when you just want to assert.
• --fail-with-body — non-zero exit on HTTP errors, and keeps the body printed. Old-timers say -f; -f hides the error body, which is the only interesting part.

One more: devtools "Copy as cURL" emits --compressed and -H 'Accept: */*' in places you wouldn't. The converter strips the noise where it's safe; when it keeps something, it's because the flag changed the response.

FAQ

Do I need -X GET for GET requests? No. GET is curl's default and -X GET is a no-op at best — on some servers an explicit method on a cacheable request defeats caching. Drop it.

Why does my -d payload start with a filename? Because -d treats a leading @ as "read this file." If your body legitimately starts with @, use --data-raw.

What's the minimum flag set for CI? -sS --fail-with-body --connect-timeout 5 --max-time 30 -w '\n%{http_code}\n'. Silent, loud about failures, bounded in time, and assertable.