curl: A Complete Practical Guide
curl is the tool for talking to an HTTP API from the terminal. Learn the flags for a request, a header, a body, a file and a debug trace.
By Velloreth
The basic request
curl https://api.example.com/users
The response body is printed to the terminal.
The progress meter is printed to stderr, which is why it does not appear when the output is piped.
The method
curl -X GET https://api.example.com/users
curl -X POST https://api.example.com/users
curl -X PUT https://api.example.com/users/1
curl -X DELETE https://api.example.com/users/1
curl -X PATCH https://api.example.com/users/1
-X sets the method explicitly.
-d implies POST, so -X POST is redundant with a body.
-I sends a HEAD request, which returns the headers with no body.
Headers
curl -H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json" \
https://api.example.com/users
-H adds a header. Repeat it for each header.
A header with no value removes a default:
curl -H "Accept:" https://api.example.com/users
The User-Agent is curl/8.x by default, which some APIs block. Set it explicitly:
curl -A "MyApp/1.0" https://api.example.com/users
A body
# A JSON body
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-d '{"name":"Alice","email":"alice@example.com"}'
-d sends the body. With -d, curl sets Content-Type: application/x-www-form-urlencoded by default, so a JSON body needs an explicit header.
--data-binary sends the body without any processing, which matters for a binary or a body with a newline.
--data-urlencode URL-encodes the value:
curl -X POST https://api.example.com/search \
--data-urlencode "q=hello world"
A body from a file:
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
--data-binary @user.json
The @ prefix reads the value from a file.
Output
# Write to a file
curl -o output.json https://api.example.com/users
# Use the remote filename
curl -O https://example.com/photo.jpg
# Show the response headers
curl -i https://api.example.com/users
# Show only the headers
curl -I https://api.example.com/users
# Silence the progress meter
curl -s https://api.example.com/users
# Silence everything, and fail on an HTTP error
curl -sSf https://api.example.com/users
-sSf is the combination for a script. -s silences the progress, -S still shows an error, and -f makes curl exit non-zero on an HTTP error.
Without -f, curl exits 0 even on a 404, which is a common scripting bug.
Redirects
curl -L https://example.com/old-page
-L follows a redirect. Without it, curl shows the 301 response and stops.
--max-redirs 5 limits the number of redirects, which prevents a loop.
-L with a POST may change the method to GET on a 301 or 302, which is the historical behaviour. Use --post301 to keep the method.
Debugging
# The full exchange
curl -v https://api.example.com/users
# The raw bytes
curl --trace-ascii trace.txt https://api.example.com/users
# Only the timing
curl -w "@curl-format.txt" -o /dev/null -s https://api.example.com/users
-v shows the request headers, the response headers, and the TLS handshake, with a > for a sent line and a < for a received one.
A timing format is useful for a performance check:
time_namelookup: %{time_namelookup}s\n
time_connect: %{time_connect}s\n
time_appconnect: %{time_appconnect}s\n
time_redirect: %{time_redirect}s\n
time_starttransfer: %{time_starttransfer}s\n
----------\n
time_total: %{time_total}s\n
time_starttransfer is the time to the first byte, which is the server’s response time.
Authentication
# A bearer token
curl -H "Authorization: Bearer $TOKEN" https://api.example.com/me
# Basic auth
curl -u user:password https://api.example.com/me
# A cookie
curl -b "session=abc123" https://api.example.com/me
# Save and reuse a cookie jar
curl -c cookies.txt https://example.com/login -d "user=alice&pass=secret"
curl -b cookies.txt https://example.com/dashboard
-c writes the cookies, and -b sends them. The pair is how a session is maintained across two requests.
-u sends basic auth, and it prompts for the password if it is omitted.
Uploading a file
# A multipart form upload
curl -F "file=@photo.jpg" https://api.example.com/upload
# With an extra field
curl -F "file=@photo.jpg" -F "name=holiday" https://api.example.com/upload
# A raw body
curl -X PUT --data-binary @photo.jpg \
-H "Content-Type: image/jpeg" \
https://api.example.com/photo
-F sends a multipart form, which is what an HTML file input produces.
--data-binary sends the file as the raw body.
Other protocols
# A different port
curl https://api.example.com:8443/users
# Ignore a certificate error (testing only)
curl -k https://self-signed.example.com
# Resolve a name to a specific address
curl --resolve api.example.com:443:203.0.113.10 https://api.example.com/users
# A proxy
curl -x http://proxy.example.com:8080 https://api.example.com/users
--resolve is useful for testing a new server before a DNS change.
-k disables the certificate check, which is for a test only and never for production.
curl in a script
curl is the tool a shell script uses to talk to an API, and the flags that matter in a script are different from the ones that matter interactively. The first is -sSf, because a script needs a non-zero exit code on an HTTP error and a silent progress meter. The second is —retry, which retries a transient failure such as a 503 or a connection reset, with —retry-delay and —retry-max-time to bound it. The third is —max-time, which prevents a hung request from blocking the script forever. The fourth is -w, which writes a status or a timing value to stdout so the script can branch on it. The fifth is —fail-with-body, which returns a non-zero exit code on an HTTP error while still printing the response body, which is what you want when the API returns a useful error message.
Debugging with curl
curl is the fastest way to separate a client problem from a server problem, because it removes the browser from the equation. If curl returns the expected response and the browser does not, the difference is in the browser: a CORS policy, a cookie that is not sent, a cached response, or a service worker. If curl also fails, the problem is on the server or the network, and the next step is to add -v to see the request and the response headers. The flags that help most in a debugging session are -v for the full exchange, -i to include the response headers in the output, -I for a HEAD request that returns only the headers, and —resolve to test a hostname against a specific IP without changing DNS. A request that works with —resolve and fails without it is a DNS problem, and a request that works over HTTP and fails over HTTPS is a certificate or a redirect problem.
curl and the shell
curl is designed to compose with the shell, and the composition is where it becomes more than a request tool. Piping the output to jq turns a JSON response into a query, and the -s flag keeps the progress meter out of the pipe. Writing the output to a file with -o, or to a name derived from the URL with -O, turns curl into a downloader. Reading a list of URLs from a file with -K, or looping over a list in the shell, turns it into a batch tool. Passing the body from a file with -d @file, or from standard input with -d @-, turns it into a way to send a payload that is too large to type. The combination that is worth remembering is a loop over a list of hosts with -sSf and a status written by -w, which is a health check in three lines and needs no dependency beyond curl itself.
Practical guidance
- Use
-sSfin a script. - Use
-ito see the headers. - Use
-vto debug. - Use
-Lto follow a redirect. - Set
Content-Typefor a JSON body. - Use
--data-binary @filefor a body from a file. - Use
-cand-bfor a session. - Use
--resolveto test before a DNS change. - Never use
-kin production.
For the related guides, see http-status-codes-explained and essential-cli-tools-for-developers. For the broader context, api-error-responses-guide and http-caching-headers.
Quotable summary
curl makes an HTTP request from the terminal, which makes it the fastest way to test an API, with -X for the method, -H for a header, and -d for a body. -i shows the response headers and -v shows the whole exchange including the TLS handshake, while -o writes to a file and -O uses the remote filename. -s silences the progress meter, and the combination for a script is -sSf, because without -f curl exits 0 even on a 404, which is a common scripting bug. Use -L to follow a redirect, —data-binary @file for a body from a file, and -c and -b together to maintain a session across two requests.