← Full reference

curl

HTTP requests from the terminal — headers, status codes, POST with a body, redirects, HTTPS, timing

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

OptionWhat it does
-ssilent mode: no progress meter and no error messages
-Stogether with -s, still shows errors — the -sS pair
-o filesave the body to a file; -o /dev/null — discard it
-Osave under the name from the URL (the last path segment)
-Jtogether with -O: take the name from the Content-Disposition header
-C -resume a download from where it broke off
-ishow the response headers together with the body
-Ia HEAD request: response headers only
-D filewrite the response headers to a file; -D - — to stdout
-w 'format'after the request, print variables (see below); -w @file — format from a file
-fon status 400 and above, don't print the body; exit code 22
--fail-with-bodylike -f, but the error body is printed

Method, headers, body

OptionWhat it does
-X METHODset 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 URLthe Referer header
-b 'k=v' / -b filesend cookies as a string or from a file
-c filesave 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 @filebody 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)
-Gturn 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 fileupload a file with the PUT method
--compressedask for a compressed response and decompress it

Authentication and TLS

OptionWhat it does
-u user:passwordBasic authentication; -u user — it will prompt for the password
-H 'Authorization: Bearer TOKEN'token authentication
-kdon't verify the server certificate
--cacert ca.pemtrust this CA (for your own or a self-signed certificate)
--cert cert.pem --key key.pemclient certificate (mTLS)

Network, redirects, timeouts

OptionWhat it does
-Lfollow redirects (301, 302…); --max-redirs N — at most N hops
--resolve host:port:IPfor this host and port, go to the given IP, bypassing DNS
--connect-to host:port:new_host:new_portconnect to a different address while keeping the original name in the request
-x http://proxy:portthrough a proxy; --noproxy '*' — ignore the http_proxy variables
-4 / -6IPv4 only / IPv6 only
--connect-timeout Nwait for the connection no longer than N seconds
-m N / --max-time Nthe whole request no longer than N seconds (exit code 28)
--retry Nretry on transient errors; --retry-delay S, --retry-connrefused — also on connection refused
--http1.1 / --http2protocol version

Debugging

OptionWhat it does
-vrequest headers (>), response headers (<), info lines (*): DNS, connection, TLS
--trace-ascii filefull dump of the exchange, including the body; - — to stdout

Variables for -w

VariableMeaning
%{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