cURL — Transfer Data from the Command Line
Practical guide to cURL — HTTP requests, headers, authentication, downloads and TLS on the command line, with examples for every use case.
cURL is the Swiss Army knife for HTTP on the command line: a single command lets you call APIs, download files, probe endpoints or debug headers. It speaks more than twenty protocols – from HTTP and HTTPS through FTP to SFTP – and ships on virtually every system. This guide walks you through the options you reach for daily, from a plain GET request to client-certificate authentication.
Basic Requests
curl <url> — Perform a simple GET request and print the response to stdout.
curl https://api.example.com/userscurl -s <url> — Silent mode. Suppress progress meter and error messages.
curl -s https://api.example.com/userscurl -v <url> — Verbose mode. Show request and response headers for debugging.
curl -v https://api.example.com/userscurl -I <url> — Fetch only the HTTP response headers (HEAD request).
curl -I https://www.example.comcurl -L <url> — Follow redirects automatically.
curl -L https://example.com/redirectHeaders
curl -H "<header>" <url> — Send a custom request header.
curl -H "Accept: application/json" https://api.example.com/userscurl -H "Content-Type: application/json" <url> — Set the content type header for the request.
curl -H "Content-Type: application/json" https://api.example.com/userscurl -H "Authorization: Bearer <token>" <url> — Send a Bearer token for authentication.
curl -H "Authorization: Bearer eyJhbGci..." https://api.example.com/mecurl -A "<user-agent>" <url> — Set a custom User-Agent string.
curl -A "Mozilla/5.0" https://www.example.comPOST & PUT Data
curl -X POST -d "<data>" <url> — Send a POST request with URL-encoded form data.
curl -X POST -d "name=John&email=john@example.com" https://api.example.com/userscurl -X POST -H "Content-Type: application/json" -d '<json>' <url> — Send a POST request with JSON body.
curl -X POST -H "Content-Type: application/json" -d '{"name":"John"}' https://api.example.com/userscurl -X PUT -d '<data>' <url> — Send a PUT request to update a resource.
curl -X PUT -H "Content-Type: application/json" -d '{"name":"Jane"}' https://api.example.com/users/1curl -X PATCH -d '<data>' <url> — Send a PATCH request for partial updates.
curl -X PATCH -H "Content-Type: application/json" -d '{"email":"new@example.com"}' https://api.example.com/users/1curl -X DELETE <url> — Send a DELETE request to remove a resource.
curl -X DELETE https://api.example.com/users/1curl -F "file=@<path>" <url> — Upload a file using multipart form data.
curl -F "file=@photo.jpg" https://api.example.com/uploadcurl -d @<file> <url> — Send data from a file as the request body.
curl -d @data.json -H "Content-Type: application/json" https://api.example.com/usersAuthentication
curl -u <user>:<password> <url> — Send a request with Basic authentication.
curl -u admin:secret https://api.example.com/admincurl -u <user> <url> — Prompt for password interactively (more secure).
curl -u admin https://api.example.com/admincurl --oauth2-bearer <token> <url> — Send a request with an OAuth 2.0 Bearer token.
curl --oauth2-bearer eyJhbGci... https://api.example.com/mecurl -b "<cookies>" <url> — Send cookies with the request.
curl -b "session=abc123" https://www.example.com/dashboardcurl -c <file> <url> — Save response cookies to a file.
curl -c cookies.txt https://www.example.com/loginDownload & Output
curl -o <file> <url> — Save the response to a specific file.
curl -o page.html https://www.example.comcurl -O <url> — Save the response using the remote filename.
curl -O https://example.com/file.tar.gzcurl -w "%{http_code}" -o /dev/null -s <url> — Get only the HTTP status code.
curl -w "%{http_code}" -o /dev/null -s https://www.example.comcurl -w "%{time_total}" -o /dev/null -s <url> — Measure the total response time.
curl -w "%{time_total}" -o /dev/null -s https://www.example.comcurl -C - -O <url> — Resume an interrupted download.
curl -C - -O https://example.com/largefile.zipSSL/TLS
curl -k <url> — Skip SSL certificate verification (insecure, for testing only).
curl -k https://self-signed.example.comcurl --cacert <file> <url> — Use a custom CA certificate for verification.
curl --cacert ca-bundle.crt https://api.example.comcurl --cert <cert> --key <key> <url> — Use client certificate authentication.
curl --cert client.crt --key client.key https://api.example.comAdvanced Options
curl -x <proxy> <url> — Use a proxy server for the request.
curl -x http://proxy.example.com:8080 https://www.example.comcurl --connect-timeout <seconds> <url> — Set maximum time for the connection phase.
curl --connect-timeout 5 https://api.example.comcurl -m <seconds> <url> — Set maximum time for the entire operation.
curl -m 30 https://api.example.com/slow-endpointcurl --retry <num> <url> — Retry the request on transient errors.
curl --retry 3 https://api.example.com/flakycurl -s <url> | jq . — Pipe JSON response to jq for pretty-printing.
curl -s https://api.example.com/users | jq .Conclusion
cURL belongs in every developer's and administrator's toolkit: what starts as a quick API test soon replaces whole scripts. If you regularly build complex requests, it pays to explore --config files and the -w output format for machine-readable results – turning a one-liner into a reusable tool.
Further Reading
- curl – official documentation – reference and manual
- curl(1) – manual page – every option at a glance
- cURL – Wikipedia – background and history