AdSense Placeholder
Slot: header_reference_page
curl transfers data to and from URLs from the command line. Every flag below exists in curl 8.18 (curl --help all), and the headers each one sends were checked against a local echo server. Build commands visually with the curl Command Builder, or turn one into Python, JavaScript or Go with the curl to Code Converter. Examples use https://api.example.com.
Request method and body
| Flag |
Long form |
Does |
Example |
-X |
--request |
Sets the method |
curl -X DELETE https://api.example.com/items/7 |
-d |
--data |
Sends a body; implies POST and Content-Type: application/x-www-form-urlencoded |
curl -d 'a=1&b=2' https://api.example.com/form |
|
--data-raw |
Like -d, but a leading @ is not read as a file name |
curl --data-raw '@not-a-file' ... |
|
--data-binary |
Sends the data exactly, keeping newlines |
curl --data-binary @dump.bin ... |
|
--data-urlencode |
URL-encodes the value |
curl --data-urlencode 'q=a b&c' ... |
|
--json |
Sends JSON: POST, Content-Type and Accept: application/json |
curl --json '{"name":"Ana"}' https://api.example.com/users |
-F |
--form |
Multipart form (file uploads) |
curl -F '[email protected]' -F 'title=Hi' ... |
-G |
--get |
Puts the -d data in the query string and uses GET |
curl -G -d q=test https://api.example.com/search |
|
--url-query |
Adds an encoded query parameter |
curl --url-query 'q=a+b' ... → ?q=a%2bb |
-T |
--upload-file |
Uploads a file with PUT |
curl -T report.pdf https://files.example.com/ |
-I |
--head |
Sends HEAD: headers only |
curl -I https://example.com |
-d @file reads the body from a file and strips newlines; use --data-binary @file to send it untouched. -X POST is never needed alongside -d, --json or -F.
Headers, auth and cookies
| Flag |
Long form |
Does |
Example |
-H |
--header |
Adds or replaces a header (Name: with nothing after removes it) |
-H 'Authorization: Bearer TOKEN' |
-A |
--user-agent |
Sets User-Agent |
-A 'MyAgent/1.0' |
-e |
--referer |
Sets Referer |
-e https://example.com/ |
-u |
--user |
Basic authentication (user:password) |
-u alice:s3cret |
|
--oauth2-bearer |
Sends Authorization: Bearer |
--oauth2-bearer TOKEN |
-b |
--cookie |
Sends cookies, or reads them from a file |
-b 'session=abc', -b cookies.txt |
-c |
--cookie-jar |
Saves received cookies to a file |
-c cookies.txt |
|
--compressed |
Asks for and decompresses gzip, deflate, brotli, zstd |
--compressed |
-n |
--netrc |
Reads credentials from ~/.netrc |
-n |
Responses and output
| Flag |
Long form |
Does |
-i |
--show-headers |
Prints response headers before the body (--include is the older name) |
-D |
--dump-header |
Writes response headers to a file (-D - for the terminal) |
-o |
--output |
Saves the body to a file |
-O |
--remote-name |
Saves under the file name from the URL |
-J |
--remote-header-name |
With -O, uses the name from Content-Disposition |
|
--create-dirs |
Creates missing directories for -o |
-C |
--continue-at |
Resumes a download (-C - works out the offset) |
-r |
--range |
Requests only a byte range: -r 0-99 |
-s |
--silent |
No progress meter or error messages |
-S |
--show-error |
With -s, still shows errors |
-f |
--fail |
Exits with code 22 and no body on HTTP 400 and above |
|
--fail-with-body |
Like -f but still saves the body |
-w |
--write-out |
Prints variables after the transfer |
-# |
--progress-bar |
Simple progress bar instead of the meter |
Redirects, retries and timeouts
| Flag |
Long form |
Does |
-L |
--location |
Follows redirects |
|
--max-redirs |
Limits the number of redirects followed |
-m |
--max-time |
Maximum total time in seconds |
|
--connect-timeout |
Maximum time to connect |
|
--retry |
Retries transient failures N times |
|
--retry-delay |
Seconds between retries |
|
--retry-all-errors |
Retries on every error, not just transient ones |
|
--limit-rate |
Caps the speed: --limit-rate 500K |
-Z |
--parallel |
Runs several URLs at once |
See every hop of a redirect chain, with status codes, in the HTTP Redirect Chain Tracer.
Connection, TLS and proxies
| Flag |
Long form |
Does |
-k |
--insecure |
Skips certificate verification (testing only) |
|
--cacert |
Trusts a specific CA bundle |
|
--cert / --key |
Client certificate and key (mutual TLS) |
|
--tlsv1.2 |
Requires at least TLS 1.2 (--tls-max sets the ceiling) |
|
--http1.1 / --http2 / --http3 |
Chooses the HTTP version |
-4 / -6 |
--ipv4 / --ipv6 |
Resolves names to IPv4 or IPv6 only |
|
--resolve |
Pins a host to an IP: --resolve example.com:443:192.0.2.10 |
|
--connect-to |
Sends the request to another host and port |
-x |
--proxy |
Uses a proxy: -x http://proxy.example.com:3128 |
|
--noproxy |
Hosts that bypass the proxy |
|
--unix-socket |
Connects through a Unix socket (Docker API) |
Debugging and timing
| Flag |
Long form |
Does |
-v |
--verbose |
Shows the request and response headers and the TLS handshake |
|
--trace-ascii |
Logs everything sent and received to a file |
|
--trace-time |
Adds timestamps to verbose and trace output |
-K |
--config |
Reads options from a file |
Useful -w variables: %{http_code}, %{time_namelookup}, %{time_connect}, %{time_starttransfer}, %{time_total}, %{size_download}, %{url_effective}, %{remote_ip}.
Recipes
| Task |
Command |
| Status code only |
curl -s -o /dev/null -w '%{http_code}\n' https://example.com |
| Timing breakdown |
curl -s -o /dev/null -w 'dns %{time_namelookup} connect %{time_connect} ttfb %{time_starttransfer} total %{time_total}\n' https://example.com |
| Headers only, following redirects |
curl -sIL https://example.com |
| POST JSON with a token |
curl --json '{"q":"test"}' -H 'Authorization: Bearer TOKEN' https://api.example.com/search |
| Download, resuming if interrupted |
curl -L -C - -O https://example.com/file.iso |
| Test a server before DNS changes |
curl --resolve example.com:443:203.0.113.10 https://example.com |
| Fail a script on HTTP errors |
curl -fsS https://api.example.com/health |
Quote URLs that contain & or ? in the shell, and percent-encode special characters in query values with the URL Encode tool. To check a site's headers without a terminal, use the HTTP Headers Viewer.