Tools mentioned in this article
Open the browser-based tool while you read and try the workflow immediately.
Reading a pasted curl command makes API work faster
A curl command copied from documentation or your browser’s dev tools usually looks like this:
curl -X POST 'https://api.example.com/v1/items?limit=10' \
-H 'Authorization: Bearer TOKEN' \
-H 'Content-Type: application/json' \
-d '{"name":"Alice","tags":["a","b"]}'
Simple enough once you can read it — but a few option combinations change the behaviour, and not knowing them leads to “the same command doesn’t work here”. This is a reference for the common options plus the places people actually get caught.
curl options list (by purpose)
The options you will meet most often, grouped by what they do. To see everything your build supports, run curl --help all (full list), curl --help category (list of categories) or man curl (details).
Building the request
| Option | Meaning |
|---|---|
-X, --request |
Set the HTTP method (GET / POST / PUT / DELETE) |
-H, --header |
Add a request header; repeatable |
-A, --user-agent |
Set the User-Agent header |
-e, --referer |
Set the Referer header |
-b, --cookie |
Send cookies |
-c, --cookie-jar |
Save received cookies to a file |
-u, --user |
Basic auth (user:password) |
-G, --get |
Put the -d data in the URL query string instead of the body |
Sending data
| Option | Meaning |
|---|---|
-d, --data |
Send a request body. Implies POST |
--data-raw |
Same as -d but does not treat a leading @ as a filename |
--data-binary |
Send the data exactly as given, keeping newlines (files, binary) |
--data-urlencode |
Percent-encode the value before sending |
-F, --form |
Send as multipart/form-data (file uploads) |
-T, --upload-file |
Upload a file (a PUT over HTTP) |
--json |
Send JSON and set Content-Type and Accept too (curl 7.82+) |
Handling the response
| Option | Meaning |
|---|---|
-o, --output |
Write the response to a file |
-O, --remote-name |
Save using the filename from the URL |
-i, --include |
Include response headers in the output |
-I, --head |
Send HEAD and show only headers |
-D, --dump-header |
Write the response headers to a file |
-w, --write-out |
Print details such as %{http_code} when finished |
-r, --range |
Request a byte range (for example 0-99) |
-C - |
Resume a partly downloaded file |
--compressed |
Ask for a compressed transfer (gzip etc.) |
Output and errors
| Option | Meaning |
|---|---|
-s, --silent |
Hide the progress meter |
-S, --show-error |
With -s, still show errors |
-v, --verbose |
Show the full exchange, including request headers |
-f, --fail |
On HTTP 400 or above, print no body and exit with code 22 |
-#, --progress-bar |
Show progress as a bar |
Connection, timeouts and redirects
| Option | Meaning |
|---|---|
-L, --location |
Follow redirects (3xx) |
--max-redirs |
Maximum number of redirects to follow |
--connect-timeout |
Seconds to wait for the connection |
-m, --max-time |
Maximum total seconds; the transfer is aborted after this |
--retry |
Number of retries on transient errors |
-x, --proxy |
Connect through a proxy |
--resolve |
Resolve a host name to a given IP (host:port:address), handy for testing a new server without changing DNS |
-4, -6 |
Use only IPv4 / IPv6 |
-g, --globoff |
Do not expand [] and {} in the URL |
TLS (HTTPS)
| Option | Meaning |
|---|---|
-k, --insecure |
Skip server certificate verification |
--cacert |
CA certificate file to verify against |
-E, --cert / --key |
Client certificate and private key |
-X POST is usually redundant
Adding -d already makes the request a POST. These two are identical:
curl -X POST https://api.example.com/items -d '{"a":1}'
curl https://api.example.com/items -d '{"a":1}'
The problem is the opposite case. -X GET together with -d produces a GET request with a body — something proxies and servers may ignore or reject, which is a classic “works locally, fails in production” cause.
Note also that repeating -d joins the values with &. Handy for form posts, fatal for JSON:
# Not what you want: sends {"a":1}&{"b":2}
curl -d '{"a":1}' -d '{"b":2}' https://api.example.com/items
A leading @ in -d reads a file
When the value passed to -d starts with @, curl reads that file and sends its contents:
curl -d @payload.json https://api.example.com/items # sends the file contents
Useful — until you pass a username or handle verbatim:
# Intent: send the string "@alice"
# Reality: curl looks for a file called ./alice and errors if it's missing
curl -d '@alice' https://api.example.com/items
To send a value containing @ literally, use --data-raw, which gives @ no special meaning.
The Content-Type does not become JSON on its own
With -d, curl sends Content-Type: application/x-www-form-urlencoded unless you say otherwise. Send JSON without the header and the server fails to parse it:
curl -H 'Content-Type: application/json' \
-d '{"name":"Alice"}' https://api.example.com/items
curl 7.82 and later offer --json, which sets both Content-Type: application/json and Accept: application/json. Older environments don’t have it, so spell the header out in commands you intend to share.
Quoting causes more failures than anything else
| Style | Behaviour |
|---|---|
'...' (single) |
Passes $ and " through untouched. Use this for JSON |
"..." (double) |
The shell expands $variables |
JSON contains double quotes, so the outer quoting should be single:
# Fine
curl -d '{"name":"Alice"}' https://api.example.com/items
# The shell strips the inner quotes and the body breaks
curl -d "{"name":"Alice"}" https://api.example.com/items
When you need a token from an environment variable, mix the two deliberately:
curl -H "Authorization: Bearer $TOKEN" \
-d '{"name":"Alice"}' https://api.example.com/items
Windows Command Prompt does not treat single quotes as quoting at all, and in PowerShell curl may be an alias for Invoke-WebRequest. Call curl.exe explicitly, or run the command in WSL or Git Bash.
Which data option to use
The -d family differs in what gets transformed before sending.
| Option | Transformation | Best for |
|---|---|---|
-d |
A value starting with @ reads a file; newlines in the file are stripped |
Forms, short JSON |
--data-raw |
@ is not special |
Sending a string that contains @ as-is |
--data-binary |
Sent exactly as given, newlines included | Files where newlines matter, binary data |
--data-urlencode |
Percent-encodes the value | Non-ASCII text or symbols in form values and queries |
-F |
Sent as multipart/form-data |
File uploads |
Use -d @payload.json to read a file and -d @- to read standard input. For a JSON file whose newlines you want preserved, or for binary data, use --data-binary @file.
Timeouts and retries
When curl runs from a script, set time limits so it never waits forever:
curl --connect-timeout 5 --max-time 30 --retry 3 https://api.example.com/items
--connect-timeout: seconds to wait for the connection-m, --max-time: seconds for the whole transfer. Allow more for large downloads--retry: how many times to retry on a timeout or certain HTTP errors (429, 502, 503, 504 and similar)
By default, curl exits with 0 even when the server returns 404 or 500. To detect failure in a script, add -f:
curl -fsS https://api.example.com/health || echo "failed"
To get just the status code, use -w:
curl -s -o /dev/null -w '%{http_code}\n' https://example.com/
On Windows, write NUL instead of /dev/null. -w also supports variables such as %{time_total} (total seconds).
Common exit codes
A guide for checking $? in scripts (the full list is under “EXIT CODES” in man curl).
| Code | Meaning |
|---|---|
| 0 | Success |
| 6 | Could not resolve host |
| 7 | Failed to connect |
| 22 | HTTP 400 or above (with -f) |
| 28 | Timeout |
| 35 | TLS handshake failed |
| 60 | Server certificate could not be verified |
Using curl.exe on Windows
Windows 10 (version 1803) and later ship with curl.exe. The options are the same as on Linux and macOS, but the way you write the command depends on the shell.
| Item | Command Prompt (cmd) | PowerShell |
|---|---|---|
| Calling it | curl / curl.exe |
Write curl.exe (curl can be an alias for Invoke-WebRequest) |
| Quotes | Double quotes only (single quotes do not work) | Single or double, but inner " can get stripped |
| Line continuation | ^ |
Backtick ` |
In cmd, escape the double quotes inside JSON with \":
curl.exe -X POST -H "Content-Type: application/json" -d "{\"name\":\"Alice\"}" https://api.example.com/items
PowerShell also mangles JSON quotes easily, so the reliable way is to put the JSON in a file and pass it with -d @body.json:
curl.exe -X POST -H "Content-Type: application/json" -d "@body.json" https://api.example.com/items
If in doubt, run the command from WSL or Git Bash, where single quotes work and the examples in this article can be used as they are.
Quote URLs that contain &
Paste a multi-parameter URL unquoted and the shell reads & as “run in background”, truncating the command:
# Broken: only limit=10 is sent
curl https://api.example.com/items?limit=10&offset=20
# Correct
curl 'https://api.example.com/items?limit=10&offset=20'
Values with spaces or non-ASCII characters need percent-encoding. You can check an encoding with the URL encoder/decoder, or let curl build the query string safely with -G and --data-urlencode:
curl -G https://api.example.com/search --data-urlencode 'q=hello world'
Two options worth hesitating over
-k / --insecure disables certificate verification. It has a place when testing a self-signed certificate locally, but the classic incident is adding it to silence an error and leaving it in a shared or production command. Fix certificate problems at the certificate.
-L / --location follows redirects. Convenient, but the method and body handling on a redirected POST can change; pin the behaviour with --post301, --post302 or --post303 when it matters.
Turning the command into code
Once you’ve read a curl command, transcribing headers and bodies by hand into your application is error-prone. Paste it into the cURL converter to get request code for JavaScript, Python, Go and others — the quoting and header splitting are handled for you.
For formatting or validating the JSON you’re sending, use the JSON formatter; to inspect a query string, URL parameters to JSON. Everything runs in your browser, so a command containing an auth token is never transmitted anywhere.
Summary
-dalready implies POST;-X GETwith-dproduces an awkward GET-with-body- A
-dvalue starting with@reads a file — use--data-rawto send it as text -dalone means form encoding. For JSON, set the header or use--json(curl 7.82+)- Use single quotes around JSON; double quotes only where you need variable expansion
- Quote URLs containing
&; build encoded queries with-G --data-urlencode -kis not a tool for silencing errors, and-Lcan change how a POST behaves- In scripts, set
--connect-timeoutand--max-time, and use-f(exit code 22) to detect HTTP errors - On Windows, write
curl.exe; for JSON, put it in a file and pass-d @body.json
FAQ
How do I list all curl options?
Run curl --help all for every option, or curl --help category for the categories. man curl has the full descriptions. On Windows, use curl.exe --help all. The “curl options list (by purpose)” tables above cover the ones you will use most.
What is the difference between curl and curl.exe?
In Windows PowerShell, curl can be an alias for Invoke-WebRequest, which has different options. Write curl.exe to call the real curl. In Command Prompt, either name runs curl.exe.
curl exits with 0 even on a 404. Can I make it fail?
Add -f (--fail): on HTTP 400 or above curl prints no body and exits with code 22. It is useful for detecting failures in scripts. Pair it with --connect-timeout and --max-time so it cannot hang.
Do I need to write -X POST?
Usually not — adding -d or -F makes the request a POST automatically. Writing it anyway documents intent, which is worth something in a shared command. What to avoid is -X GET combined with -d: that is a GET with a body, and some servers and proxies ignore or reject it.
What is the difference between -d and --data-raw?
Only the handling of a leading @. With -d, a value starting with @ is treated as a filename and the file’s contents are sent; --data-raw sends the string as-is. Use --data-raw for data that legitimately contains @, such as an email address.
I sent JSON but the server won’t parse it
With -d, the default Content-Type is application/x-www-form-urlencoded, so you need -H 'Content-Type: application/json'. On curl 7.82 or later, --json sets the header for you.
The command doesn’t work on Windows
Command Prompt does not interpret single quotes, and PowerShell may alias curl to Invoke-WebRequest. Either call curl.exe explicitly or run the command from a shell that handles single quotes, such as WSL or Git Bash.
Is it safe to paste a command containing an auth token?
The cURL converter runs entirely in your browser and nothing you paste is transmitted. Do note that the converted code still contains the token, so move it to an environment variable before committing the code.
