What is the curl Command? Examples, Flags, HTTP Requests
curl is a command-line tool to send HTTP/HTTPS/FTP requests from the terminal. Used for API testing, debugging, scripting, and CI checks.
What is the curl command?
curl (Client URL) is a command-line tool and library for transferring data with URLs. It supports dozens of protocols (HTTP, HTTPS, FTP, SFTP, SMTP, IMAP, LDAP, SCP, etc.) and is the de facto standard for making HTTP requests from the terminal. Originally written in 1996 by Daniel Stenberg, curl is bundled with most Linux distributions, macOS, and Windows 10+.
Developers use curl for testing API endpoints, debugging HTTP issues, scripting automation, downloading files, and CI/CD checks. It's also widely used as a teaching tool — almost every API documentation page includes curl examples.
Basic curl syntax
The simplest curl command sends a GET request:
curl https://api.example.com/users/42To see headers + body:
curl -i https://api.example.com/users/42POST with JSON body:
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-d '{"name": "Alice", "email": "alice@example.com"}'With authentication:
curl -H "Authorization: Bearer eyJ..." https://api.example.com/meMost-used curl flags
| Flag | What it does |
|---|---|
-X METHOD | Set HTTP method (GET, POST, PUT, PATCH, DELETE) |
-H "Header: value" | Add a request header |
-d 'data' or --data 'data' | Send request body (POST/PUT) |
-d @file.json | Read body from file |
-F "field=value" | Send multipart/form-data field |
-F "file=@photo.jpg" | Upload a file (multipart) |
-i | Include response headers in output |
-I | Send HEAD request (headers only) |
-L | Follow redirects |
-o file | Save response body to file |
-O | Save with remote filename |
-s | Silent mode (no progress bar) |
-v | Verbose output (debug) |
-k | Skip TLS cert verification (testing only) |
--cookie-jar file | Save cookies to file |
-u user:pass | HTTP Basic Auth |
--max-time N | Total timeout in seconds |
-w "%{http_code}" | Print specific response info (status, time, etc.) |
Common curl recipes
Test an API endpoint
curl -i https://api.example.com/healthPOST JSON
curl -X POST https://api.example.com/orders \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"product_id": 42, "quantity": 1}'Download a file
curl -O https://example.com/large-file.zipResume an interrupted download
curl -C - -O https://example.com/large-file.zipUpload a file (multipart)
curl -F "avatar=@photo.jpg" -F "username=alice" \
https://api.example.com/uploadFollow redirects
curl -L https://example.com/short-urlGet only the HTTP status code
curl -s -o /dev/null -w "%{http_code}" https://example.comTime the response
curl -s -o /dev/null -w "%{time_total}\n" https://example.comTest with self-signed certificate
curl -k https://localhost:8443/healthCookie session
curl --cookie-jar cookies.txt -d "user=alice&pass=..." https://example.com/login
curl --cookie cookies.txt https://example.com/dashboardcurl vs wget vs httpie
| Aspect | curl | wget | HTTPie |
|---|---|---|---|
| Best for | Scripting, API testing, debugging | File downloads, mirroring | Human-friendly API testing |
| Output | Stdout (default) | File (default) | Stdout, color-coded |
| Recursive download | No (use wget) | Yes (specialty) | No |
| Resume downloads | Yes (-C) | Yes (-c) | No |
| Protocols | 30+ (HTTP, FTP, SMTP, etc.) | HTTP, HTTPS, FTP | HTTP/HTTPS only |
| Pre-installed | Almost everywhere | Linux only typically | Requires install |
Common curl pitfalls
- Forgot Content-Type for JSON.
-ddefaults toapplication/x-www-form-urlencoded. Always add-H "Content-Type: application/json"for JSON. - Quote escaping in shell. Use single quotes around JSON to avoid bash variable expansion:
-d '{"x": 1}'not-d "{\"x\": 1}". - Logged secrets. Bearer tokens in
-H "Authorization: ..."end up in shell history. Use--header @fileor env variables. - HTTP/2 issues. Old curl versions don't support HTTP/2; check
curl --version. - Trailing newlines on redirected output. Add
-Nfor unbuffered output, useful with streaming responses. - Wrong status code in scripts. Use
-w "%{http_code}"+ parse, or--failto set non-zero exit on 4xx/5xx.
curl in CI/CD
- Smoke tests after deploy.
curl --fail https://api.example.com/healthexits non-zero on 4xx/5xx. - Health check endpoints. Lightweight liveness/readiness checks.
- API integration tests. Quick endpoint validation in CI scripts.
- Performance budget tests. Combined with
-w "%{time_total}"to assert response time.
FAQ: curl command
What's the difference between -d and --data-raw?
-d processes @ as "read from file". --data-raw sends literal @ characters. Use --data-raw when sending strings starting with @.
How do I send a custom HTTP method?
-X CUSTOM works: curl -X PROPFIND ... for WebDAV, -X PURGE ... for some CDN purge APIs.
How do I see the request curl sends?
-v for verbose mode (request + response). --trace-ascii file for full debug.
Can curl do parallel requests?
curl 7.66+ supports --parallel for multiple URLs in one command. For load testing at scale, dedicated tools like LoadFocus/k6/JMeter are better.
How do I handle cookies across multiple curl calls?
Save with --cookie-jar cookies.txt, send with --cookie cookies.txt.
Can I use curl as a load testing tool?
For 1-10 concurrent requests, yes. For real load testing (100s-1000s of VUs from multiple regions), use proper tools like LoadFocus.
Beyond curl: load testing at scale with LoadFocus
If you've reached the limits of curl-in-a-loop for load testing, LoadFocus runs JMeter and k6 scripts that take HTTP requests to 12,500 VUs from 25+ regions. Sign up free at loadfocus.com/signup.
Related LoadFocus Tools
Put this concept into practice with LoadFocus — the same platform that powers everything you just read about.