Skip to content

curl Flags Explained

The curl flags used day to day, grouped by job: shape the request, set headers, authenticate, present an identity, control output, follow redirects, tune the connection, and debug. Each row pairs the flag with a realistic invocation.

curl sends an HTTP request and prints the response body. Most of its power is in the flags: they choose the method, attach headers and data, handle auth, and decide what gets printed. The long form is shown where it is clearer; the short form is the single letter. Put URLs in quotes so the shell does not eat the query string.

Reference table · 54 entries
54 of 54 rows
Request shape
Set the HTTP method.curl -X POST https://api.test
Add a request header.curl -H "Accept: application/json" URL
Send a body (sets POST and a default content type).curl -d "name=Ada" URL
Append -d values as query params onto a GET.curl -G -d "q=hi" URL
Send multipart form data (file uploads).curl -F "file=@photo.png" URL
Send form data with URL encoding applied.curl --data-urlencode "name=Ada Lovelace" URL
Upload a file with PUT.curl -T big.zip URL
Append an upload to the remote file instead of replacing it.curl -a -T log.txt ftp://server.test/logs/log.txt
JSON & APIs
Send JSON with the correct content type.curl -H "Content-Type: application/json" -d '{"a":1}' URL
Send the contents of a file as the body.curl -d @body.json URL
Send JSON without setting the headers by hand (curl 7.82+).curl --json '{"a":1}' URL
Auth
HTTP Basic auth with user and password.curl -u ada:s3cr3t URL
Send an OAuth bearer token.curl --oauth2-bearer TOKEN URL
Send any token scheme by hand.curl -H "Authorization: Bearer TOKEN" URL
Present a client certificate and its key for mutual TLS.curl --cert client.pem --key key.pem URL
Verify the server against one CA bundle file.curl --cacert ca.pem URL
Verify the server against a directory of CAs.curl --capath /etc/ssl/certs URL
Send the request through a proxy.curl -x http://proxy.test:8080 URL
Skip TLS verification for the proxy hop only.curl -x https://proxy.test:8443 --proxy-insecure URL
Require TLS 1.3 as the minimum version.curl --tlsv1.3 URL
Identity
Send a custom User-Agent string.curl -A "Mozilla/5.0" URL
Send a Referer header.curl -e https://example.com/page URL
Send cookies with the request.curl -b "session=abc123" URL
Save response cookies to a file.curl -c cookies.txt URL
Output
Write the body to a file.curl -o page.html URL
Save the body using the remote file name.curl -O https://site/file.tgz
Print response headers above the body.curl -i URL
Fetch headers only (sends HEAD).curl -I URL
Hide the progress meter and errors.curl -s URL
Print a format string after the body (timing, status).curl -w "%{http_code}\n" -o /dev/null URL
Exit non-zero on HTTP errors and skip the error body.curl -f URL
Exit non-zero on HTTP errors but still print the body.curl --fail-with-body URL
Name the saved file from the Content-Disposition header.curl -OJ URL
Resume an interrupted transfer from where it stopped.curl -C - -O URL
Show a progress bar instead of the default meter.curl -# -O URL
Print errors even when running silent.curl -sS URL
Write the response headers to a file.curl -D headers.txt URL
Ask for a compressed response and decode it.curl --compressed URL
Create missing directories in the -o path.curl -o cache/api/data.json --create-dirs URL
Redirects & connection
Follow 3xx redirects.curl -L URL
Max seconds to wait for the TCP connect.curl --connect-timeout 5 URL
Max seconds for the whole request.curl --max-time 30 URL
Skip TLS certificate verification.curl -k https://self-signed.test
Retry transient errors up to N times.curl --retry 3 URL
Retry on any error, not just transient ones.curl --retry 3 --retry-all-errors URL
Force the connection over IPv4 or IPv6.curl -4 URL
Map a host and port to an address, bypassing DNS.curl --resolve api.test:443:127.0.0.1 https://api.test
Bind the transfer to a network interface or address.curl --interface eth0 URL
Transfer multiple URLs at the same time.curl -Z URL1 URL2
Use HTTP/2 or HTTP/3 for the transfer.curl --http3 URL
Stream the body as it arrives instead of buffering.curl -N URL
Read further flags from a config file.curl -K flags.cfg URL
Debug
Print the full request and response exchange.curl -v URL
Hex-dump everything sent and received.curl --trace - URL