curl Command Cheat Sheet (With Code Conversion)

Most curl cheat sheets dump every flag in alphabetical order, which is useless when you are mid-task and just need to remember how to send a JSON body or print only the HTTP status. This one is organized by what you are actually trying to do. Each entry gives you a copyable command and, because a working terminal command is often the start of a script and not the end, a path to turn it into real code with our curl-to-code converter.

Send a JSON body (POST)

The most common request developers reach for. You set the method, declare the content type, and pass the body with -d:

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada","role":"admin"}'

Two gotchas. First, single-quote the JSON in bash so the shell does not try to interpret " or $. On Windows cmd you have to escape inner quotes instead, which is why many copied commands break on Windows. Second, see the auto-POST note below: adding -d changes the method for you, so the explicit -X POST is often redundant.

Since curl 7.82.0 (released March 2022) there is a --json shortcut that sets the method to POST and adds both Content-Type: application/json and Accept: application/json in one flag:

curl --json '{"name":"Ada"}' https://api.example.com/users

It is cleaner, but if you support older curl builds or share commands with teammates on unknown versions, the explicit three-line form is safer. Paste either version into the converter to get the equivalent requests or fetch call without hand-translating headers.

The -d auto-POST gotcha

This trips up almost everyone at least once. The moment you add a -d (or --data) flag, curl silently switches the method from GET to POST. So curl -d 'q=test' https://example.com/search is a POST, not a GET with a query string. If you actually want those values sent as a query string on a GET request instead, use -G, which tells curl to append the -d values to the URL:

curl -G https://example.com/search -d 'q=test' -d 'page=2'
# becomes GET https://example.com/search?q=test&page=2

Also note that -d defaults to a content type of application/x-www-form-urlencoded, not JSON. If your API expects JSON you must add the header yourself, or use --json. For values with spaces or special characters, pair -G with --data-urlencode so curl percent-encodes them correctly.

Add authentication headers

For token-based APIs, send a bearer token with a manual Authorization header:

curl https://api.example.com/me \
  -H "Authorization: Bearer YOUR_TOKEN"

For old-school HTTP Basic auth, curl has a built-in flag that base64-encodes the credentials for you:

curl -u username:password https://api.example.com/me

Per MDN's HTTP authentication docs, Basic auth is just base64 of user:password in an Authorization header, so it is encoding, not encryption, and must run over HTTPS. If you need to build that header by hand for code or a tool that has no -u equivalent, our basic auth header generator produces the exact Authorization: Basic ... string.

Inspect the response: status, headers, verbose

Three flags cover almost all debugging. Use -I to fetch only the response headers with a HEAD request, which is the fastest way to check caching, content type, or a redirect target:

curl -I https://example.com

To print just the numeric status code and nothing else, combine silent mode with a write-out format string:

curl -s -o /dev/null -w "%{http_code}\n" https://example.com

Here -s hides the progress meter, -o /dev/null discards the body, and -w prints a chosen variable. You can extend the format string with %{time_total} or %{redirect_url} for quick timing or redirect checks. For the full deep-dive on a real response, -v (verbose) shows the request line, all sent and received headers, and TLS handshake details:

curl -v https://example.com

When you only care about analyzing the response headers in a readable layout rather than reading raw verbose output, paste a URL into the HTTP header inspector to see them parsed and grouped.

Follow redirects and other essentials

By default curl does not follow 3xx redirects; it prints the redirect response and stops. Add -L to make it follow the Location header to the final destination, which is essential for shortened URLs and sites that redirect HTTP to HTTPS or bare to www:

curl -L https://example.com

A few more flags worth memorizing:

• -o file.html saves the body to a named file; -O uses the remote filename from the URL.
• -H "Accept: application/json" sets any request header; repeat the flag for multiple headers.
• -X DELETE or -X PUT sets an explicit method when there is no body to imply it.
• --compressed requests and transparently decodes gzip or brotli responses.
• -b "name=value" sends a cookie; -c jar.txt saves received cookies to a file.

From terminal to code

The reason curl is worth mastering is that it is a near-universal lingua franca: API docs, browser devtools (right-click a request, Copy as cURL), and Postman all speak it. But a one-off terminal command usually needs to become a function in your app. Rather than manually mapping each -H to a headers dictionary and each -d to a body, drop the whole command into the curl-to-code converter to get a working requests (Python), fetch (JavaScript), or Node snippet. It correctly carries over the method that -d implied, the content type, and auth, which is exactly where hand translation tends to introduce bugs. If you are wiring these requests into a test suite next, the guide to API testing tools covers where curl ends and dedicated tooling begins.

Frequently Asked Questions