Networking & API TestingUpdated: 2026-11-06
cURL CLI Syntax, Headers, Form Uploads & SSL Flags Reference
Master cURL options for REST API testing, downloading files, streaming payloads, inspecting SSL certs, and debugging response timings.
cURL (Client URL) is the ubiquitous command-line tool used by developers and DevOps engineers to transfer data across network protocols. From debugging preflight CORS requests to automated API testing in CI/CD pipelines, this cheat sheet provides production-tested cURL flags.
Table of Contents
HTTP Methods & JSON Payloads
Commands for executing standard REST API requests.
| Command / Flag | Action Description | Example Syntax |
|---|---|---|
| `-X POST -d '{"key":"val"}'` | Send JSON body in POST request | `curl -X POST https://api.example.com -d '{"id":1}'` |
| `-H "Content-Type: application/json"` | Set JSON request content header | `curl -H "Content-Type: application/json" ...` |
| `-X PUT / -X DELETE` | Specify HTTP PUT or DELETE verbs | `curl -X DELETE https://api.example.com/items/42` |
| `-d @payload.json` | Read JSON body directly from a local file | `curl -X POST https://api.example.com -d @data.json` |
Authentication & Headers
Sending Bearer tokens, Basic Auth, and custom tracking headers.
| Auth Method | cURL Syntax | Use Case |
|---|---|---|
| Bearer Token | `-H "Authorization: Bearer <TOKEN>"` | OAuth2, JWT authentication |
| Basic Authentication | `-u username:password` | HTTP Basic Auth challenge |
| API Key Header | `-H "X-API-Key: <SECRET>"` | Third-party developer gateways |
| Pass Cookies | `-b "session=xyz123"` | Simulate logged-in browser session |
Debugging & Performance Profiling
Isolate DNS latency, TLS handshake duration, and HTTP status codes.
| Flag | Effect | Description |
|---|---|---|
| `-i` / `-I` | Include response headers / HEAD only | Inspect status code, caching headers, and Content-Type |
| `-v` (Verbose) | Show complete TLS handshake and socket info | Diagnose certificate and connection drops |
| `-L` (Follow Location) | Automatically follow 301/302 HTTP redirects | Mandatory for shortened URLs and canonical redirects |
| `-sS` (Silent + Show Error) | Hide progress bar but display fatal errors | Ideal for cron jobs and bash script pipelines |
Interactive Client-Side Tools for this Guide
Test and run these patterns directly inside your browser with zero server uploads:
Frequently Asked Questions
How do I download a file and preserve its original remote filename?
Use `curl -O <URL>`. To automatically follow redirects and resume interrupted downloads, combine flags: `curl -C - -L -O <URL>`.
How can I measure exact API response latency with cURL?
Use the write-out format flag: `curl -o /dev/null -s -w "DNS: %{time_namelookup}s | Connect: %{time_connect}s | TTFB: %{time_starttransfer}s | Total: %{time_total}s\n" <URL>`.