Blog
3 min read

What Is curl? A Beginner's Guide With Practical Examples

curl is a command-line tool for making web requests, installed on almost every computer. The commands you'll actually use — GET, POST JSON, headers, authentication, following redirects, downloading files, seeing response headers — and how to read API docs that use it.

curl is a command-line program for sending requests to web servers and showing you what comes back. It's installed on macOS, Linux and modern Windows, and almost every API documentation page shows examples in curl. Learning a handful of commands makes debugging much easier.

Your first request

curl https://example.com

That sends a GET request and prints the response body — the page's HTML. (GET vs POST)

On Windows, use Command Prompt or Git Bash. In older PowerShell, curl was an alias for a different command; type curl.exe to be sure you get the real one.

The commands you'll actually use

See the status code and headers

curl -I https://example.com     # headers only (HEAD request)
curl -i https://example.com     # headers + body
curl -v https://example.com     # everything, including the request sent

-v (verbose) is the debugging workhorse: it shows the DNS lookup, the TLS handshake, every header sent and received. (HTTP headers explained, HTTP status codes)

Follow redirects

curl -L http://example.com

Without -L, curl shows you the redirect response itself instead of following it — handy for debugging redirect loops. (ERR_TOO_MANY_REDIRECTS)

Send JSON (POST)

curl -X POST https://api.example.com/orders \
  -H "Content-Type: application/json" \
  -d '{"product_id": 42, "quantity": 2}'
  • -X sets the method (POST, PUT, PATCH, DELETE)
  • -H adds a header
  • -d sends a body (and implies POST)

Newer versions of curl have --json, which sets the headers for you:

curl --json '{"product_id": 42}' https://api.example.com/orders

Authentication

curl -H "Authorization: Bearer $API_TOKEN" https://api.example.com/me
curl -u username:password https://example.com/admin   # basic auth

Put tokens in environment variables rather than typing them in, so they don't sit in your shell history. (What is an API key?)

Download a file

curl -O https://example.com/report.pdf        # keep the file name
curl -o latest.pdf https://example.com/report.pdf

Quiet output for scripts

curl -fsS https://example.com/health

-f makes curl fail (non-zero exit) on HTTP errors, -s hides the progress bar, -S still shows errors. Good for health checks. (Health check endpoints)

Pretty-print JSON

curl doesn't format JSON, but jq does:

curl -s https://api.example.com/users | jq

Reading curl in API docs

When documentation shows:

curl https://api.stripe.com/v1/customers \
  -u sk_test_123: \
  -d email="ada@example.com"

you can read it as: POST to that URL, authenticate with that key, send email as form data. The backslashes \ just continue the command on the next line. Your browser's DevTools can also do the reverse: right-click a request in the Network tab → Copy → Copy as cURL.

Debugging your own app with curl

When something's broken in production, curl from the server itself isolates the problem:

curl -i http://127.0.0.1:3000/     # is the app answering at all?
curl -i https://yourdomain.com/    # does it work through the proxy?

If the first works and the second doesn't, the problem is the proxy, DNS or HTTPS — not your app. (502 Bad Gateway)

Quick reference

Flag Meaning
-X METHOD Request method
-H "Name: value" Add a header
-d 'data' Send a body
--json '{...}' Send JSON
-i / -I Show headers (with/without body)
-v Verbose
-L Follow redirects
-o file / -O Save to a file
-f -s -S Script-friendly

EasySpawn gives you a terminal on the same server as your app, so curl against your own endpoints is the fastest way to see what's really happening — or to ask Claude Code to. See how it works or join the waitlist.

Related: How to Test an API · The Terminal for Complete Beginners · HTTP Headers Explained · What Is an API?

Keep reading