curl Cheat Sheet

curl -LO https://example.com/file.tar.gz          # download, keep remote name
curl -I https://example.com                       # response headers only
curl -sS https://api.example.com/v1/items | jq    # quiet, but still show errors
curl --json '{"name":"x"}' https://api.example.com/v1/items   # POST JSON
curl -H "Authorization: Bearer $TOKEN" https://api.example.com/v1/me
curl -v https://example.com -o /dev/null          # debug the connection and TLS

Syntax: curl [options] URL.... By default curl does a GET and writes the body to standard output, with a progress meter on standard error when output is redirected. It is preinstalled on Ubuntu, Fedora and most other distros; otherwise install the curl package with apt, dnf, pacman or zypper. Check your version with curl --version, since a few options below need a recent release.

Downloading

Requests, headers and data

Authentication and cookies

Output, debugging and timing

Connections, TLS, proxies and retries

Common recipes

Check a list of URLs and print status code and total time:

while read -r u; do
  curl -o /dev/null -sS -w "%{http_code} %{time_total}s $u\n" --max-time 10 "$u"
done < urls.txt

Show a site's certificate dates and issuer (the SSL expiry check script automates this):

curl -vsI https://example.com 2>&1 | grep -E 'expire date|start date|issuer|subject:'

Call a JSON API, fail on HTTP errors and extract a field:

curl -fsS -H "Authorization: Bearer $TOKEN" https://api.example.com/v1/user | jq -r '.login'

Test a new server before switching DNS:

curl -sI --resolve www.example.com:443:203.0.113.10 https://www.example.com | head -5

Find your public IP address:

curl -s https://ifconfig.me; echo

Query a local API on a Unix socket (Docker):

curl -s --unix-socket /var/run/docker.sock http://localhost/version | jq .Version

Download and verify before running an installer, instead of piping to a shell:

curl -fsSLo install.sh https://example.com/install.sh
less install.sh          # read it
sha256sum install.sh     # compare with the published checksum
bash install.sh

Gotchas

• No redirects by default. Without -L you save a tiny HTML redirect page instead of the file.
• HTTP errors exit 0. A 404 or 500 is a successful transfer to curl. Use -f (or --fail-with-body) in scripts.
• -d switches to POST. Adding -X POST as well is redundant, and -X GET -d ... sends a body with GET, which many servers ignore. Use -G for query strings.
• Shell quoting. Use single quotes around JSON so the shell leaves $ and " alone; use double quotes only when you need a variable expanded, or put the body in a file with -d @file.
• curl | sudo bash runs code you have not read as root. Download, inspect, and prefer a distro package or an official repository.
• Name resolution failures. curl: (6) Could not resolve host is a DNS problem on your side; see Temporary failure in name resolution.
• Secrets on the command line are visible to other users in ps. Use -u user without the password, ~/.netrc, or -H @headers.txt.

The full manual is at curl.se/docs/manpage.html and Everything curl.

Frequently asked questions