Basics

Shape of a curl command

curl [options] [URL...]. Options may come before or after the URL, and the default method is GET with the body written to stdout.

curl https://api.example.com/users        # GET, body to stdout
curl -s https://api.example.com/users     # no progress meter
curl -sS https://api.example.com/users    # quiet, but still show errors
curl -i https://api.example.com/users     # headers + body
curl -I https://api.example.com/users     # headers only (HEAD)

Multiple URLs in one invocation reuse the connection. --next (or -:) starts a fresh option set for the URL that follows it, which is how you send two different requests in one process.

curl -s https://a.example.com/ -: -X POST -d x=1 https://b.example.com/

The flag table

Short and long form together, because both get searched. This is the set that covers almost every real invocation.

URL globbing

curl expands {} and [] in URLs unless you pass -g / --globoff. Handy for batches, surprising when a URL legitimately contains a brace.

curl -O "https://ex.com/img[001-010].png"    # 10 downloads
curl "https://ex.com/{users,orgs,repos}"     # 3 requests
curl -g "https://ex.com/search?q=a[0]"       # globbing off, literal

#1 and #2 in an -o template refer to the first and second glob, which is how you name the outputs.

curl "https://ex.com/{a,b}/img[1-3].png" -o "#1-#2.png"

.curlrc

A per-user default option file. One option per line, long form, no leading dashes needed, # comments. Search order is $CURL_HOME/.curlrc, then $XDG_CONFIG_HOME/curlrc, then $HOME/.curlrc.

# ~/.curlrc
silent
show-error
location
compressed
connect-timeout = 10
max-time = 60
user-agent = "curl-local"

Load a different file with -K file / --config file, and skip .curlrc entirely with -q as the first argument.

A .curlrc that sets insecure or silent is a classic debugging trap, because every later curl on that machine behaves differently from the command you pasted into a ticket. Reproduce with curl -q when a result looks wrong.

Exit codes

curl exits 0 on a completed transfer even when the server answered 404. Use -f if a bad status should fail the script.

curl -fsS https://api.example.com/health || echo "health check failed: $?"

--fail-with-body is the variant that still prints the error body, which is usually what you want against a JSON API that explains itself in the 4xx.