Getting started
Introduction
curl transfers data with URLs from the command line. This reference covers common HTTP options and recipes, current through curl 8.23.
- curl documentation (curl.se)
- curl man page (curl.se)
Options
-o file # --output: write body to file
-O # --remote-name: use remote filename
-u user:pass # --user: basic authentication
-v # --verbose: show request and response
-s # --silent: hide progress and errors
-S # --show-error: errors even with -s
-i # --include: include response headers
-I # --head: fetch headers only
Use -sS to hide the progress meter but still print errors.
See: curl man page
Request
-X POST # --request: set method
-L # --location: follow redirects
-F name=value # --form: multipart/form-data
-F file=@path # upload a file
-f # --fail: exit 22 on HTTP 4xx/5xx
--fail-with-body # --fail, but keep the response body
--retry 3 # retry transient errors
See: -X, --request
Data
-d 'a=1&b=2' # --data: form-urlencoded body
-d @file # read body from file
-d @- # read body from stdin
--data-binary @file # raw bytes from file
--data-urlencode a=1 # URL-encode a field
-G # --get: append data to query string
--json '{"a": 1}' # JSON POST with headers
--url-query a=1 # append an encoded query parameter
--data does not URL-encode; @file strips newlines. Use --data-urlencode for &/=, or --data-binary @file for exact bytes.
See: -d, --data
Headers
-H 'X-Foo: bar' # --header: add a request header
-A 'agent' # --user-agent
-b name=value # --cookie: send a cookie
-b cookies.txt # --cookie: read a cookie file
-c cookies.txt # --cookie-jar: save cookies
--compressed # request a compressed response
See: -H, --header
TLS
--cacert ca.pem # CA bundle
--capath /etc/ssl # CA directory
--ca-native # add the OS certificate store
-E cert.pem # --cert: client certificate
--cert-type PEM # certificate type
-k # --insecure: skip verification
--ca-native adds the OS trust store; support depends on the TLS backend.
Advanced
Transfers
--no-progress-meter # hide progress, keep errors
--retry 3 # retry transient errors
--retry-all-errors # retry any error
-C - # --continue-at: resume a partial file
--parallel # run transfers in parallel
--rate 10/s # cap request rate
--resolve example.com:443:127.0.0.1 # pin host to an address
--rate has no effect when --parallel is used.
See: --parallel, retries
HTTP versions
--http1.1 # force HTTP/1.1
--http2 # use HTTP/2
--http3 # try HTTP/3, fall back
HTTP/3 needs a curl built with HTTP/3 support.
See: --http3
Variables
--variable host=example.com # set a variable
--variable %TOKEN # import an environment variable
--expand-url 'https://{{host}}/v1'
--expand-data '{{TOKEN:trim}}'
Only --expand-* options expand {{name}}. Functions include trim,
json, url, b64, and 64dec.
See: --variable
Config files
-K curlrc # --config: read options from a file
-K - # read options from stdin
-q # --disable: ignore .curlrc
curl reads $CURL_HOME/.curlrc, $XDG_CONFIG_HOME/curlrc, then
$HOME/.curlrc. Write one option per line, without leading dashes.
See: Config file
Examples
Common recipes
# POST JSON
curl --json '{"name": "Ada"}' https://api.example.com/users
# Upload a file
curl -F name=Ada -F avatar=@photo.jpg https://example.com/upload
# Follow redirects and save the body
curl -fL -o page.html https://example.com
# Check the status code
curl -s -o /dev/null -w '%{http_code}\n' https://example.com
# Download with retries
curl -fL --retry 3 -O https://example.com/file.tar.gz
See: Using curl
0 Comments for this cheatsheet. Write yours!