Command builder
curl command builder and explainer
For the things you only do occasionally — inspect a response, download a file, or call an API. Build a command from options, or Explain one you've been handed. Quoting is correct for your shell.
Save to disk
Most download links redirect — keep Follow redirects on above. -O needs a filename in the URL; if the URL has none, pick “Choose a filename” instead.
Upload a file
-T sends the file's raw bytes as a PUT (no -X needed). If the URL ends in /, curl appends the filename — e.g. -T report.pdf https://host/uploads/ uploads to …/uploads/report.pdf. This is different from -F (multipart form upload) over in Call an API.
Response & inspection
Headers & identity
Custom headers
Authentication
Request body
Form fields (value @path uploads a file)
CORS preflight
Caching / conditional
TLS & connection
Resolve host to a specific IP --resolve (test a CDN edge / staging server)
Windows PowerShell 5.1, the version built into Windows, strips the double quotes inside this command, so a JSON body arrives as {name:boga} and the API rejects it. PowerShell 7.3 and later are fine. On 5.1, save the JSON as body.json and send it with -d '@body.json' instead.
Build or explain
Two tabs at the top. Build a command assembles one from options. Explain a command goes the other way — paste a curl command someone handed you (from a README, a Stack Overflow answer, your browser's “Copy as cURL”) and it breaks down the method, the URL and every flag in plain language. It covers the ~50 most common flags; anything it doesn't recognise is marked rather than guessed at, and it assumes bash/zsh quoting.
The four modes
curl really does a few different jobs, and they barely overlap — so the tool leads with them. The difference is what flows where: Inspect prints the response to your terminal (headers, redirects, timing); Download writes the response to a file on disk; Upload sends a local file up to the server; Call an API is about sending structured data (JSON, forms, auth) and reading the reply. They conflict on purpose — you can't both print headers only and save the body to a file — which is why picking a mode swaps the relevant options in and out. Headers, auth and TLS settings stay available in every mode.
Downloading: -o vs -O
The classic trap. -O (capital O) saves the file using the name from the URL — curl -O https://x.com/report.pdf writes report.pdf. -o name (lowercase o) saves to a filename you choose — curl -o my.pdf https://x.com/report.pdf. Mnemonic: lowercase -o = the output name is yours; capital -O = use the Original name. Companions: -J honours a filename the server suggests (via Content-Disposition, pairs with -O); -C - resumes a half-finished download; --output-dir picks the folder; and almost every download link redirects, so keep -L on. Note -O fails if the URL ends in a slash with no filename — choose a name instead.
Uploading: -T
-T file is the mirror image of -O: it sends a local file to the URL as the raw request body, which curl turns into a PUT (so no -X is needed). If the URL ends in /, curl appends the local filename — curl -T report.pdf https://host/uploads/ PUTs to …/uploads/report.pdf. Don't confuse it with -F field=@file (a multipart form upload, like an HTML form) or -d @file (posts the file's text as the body) — -T is the plain "PUT this file" upload used by REST APIs, S3-style stores and WebDAV.
Common curl commands
The tasks people look up most, each with the command to copy. The recipe buttons in the builder above fill in most of them for you.
All of these on one printable page: curl cheat sheet (PDF, A4).
Show only the response headers
-I sends a HEAD request and prints just the headers; -i (lowercase) prints the headers plus the body. Don't use -X HEAD: it can hang waiting for a body that never comes.
curl -I 'https://example.com'
Follow redirects
curl doesn't follow redirects by default. -L does, and with -I and -s you see every hop's status and headers. For a visual trace, use the redirect checker.
curl -sIL 'http://example.com'
Send JSON (POST)
The most common mistake is forgetting Content-Type: application/json. -d already makes it a POST, so -X POST isn't needed. curl 7.82 and later also have --json, which sets the content type and Accept header for you.
curl -H 'Content-Type: application/json' \
-d '{"name":"boga"}' \
'https://api.example.com/users' Send a bearer token
For APIs that use OAuth or JWT tokens. To see what's inside a token, paste it into the JWT decoder.
curl -H 'Authorization: Bearer YOUR_TOKEN' 'https://api.example.com/users'
Log in with a username and password
Basic auth. Write just -u user and curl asks for the password, so it doesn't end up in your shell history.
curl -u 'user:password' 'https://api.example.com/users'
Download a file
-O keeps the file's own name; -o name picks yours (more below). -L because download links usually redirect.
curl -LO 'https://example.com/report.pdf'
Upload a file
Sends the file as the request body with PUT. Details below.
curl -T 'report.pdf' 'https://example.com/uploads/'
Test a new server before switching DNS
--resolve sends the request to a specific IP but keeps the real host name, so HTTPS and virtual hosts behave as they will after the switch.
curl -I \ --resolve 'example.com:443:203.0.113.10' \ 'https://example.com'
Test CORS (preflight)
Reproduces the OPTIONS request a browser sends before certain cross-origin calls. The Access-Control-Allow-* headers in the reply show what the server permits.
curl -i \ -X OPTIONS \ -H 'Origin: https://app.example.com' \ -H 'Access-Control-Request-Method: POST' \ -H 'Access-Control-Request-Headers: Content-Type' \ 'https://api.example.com/users'
Test caching (304 Not Modified)
Send the ETag you got back as If-None-Match. A 304 Not Modified confirms revalidation works; check Cache-Control, Age and CDN headers such as CF-Cache-Status too.
curl -I \ -H 'If-None-Match: "abc123"' \ 'https://example.com/style.css'
Time a request
Prints DNS, connect, TLS, time to first byte and total time: a quick answer to "why is this slow?".
curl -s \
-o /dev/null \
-w 'DNS %{time_namelookup}s Connect %{time_connect}s TLS %{time_appconnect}s TTFB %{time_starttransfer}s Total %{time_total}s\n' \
'https://example.com' See everything curl sends and receives
-v prints the request and response headers and the TLS handshake. For a full byte-level log, use --trace-ascii trace.txt.
curl -v 'https://example.com'
The same curl command in bash, PowerShell and CMD
One request, a JSON POST, written for each shell by the builder above. Pasting a bash command into a Windows shell is the most common reason a copied curl command fails.
bash / zsh (macOS, Linux, WSL, Git Bash)
curl -H 'Content-Type: application/json' \
-d '{"name":"boga"}' \
'https://api.example.com/users' PowerShell
curl.exe -H 'Content-Type: application/json' `
-d '{"name":"boga"}' `
'https://api.example.com/users' CMD (Command Prompt)
curl -H "Content-Type: application/json" ^
-d "{\"name\":\"boga\"}" ^
"https://api.example.com/users" - bash / zsh: single quotes keep everything inside them literal, so JSON pastes as-is. A backslash (
\) continues the command on the next line. - PowerShell: the program is written
curl.exe, because in Windows PowerShell 5.1 (the version built into Windows)curlis an alias forInvoke-WebRequest, a different command. A backtick (`) continues the line and the null device isNUL. One trap: Windows PowerShell 5.1 strips the double quotes inside arguments it hands to programs, so the JSON arrives as{name:boga}and the API rejects it. PowerShell 7.3 and later pass it through correctly. On 5.1, save the JSON in a file and send it with-d '@body.json'(quoted, because PowerShell reads a leading@as its own syntax). - CMD: there are no single-quoted strings, so every value goes in double quotes and inner quotes become
\". A caret (^) continues the line, and the null device isNULinstead of/dev/null.
Two security notes
-k (skip TLS verification) defeats the point of HTTPS — use it only against known staging/self-signed hosts, never in scripts that touch real data. On a redirect to a different host, curl drops the Authorization header on purpose so your token can't leak to another origin.
Questions about curl
Is curl available on Windows?
Yes. Windows 10 (version 1803 and later) and Windows 11 include curl.exe, so it works in Command Prompt and PowerShell without installing anything.
How do I copy a request from my browser as curl?
Open the developer tools (F12), go to the Network tab, right-click the request and choose Copy → Copy as cURL. On Windows, Chrome and Edge offer a bash and a CMD version; take the bash one to paste into the Explain tab above, which reads bash quoting.
How do I send form data instead of JSON?
For a classic web form, use -d 'name=boga&lang=en': it's sent like a submitted HTML form (application/x-www-form-urlencoded). To upload a file the way a form's file field does, use -F 'file=@photo.jpg' (multipart/form-data).
Why does my POST turn into a GET after a redirect?
With -L, curl behaves like a browser: after a 301, 302 or 303 it repeats the request as a GET, without the body. Add --post301 or --post302 to keep the POST for those redirects; a 303 is meant to switch to GET.
How do I ignore SSL certificate errors?
-k (--insecure) skips the certificate check. It's acceptable for a quick look at a staging server with a self-signed certificate, never in scripts that handle real data. Better: point curl at the right certificate with --cacert ca.pem, so the connection stays verified.
How do I set a timeout?
--connect-timeout 5 limits how long curl waits for the connection; --max-time 30 limits the whole request. Both are in seconds, and both are options in the builder.
Related tools
- Redirect checker: trace a redirect chain hop by hop without a terminal.
- HTTP header checker: response headers grouped by purpose, with a security grade.
- JWT decoder: see what's inside the bearer token you're sending.
- URL parser & decoder: encode query parameters before putting them in a curl URL.
Sources & references
- everything.curl.dev — the curl bookcurl project
- curl man pagecurl.se
- Cross-Origin Resource Sharing (CORS)MDN
- HTTP cachingMDN