curl sends a request to a URL and prints the response body to stdout. It's the main way to check a web server or an API from the terminal: what it answers, with which status code and headers, how long the request took.
Syntax
curl [options] URL…
Without options curl does a GET and prints the body. The method, headers and body are set with flags. Short flags can be combined: -sSfL = -s -S -f -L.
Output and saving
| Option | What it does |
|---|
-s | silent mode: no progress meter and no error messages |
-S | together with -s, still shows errors — the -sS pair |
-o file | save the body to a file; -o /dev/null — discard it |
-O | save under the name from the URL (the last path segment) |
-J | together with -O: take the name from the Content-Disposition header |
-C - | resume a download from where it broke off |
-i | show the response headers together with the body |
-I | a HEAD request: response headers only |
-D file | write the response headers to a file; -D - — to stdout |
-w 'format' | after the request, print variables (see below); -w @file — format from a file |
-f | on status 400 and above, don't print the body; exit code 22 |
--fail-with-body | like -f, but the error body is printed |
Method, headers, body
| Option | What it does |
|---|
-X METHOD | set the method: PUT, DELETE, PATCH… |
-H 'Name: value' | add a header; can be repeated. -H 'Name:' — remove a header curl sets itself |
-A 'string' | the User-Agent header |
-e URL | the Referer header |
-b 'k=v' / -b file | send cookies as a string or from a file |
-c file | save received cookies to a file (cookie jar) |
-d 'data' | request body; makes it a POST with application/x-www-form-urlencoded. -d @file — from a file, newlines are stripped |
--data-binary @file | body from a file, byte for byte |
--data-raw 'data' | like -d, but a leading @ is an ordinary character |
--data-urlencode 'k=v' | URL-encode the value (space → +, & → %26) |
-G | turn all -d into query string parameters and send a GET |
--json 'JSON' | a JSON body plus Content-Type/Accept: application/json headers (curl 7.82+) |
-F 'k=v' / -F 'file=@path' | a multipart/form-data form, file upload |
-T file | upload a file with the PUT method |
--compressed | ask for a compressed response and decompress it |
Authentication and TLS
| Option | What it does |
|---|
-u user:password | Basic authentication; -u user — it will prompt for the password |
-H 'Authorization: Bearer TOKEN' | token authentication |
-k | don't verify the server certificate |
--cacert ca.pem | trust this CA (for your own or a self-signed certificate) |
--cert cert.pem --key key.pem | client certificate (mTLS) |
Network, redirects, timeouts
| Option | What it does |
|---|
-L | follow redirects (301, 302…); --max-redirs N — at most N hops |
--resolve host:port:IP | for this host and port, go to the given IP, bypassing DNS |
--connect-to host:port:new_host:new_port | connect to a different address while keeping the original name in the request |
-x http://proxy:port | through a proxy; --noproxy '*' — ignore the http_proxy variables |
-4 / -6 | IPv4 only / IPv6 only |
--connect-timeout N | wait for the connection no longer than N seconds |
-m N / --max-time N | the whole request no longer than N seconds (exit code 28) |
--retry N | retry on transient errors; --retry-delay S, --retry-connrefused — also on connection refused |
--http1.1 / --http2 | protocol version |
Debugging
| Option | What it does |
|---|
-v | request headers (>), response headers (<), info lines (*): DNS, connection, TLS |
--trace-ascii file | full dump of the exchange, including the body; - — to stdout |
Variables for -w
| Variable | Meaning |
|---|
%{http_code} | the response status code (000 if there was no response) |
%{time_namelookup}, %{time_connect}, %{time_appconnect} | time until DNS, TCP connection, TLS handshake finished (seconds, from the start) |
%{time_starttransfer} | time to the first response byte (TTFB) |
%{time_total} | total request time |
%{size_download}, %{content_type} | body size in bytes, content type |
%{remote_ip}, %{remote_port} | where it actually connected |
%{redirect_url} | where the redirect points (without -L) |
%{url_effective}, %{num_redirects} | the final URL and number of hops (with -L) |
%{ssl_verify_result} | certificate verification result: 0 — success |
%header{name} | value of a response header (curl 7.84+) |
%{exitcode}, %{errormsg} | curl's error code and its message (curl 7.75+) |
%{json} | all variables as one JSON object |
Exit codes
0 — a response was received (any, even 500, unless -f), 6 — couldn't resolve the name, 7 — couldn't connect, 22 — HTTP error with -f, 28 — timeout, 35 — TLS handshake error, 47 — --max-redirs exceeded, 60 — the certificate failed verification.
Examples
# only the status code — handy in scripts and checks
curl -s -o /dev/null -w '%{http_code}\n' http://localhost/
# response headers without the body
curl -I http://localhost/
# headers and body of a real GET request
curl -si http://localhost/
# where and how long: DNS, connection, first byte, total
curl -s -o /dev/null -w 'dns=%{time_namelookup} conn=%{time_connect} ttfb=%{time_starttransfer} total=%{time_total}\n' http://localhost/
# download a file following redirects; show errors, hide progress
curl -sSL -o archive.tar.gz https://example.com/archive.tar.gz
# POST with JSON
curl -s -H 'Content-Type: application/json' -d '{"name":"demo"}' http://localhost:8000/api/items
# GET with properly encoded parameters
curl -s -G --data-urlencode 'q=a b&c' -d page=2 http://localhost:8000/search
# upload a file with a form
curl -s -F 'file=@report.pdf' -F 'title=Report' http://localhost:8000/upload
# delete a resource
curl -s -X DELETE http://localhost:8000/api/items/1
# Basic auth and a custom header
curl -s -u admin:secret -H 'Accept: application/json' http://localhost:8000/
# log in saving cookies, then keep using them
curl -s -c cookies.txt -d 'user=demo&pass=demo' http://localhost:8000/login
curl -s -b cookies.txt http://localhost:8000/profile
# test a virtual host without touching DNS or /etc/hosts
curl -s --resolve example.com:80:127.0.0.1 http://example.com/
# HTTPS with a self-signed certificate: --cacert is better than -k
curl -s --cacert cert.pem https://localhost:8443/
# the value of a single response header
curl -s -o /dev/null -w '%header{content-type}\n' http://localhost/
# fail with a non-zero exit code if the server returned an error
curl -sSf --max-time 5 http://localhost/health || echo 'service is not responding'
Pitfalls
- Without
-f the exit code is 0 even on 404 and 500. curl considers getting any response a success. For checks use -f or compare %{http_code} explicitly.
-s swallows errors too. curl -s against a dead server prints nothing. Add -S to see the reason (Couldn't connect to server, SSL certificate problem).
-d @file strips newlines. For multi-line JSON, binary data and generally "send the file as is" you need --data-binary @file.
-d without Content-Type goes out as application/x-www-form-urlencoded. An API that expects JSON won't understand such a request — add the header or use --json.
-X POST doesn't add a body, and -d already makes the request a POST. And -X together with -L applies to every hop — after a 302 the server expects a GET but gets a POST again.
- Without
-L the redirect isn't followed: you get a 301 and a short placeholder page. Use -w '%{redirect_url}' or -i to see where it leads.
-I is HEAD, not GET. Some applications answer HEAD differently. To see the headers of a real GET, use -i, -D - or -v.
-k disables protection entirely. For your own certificate --cacert cert.pem is better: verification stays on, just with your trusted root.
- Special characters in URLs. The shell splits an unquoted URL at
& and ? — quote URLs.
-O doesn't work if the URL ends in / — there's no file name. Then set a name with -o.
See also
nginx · openssl · jq · dig · ss