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

  • -d already implies POST; -X GET with -d produces an awkward GET-with-body
  • A -d value starting with @ reads a file — use --data-raw to send it as text
  • -d alone 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
  • -k is not a tool for silencing errors, and -L can change how a POST behaves
  • In scripts, set --connect-timeout and --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.