Curl Commands — A Cheat Sheet of Everyday Command Lines

The command

curl -sS -L -o response.json -w "%{http_code}\n" https://httpbin.org/json

Everyday curl commands

Task	Command
Fetch a URL	`curl URL`
Show response headers with the body	`curl -i URL`
Print only the status code	`curl -s -o /dev/null -w "%{http_code}" URL`
Send JSON	`curl -H "Content-Type: application/json" -d '{"a":1}' URL`
Send form fields	`curl -d "name=Ada" -d "role=admin" URL`
Upload a file	`curl -F "file=@report.pdf" URL`
Log in with a password	`curl -u user:password URL`
Send a token	`curl -H "Authorization: Bearer TOKEN" URL`
Follow redirects	`curl -L URL`
Download a file under its own name	`curl -LO URL`
Resume an interrupted download	`curl -C - -O URL`
Give up after 20 seconds	`curl --max-time 20 URL`
Show everything curl does	`curl -v URL`

Commands for finding out where the time went

When a request is slow, the total alone does not say why. Curl records a timestamp at each stage and prints them through write-out variables: name lookup, TCP connect, the end of the TLS handshake, the first byte of the response, and the finish. Each value is measured from the start, so the gap between two neighbours is the cost of that stage. A long wait before the first byte with fast earlier stages points at the server, not the network.

curl -s -o /dev/null https://httpbin.org/get -w "dns        %{time_namelookup}s
connect    %{time_connect}s
tls        %{time_appconnect}s
first byte %{time_starttransfer}s
total      %{time_total}s
"

Commands for scripts

An unattended command needs three properties that an interactive one does not. It must stay silent on success yet still print real errors, which is -sS. It must turn an HTTP error into a failing exit status, which is -f. And it must not wait for ever, which is --max-time, with --retry for faults that clear up by themselves. When the script needs to branch on the status code instead, send the body to a file and capture the code in a variable.

# fail loudly, stay quiet otherwise, retry transient errors
curl -fsS --retry 3 --max-time 20 -o data.json https://httpbin.org/json

# body to a file, status code to a variable
status=$(curl -s -o body.json -w "%{http_code}" https://httpbin.org/status/404)
echo "status: $status"

Commands for several requests at once

One curl command can make many requests, and reuses its connection between them. Square brackets in a URL expand to a numeric range and braces to a list; #1 in the output name stands for the current value. --parallel runs the transfers side by side (curl 7.66+). To send requests that differ in more than the URL, separate them with --next, which starts a fresh set of options.

curl -s "https://httpbin.org/anything/page/[1-3]" -o "page_#1.json"
curl -s --parallel --parallel-max 4 "https://httpbin.org/delay/{1,2}" -o "delay_#1.json"
curl -s https://httpbin.org/get --next -s -d "a=1" https://httpbin.org/post

Common mistakes

A copied command brings its quoting style with it. Single-quoted JSON works in bash and zsh and breaks in the Windows command prompt; the Windows page shows the equivalents.
-o and -O overwrite without asking. Check the target name before running a download in a directory that matters.
Flags before --next do not apply after it. Repeat -s, headers and credentials for each group.

Related curl examples

Curl Flags Example

Curl has well over two hundred options.

How to Use Curl

Curl is a command-line program that makes network requests and prints what comes back.

Curl GET Request Example

GET is what curl does when you give it nothing but a URL.

Curl POST JSON Example

Sending JSON takes two things: the JSON itself and a header saying that is what it is.

All Curl Examples

49 worked examples, grouped by what you are trying to do.

More under Reference

References

curl man page — The reference to check before trusting any cheat sheet, this one included.
curl man page: -w — Every --write-out variable, including the timing ones.
curl man page: --parallel — Running transfers side by side.

These links leave api-tester.com, which is independent of the projects they point to.

FAQ

What are the basic curl commands?

curl URL fetches a page, curl -i URL adds the response headers, curl -d "data" URL sends a POST, curl -H "Name: value" URL adds a header, curl -L URL follows redirects and curl -O URL downloads a file.

How do I see how long a curl request takes?

Use -w with timing variables, for example curl -s -o /dev/null -w "%{time_total}" URL. Variables such as time_namelookup, time_connect and time_starttransfer break the total into stages.

How do I run several curl requests in one command?

List several URLs after curl, put a range such as [1-10] in the URL, or separate differently configured requests with --next. Add --parallel to run them at the same time.