curl

Curl shows you what your code sees.

When your application makes an HTTP request, it doesn't see a rendered webpage. It sees headers, status codes, and raw response bodies. Curl gives you that same view from the command line—the unvarnished truth of what's happening on the wire.

Why This Matters

A web browser hides the HTTP conversation behind rendered HTML and JavaScript execution. Curl strips all that away. You see:

• The exact headers your server sends and receives
• Status codes that tell you what actually happened (not what your app interpreted)
• Response timing down to the millisecond
• The raw body before any parsing or transformation

This transparency makes curl indispensable for testing APIs, debugging failed requests, and understanding why something works in a browser but breaks in your code.

Curl ships with macOS and most Linux distributions. It's been actively developed for over 25 years.

The Basics

Fetch a URL:

curl https://example.com

You get raw HTML, not a rendered page.

Save the output:

curl -o myfile.html https://example.com     # Custom filename
curl -O https://example.com/report.pdf      # Original filename

Follow redirects (curl doesn't by default):

curl -L https://example.com

Seeing the Conversation

This is where curl becomes powerful.

Include headers in output:

curl -i https://example.com

Shows HTTP headers followed by the response body. You see what status code came back, what content type was declared, whether caching headers are set.

Headers only:

curl -I https://example.com

Performs a HEAD request—just the headers, no body. Fast way to check if something exists or see server configuration.

The full conversation:

curl -v https://example.com

This is curl's most revealing mode. You watch the entire handshake unfold:

• DNS lookup resolving the domain
• TCP connection establishing
• TLS handshake negotiating encryption (for HTTPS)
• Your request headers going out
• Response headers coming back
• The response body

When something fails and you don't know why, -v shows you where it broke.

HTTP Methods

GET (the default):

curl https://api.example.com/users

POST with JSON:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"name":"John","email":"john@example.com"}' \
  https://api.example.com/users

POST with form data:

curl -X POST -d "name=John&email=john@example.com" https://api.example.com/users

POST with data from a file:

curl -X POST -H "Content-Type: application/json" -d @data.json https://api.example.com/users

The @ reads from the file.

PUT, PATCH, DELETE:

curl -X PUT -H "Content-Type: application/json" -d '{"name":"Updated"}' https://api.example.com/users/123
curl -X PATCH -H "Content-Type: application/json" -d '{"email":"new@example.com"}' https://api.example.com/users/123
curl -X DELETE https://api.example.com/users/123

Headers and Authentication

Set headers with -H:

curl -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Accept: application/json" \
     https://api.example.com/data

Basic authentication:

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

API keys:

curl -H "X-API-Key: YOUR_KEY" https://api.example.com/data

Cookies

Send a cookie:

curl -b "sessionid=abc123" https://example.com

Save cookies from a response:

curl -c cookies.txt https://example.com/login -d "user=john&pass=secret"

Use saved cookies:

curl -b cookies.txt https://example.com/dashboard

File Uploads

curl -F "file=@document.pdf" https://api.example.com/upload
curl -F "file=@document.pdf" -F "title=My Document" https://api.example.com/upload

The -F flag sends multipart/form-data, which is what servers expect for file uploads.

Timing and Performance

Get total request time:

curl -w "\nTime: %{time_total}s\n" https://example.com

Detailed timing breakdown:

curl -w "\nDNS: %{time_namelookup}s\nConnect: %{time_connect}s\nFirst byte: %{time_starttransfer}s\nTotal: %{time_total}s\n" https://example.com

Just the status code:

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

Testing and Debugging

Set timeouts:

curl --connect-timeout 5 --max-time 10 https://example.com

Fails if connection takes over 5 seconds or total request exceeds 10 seconds.

Force a specific TLS version:

curl --tlsv1.3 https://example.com

Test before DNS propagates:

curl --resolve example.com:443:93.184.216.34 https://example.com

Forces curl to resolve the domain to your specified IP. Useful for testing a new server before switching DNS.

Ignore SSL errors (testing only):

curl -k https://self-signed.example.com

Never use -k in production. It disables certificate validation entirely.

Proxies

curl -x http://proxy.example.com:8080 https://example.com
curl -x socks5://proxy.example.com:1080 https://example.com

Scripting

Check if a site is up:

if curl -f -s -o /dev/null https://example.com; then
  echo "Site is up"
else
  echo "Site is down"
fi

Get the status code into a variable:

STATUS=$(curl -s -o /dev/null -w "%{http_code}" https://example.com)
echo "Status: $STATUS"

Useful flags for scripting:

• -s suppresses progress output
• -S shows errors even when -s is used
• -f returns non-zero exit code on HTTP errors (404, 500, etc.)
• -o /dev/null discards the response body

Security

Never ignore SSL errors in production. The -k flag makes you vulnerable to man-in-the-middle attacks.

Protect credentials. Don't put passwords in commands that will appear in shell history:

curl -u username:$PASSWORD https://api.example.com

Be careful with -v output. It shows your authentication headers. Don't paste verbose output into public issue trackers.

Quick Reference