curl Cheatsheet - curl HTTP Debugging Command Reference
For developers who need to hit APIs from the shell, reproduce production issues, and see a full HTTP round trip. Browsers cannot express custom headers, POST bodies, or relaxed TLS checks, so curl is the way to take full control of what a request looks like. By the end you can declaratively build requests with bodies/headers/cookies, break down DNS/connect/TTFB timing with -w to find where slowness lives, and use -v to inspect the TLS handshake and redirect chain.
Basic Requests 6
curl https://example.comcurl -X POST https://api.example.comcurl -H "Content-Type: application/json" -H "Authorization: Bearer xxx" https://api.example.comcurl -d '{"k":"v"}' https://api.example.comcurl -d @file.json https://api.example.comcurl -G https://api.example.com --data-urlencode "q=hello world"Debugging & Details 6
curl -v https://example.comcurl -I https://example.comcurl -L https://example.comcurl -w "%{http_code} %{time_total}\n" -o /dev/null -s https://example.comcurl -s https://example.comcurl --resolve example.com:443:1.2.3.4 https://example.comProxy & Timeout 5
curl -x http://proxy:8080 https://example.comcurl -x socks5h://127.0.0.1:1080 https://example.comcurl --connect-timeout 5 https://example.comcurl --max-time 30 https://example.comcurl --retry 3 https://example.comAuth & Upload 5
curl -u user:pass https://example.comcurl -F "file=@photo.jpg" https://example.com/uploadcurl -F "file=@photo.jpg" -F "name=tom" https://example.com/uploadcurl -o photo.jpg https://example.com/photo.jpgcurl --cookie "session=abc" https://example.comTypical Use Case
The most typical scenario is "see one real request" while troubleshooting. When the frontend returns 400, replay that exact request with curl -v and inspect the outgoing headers against the server response to tell whether Content-Type is missing or an extra cookie is sent. For intermittent timeouts, use curl -w to split time_namelookup/time_connect/time_appconnect/time_starttransfer and isolate DNS, TCP connection, or slow server response. To reproduce a login-gated issue, carry cookies with curl -b cookies.txt and follow redirects with -L to reach the real landing page. Test a path with -I (headers only) before -d posting data to reduce mistakes.
Command Examples
Break down the time each phase takes in a request
curl -o /dev/null -s -w "DNS: %{time_namelookup}s\nCONNECT: %{time_connect}s\nTTFB: %{time_starttransfer}s\nTOTAL: %{time_total}s\n" https://example.com/api-o /dev/null 丢弃响应体避免刷屏，-w 输出各阶段耗时。慢在 time_namelookup 是 DNS 解析问题，慢在 time_connect 是网络连通性，慢在 time_starttransfer 说明服务端处理或首字节返回慢。
Output
DNS: 0.012s CONNECT: 0.047s TTFB: 0.213s TOTAL: 0.220s
POST with a JSON body, custom header, and cookie
curl -X POST 'https://api.example.com/login' -H 'Content-Type: application/json' -H 'X-Api-Key: abc123' -b 'session=xyz' -d '{"username":"test"}'注意 -d 不会自动设置 Content-Type，需手动加 -H；-b 传入 cookie，-H 可叠加多个自定义头。
Skip TLS verification for a local self-signed service
curl -k https://localhost:8443/health-k 只用于本地联调或内网自签证书，生产环境绝不能跳过校验，否则中间人可解读全部流量。
Common Pitfalls
- -d sends form data by default; when POSTing JSON you must add -H "Content-Type: application/json" or the server may parse it as a form and return 400 or empty data.
- -k disables TLS verification — only acceptable for local/internal self-signed certs. Used on production it defeats HTTPS entirely.
- When combining -X POST with -d, -X can override the inferred method; confirm the actual method sent with -v.
- In monitoring scripts -w time_total is measured in seconds and curl has no default timeout; always add --max-time so the process cannot hang forever.
- To follow redirects use -L rather than editing the URL by hand, or you end up at the redirect page instead of the final resource.
Tips
- When sending JSON with -d, manually add -H "Content-Type: application/json" or the server may fail to parse.
- For HTTPS certificate issues, use -v to see the handshake; skip verification temporarily with -k (never in production).
- -w time_total is in seconds. Monitoring scripts should pair with --max-time to prevent hanging.
FAQ
How do I send a request with a Cookie or a login session in curl?
To pass fixed cookies in one shot, use curl -b "name=value; token=xxx". To store the cookies returned by the server, use -c cookies.txt, then send them back with -b cookies.txt to reuse the session. For login flows, run the login request with -c first, then use -b on the following requests to stay authenticated.
How do I get a curl command for an authenticated API from the browser?
Open DevTools with F12, go to the Network panel, perform the authenticated request once, then right-click it and choose Copy as cURL. That reproduces all the headers, cookies, and body. Sanitize any exposed Cookie or Token in that command before reuse or sharing.
How do I POST JSON vs form-encoded data with curl?
For JSON, use curl -X POST -H "Content-Type: application/json" -d '{"a":1}'. For form data, -d "key=value&k2=v2" sets Content-Type to application/x-www-form-urlencoded automatically, or use -F "file=@a.png" for multipart uploads. Note -X POST is not needed when -d is present, since curl implies it.
What should I do when curl reports an HTTPS certificate error?
For self-signed or internal certificates, pass -k (--insecure) to skip verification while diagnosing; in production, prefer fixing the CA or adding the proper certificate rather than relying on -k. To trust a specific CA, use --cacert path.pem. Add --noproxy "*" to bypass a proxy if one is interfering.
How do I tell whether slowness is in the network or the server?
Use curl -w "\ntime_namelookup:%{time_namelookup}\ntime_connect:%{time_connect}\ntime_starttransfer:%{time_starttransfer}\ntime_total:%{time_total}\n" -o /dev/null -s URL. time_connect reflects TCP handshake and network latency, time_starttransfer is the time to the first byte (server processing plus TTFB), and time_total is the total. Comparing the phases tells you which segment is slow. A short form is curl -w '%{time_total}\n' -o /dev/null -s URL.
Official References
Each command links to its official documentation below, so you can verify the latest usage and read deeper.
Maintained by LaoHand
Publicly updated on Jul 21, 2026, continuously proofread against official docs.
Contact Us
Wrong command or description? Send us corrections, business inquiries or product feedback by email.
Contact Us