cURL Command Builder
Build curl commands visually — pick your method, headers, auth, and options, then copy the generated command.
Generated Command
curl \https://api.example.com
1 — Method & URL
2 — Query Parameters
3 — Headers
0 active4 — Authentication
5 — Request Body
6 — Options & Flags
cURL Command Reference
What is cURL?
cURL (Client URL) is a command-line tool for transferring data using various network protocols. It supports HTTP, HTTPS, FTP, and many more. cURL is pre-installed on macOS, Linux, and Windows 10+, making it the universal tool for testing APIs, downloading files, and debugging network requests from the terminal.
Common Flags
-X METHODSpecify the HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS). GET is the default.
-H 'Header: Value'Add a custom request header. Use multiple -H flags for multiple headers.
-d 'data'Send data in the request body. Commonly used with POST and PUT requests.
-u user:passProvide Basic authentication credentials. cURL Base64-encodes them automatically.
-w 'format'Write out info after transfer. Use variables like %{http_code}, %{time_total}, %{time_namelookup}, %{size_download} to extract response details.
-LFollow HTTP 3xx redirects automatically. Essential for URLs that redirect (e.g., shortened URLs).
-vVerbose output showing the full request/response cycle, including TLS handshake and headers.
-sSilent mode. Hides the progress meter and error messages. Useful in scripts.
-o fileWrite the response body to a file instead of stdout. Use -O to keep the remote filename. Use /dev/null to discard the body.
-IFetch response headers only, skip the body. Equivalent to a HEAD request. Use to check if a resource exists or inspect headers.
-kSkip SSL certificate verification. Use only for development/testing with self-signed certificates.
--compressedRequest a compressed response and automatically decompress it. Supports gzip, deflate, and br.
HTTP Methods Explained
Retrieve a resource. The default method. Should not have a request body.
Create a new resource or submit data. The request body contains the data to send.
Replace an existing resource entirely. The request body is the complete new representation.
Partially update a resource. The body contains only the fields to change.
Remove a resource. May or may not have a request body depending on the API.
Same as GET but returns only headers, no body. Useful for checking if a resource exists.
Authentication Methods
Sends an Authorization: Bearer <token> header. Common with OAuth2 and JWT-based APIs.
Sends a Base64-encoded username:password via the Authorization header. Use -u user:pass.
Sends the API key as a custom header (e.g., X-API-Key). The header name varies by provider.
No authentication headers are sent. Suitable for public APIs or when auth is handled by other means (cookies, IP allowlists).
Tips & Best Practices
- Use
-w '\n'to add a trailing newline after the response body for cleaner terminal output. - Pipe JSON responses through
jqfor pretty-printing:curl -s url | jq . - Use
--max-timeto set a timeout in scripts so they don't hang on slow endpoints. - Combine
-swith-o /dev/nulland-w '%{http_code}'to get just the HTTP status code. - Use
-Lwhen downloading files — many URLs redirect before serving the final content. - Avoid
-kin production scripts. If you need custom CA certificates, use--cacertinstead.
Common cURL Recipes
Use curl -s -o /dev/null -w '%{http_code}\n' URL to print just the status code (200, 404, 500, etc.). The -s flag silences the progress bar, -o /dev/null discards the response body, and -w '%{http_code}' prints the HTTP status code. This is the most common way to check if an endpoint is alive in shell scripts and CI pipelines.
Use curl -I URL to fetch only the response headers (sends a HEAD request). To see response headers along with the body, use curl -i URL instead. To see both request and response headers with full connection details, use curl -v URL. The -D - flag also dumps headers to stdout, which is useful when piping the body elsewhere.
Use curl -s -o /dev/null -w '%{time_total}\n' URL to print the total response time in seconds. For a full timing breakdown, use -w 'DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTLS: %{time_appconnect}s\nTTFB: %{time_starttransfer}s\nTotal: %{time_total}s\n'. This is essential for API performance testing and diagnosing latency issues — it tells you exactly where the time is spent (DNS, TCP, TLS, server processing).
Use curl -s -H 'Accept: application/json' URL to request JSON from an API. Add --compressed for faster transfers. Pipe through jq . for pretty-printed output, or jq '.field' to extract specific values. For POST requests with a JSON body, add -H 'Content-Type: application/json' -d '{"key":"value"}'.
Use curl -X POST -H 'Content-Type: application/json' -d '{"key":"value"}' URL for JSON, or curl -X POST -d 'field=value&other=data' URL for form-encoded data. To send a file as the body, use -d @filename.json. For multipart file uploads, use -F 'file=@photo.jpg'.
Use curl -L -o filename URL to download a file. The -L flag follows redirects (common for download links), and -o sets the local filename. Use -O (uppercase) to keep the original remote filename. Add -C - to resume a partially downloaded file.
curl -w Format Variables
The -w (write-out) flag accepts format variables that curl replaces with actual values after the transfer. These are essential for scripting, monitoring, and performance testing.
%{http_code}HTTP response status code (200, 301, 404, 500, etc.)
%{time_total}Total time in seconds for the entire operation
%{time_namelookup}Time in seconds from start to DNS name resolution
%{time_connect}Time in seconds from start to TCP connection established
%{time_appconnect}Time in seconds from start to TLS/SSL handshake complete
%{time_starttransfer}Time to first byte (TTFB) — server processing time
%{size_download}Total number of bytes downloaded in the response body
%{speed_download}Average download speed in bytes per second
%{url_effective}The final URL after all redirects are followed
%{content_type}The Content-Type header from the response