The Practical cURL Guide: From Basic Requests to Advanced Usage

cURL is the Swiss Army knife of HTTP requests. It's installed on virtually every machine, it's scriptable, and once you know the key flags you can test any API from your terminal in seconds. This guide covers the commands you'll use every day.

The Basics

The simplest cURL command fetches a URL with a GET request:

Simple GET request

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

By default, cURL prints the response body to stdout. Add flags to control the request method, headers, body, and output.

Essential Flags

Flag	Description
`-X METHOD`	Set HTTP method (GET, POST, PUT, PATCH, DELETE)
`-H 'Key: Value'`	Add a request header
`-d 'data'`	Send request body (implies POST)
`-o file`	Write output to a file instead of stdout
`-O`	Save file with its remote filename
`-v`	Verbose — show request/response headers
`-s`	Silent — hide progress bar and errors
`-L`	Follow redirects (3xx responses)
`-k`	Skip TLS certificate verification (dev only)
`-i`	Include response headers in output
`-w 'format'`	Custom output format (timing, status code)
`--max-time N`	Timeout after N seconds

Common Request Patterns

GET with Headers

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

POST JSON Data

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

PUT (Update)

curl -X PUT https://api.example.com/users/123 \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -d '{"name": "Jane Updated"}'

DELETE

curl -X DELETE https://api.example.com/users/123 \
     -H "Authorization: Bearer YOUR_TOKEN"

POST Form Data

curl -X POST https://api.example.com/login \
     -d "username=jane&password=secret123"

Authentication

Bearer Token

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
     https://api.example.com/protected

Basic Auth

curl -u username:password https://api.example.com/basic
# Equivalent to:
curl -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
     https://api.example.com/basic

API Key (Header)

curl -H "X-API-Key: your-api-key-here" \
     https://api.example.com/data

API Key (Query Parameter)

curl "https://api.example.com/data?api_key=your-api-key-here"

File Operations

Upload a File

# Multipart form upload
curl -X POST https://api.example.com/upload \
     -F "file=@/path/to/document.pdf" \
     -F "description=Quarterly report"

# Raw file body
curl -X PUT https://api.example.com/files/doc.pdf \
     -H "Content-Type: application/pdf" \
     --data-binary @/path/to/document.pdf

Download a File

# Save with custom filename
curl -o report.pdf https://example.com/files/report.pdf

# Save with remote filename
curl -O https://example.com/files/report.pdf

# Download with progress bar
curl -# -O https://example.com/large-file.zip

Debugging Requests

When an API call isn't working, these flags help you figure out why:

See Everything (Verbose)

curl -v https://api.example.com/users
# Shows: DNS resolution, TLS handshake, request headers,
# response headers, and body

Get Just the Status Code

curl -s -o /dev/null -w "%{http_code}" https://api.example.com/health
# Output: 200

Measure Response Time

curl -s -o /dev/null -w "DNS: %{time_namelookup}s
Connect: %{time_connect}s
TLS: %{time_appconnect}s
TTFB: %{time_starttransfer}s
Total: %{time_total}s
" https://api.example.com/users

Response Headers Only

curl -I https://api.example.com/users
# Same as: curl --head

Useful Recipes

Pretty-Print JSON Response

curl -s https://api.example.com/users | python3 -m json.tool
# Or with jq:
curl -s https://api.example.com/users | jq .

Follow Redirects

curl -L https://short.url/abc123
# Follows 301/302 redirects to the final URL

Send Cookies

# Send a cookie
curl -b "session=abc123" https://example.com/dashboard

# Save cookies to a file, then reuse
curl -c cookies.txt https://example.com/login -d "user=jane&pass=secret"
curl -b cookies.txt https://example.com/dashboard

Retry on Failure

curl --retry 3 --retry-delay 2 https://api.example.com/unreliable

Rate-Limited Loop

Bash script

for i in $(seq 1 100); do
  curl -s "https://api.example.com/items/$i" >> results.json
  sleep 0.5
done

Building the API you're testing?

DigitalOcean App Platform deploys your API directly from a Git repo with auto-scaling, free SSL, and built-in monitoring. Test locally with cURL, push to deploy.

cURL to Code

Once you've tested your request with cURL, convert it to your language of choice. Our cURL to Code Converter transforms any cURL command into Python, JavaScript (fetch), Node.js, Go, PHP, and more — paste your command and get clean, idiomatic code instantly.

You can also use the JSON Formatter to pretty-print API responses, and the URL Parser to break down complex endpoint URLs into their components.