cURL Cheat Sheet
curl http api reference
Basic Syntax
curl [options] <URL>
Common Options
Output Control
| Option | Description |
|---|
-o <file> | Write output to file |
-O | Save with remote filename |
-s | Silent (no progress) |
-S | Show errors even with -s |
-v | Verbose (debug) |
-i | Include response headers |
-I | Headers only (HEAD request) |
-w <format> | Custom output format |
Request Methods
| Option | Description |
|---|
-X GET | GET request (default) |
-X POST | POST request |
-X PUT | PUT request |
-X PATCH | PATCH request |
-X DELETE | DELETE request |
| Option | Description |
|---|
-H "Header: Value" | Add header |
-d "data" | POST data |
-d @file | POST data from file |
--data-raw "data" | POST data without interpretation |
--data-urlencode "k=v" | URL-encode the data |
-F "field=value" | Multipart form data |
-F "file=@path" | Upload file |
HTTP Methods Examples
GET
# Simple GET
curl https://api.example.com/users
# With headers
curl -H "Authorization: Bearer TOKEN" https://api.example.com/users
# Query parameters
curl "https://api.example.com/users?page=1&limit=10"
# Show response headers
curl -i https://api.example.com/users
POST
# JSON body
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-d '{"name": "John", "email": "john@example.com"}'
# From file
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-d @payload.json
# Form data
curl -X POST https://api.example.com/login \
-d "username=john&password=secret"
# Form data (URL encoded)
curl -X POST https://api.example.com/search \
--data-urlencode "query=hello world"
PUT / PATCH
# PUT (full update)
curl -X PUT https://api.example.com/users/123 \
-H "Content-Type: application/json" \
-d '{"name": "John Updated", "email": "john@example.com"}'
# PATCH (partial update)
curl -X PATCH https://api.example.com/users/123 \
-H "Content-Type: application/json" \
-d '{"name": "John Updated"}'
DELETE
curl -X DELETE https://api.example.com/users/123 \
-H "Authorization: Bearer TOKEN"
Authentication
Bearer Token
curl -H "Authorization: Bearer eyJhbGciOi..." https://api.example.com/protected
Basic Auth
curl -u username:password https://api.example.com/auth
# Or with header
curl -H "Authorization: Basic $(echo -n 'user:pass' | base64)" https://api.example.com/auth
API Key
# In header
curl -H "X-API-Key: your-api-key" https://api.example.com/data
# In query string
curl "https://api.example.com/data?api_key=your-api-key"
File Operations
Download
# Save with specified name
curl -o filename.zip https://example.com/file.zip
# Save with remote name
curl -O https://example.com/file.zip
# Resume download
curl -C - -O https://example.com/largefile.zip
# Follow redirects
curl -L -O https://example.com/file.zip
# Silent with progress bar
curl -# -O https://example.com/file.zip
Upload
# Single file
curl -X POST -F "file=@/path/to/file.pdf" https://api.example.com/upload
# Multiple files
curl -X POST \
-F "file1=@/path/to/file1.pdf" \
-F "file2=@/path/to/file2.pdf" \
https://api.example.com/upload
# With metadata
curl -X POST \
-F "file=@/path/to/file.pdf" \
-F "description=My document" \
https://api.example.com/upload
SSL/TLS Options
# Skip certificate verification (insecure!)
curl -k https://self-signed.example.com
# Specify CA certificate
curl --cacert /path/to/ca.crt https://api.example.com
# Client certificate
curl --cert /path/to/client.crt --key /path/to/client.key https://api.example.com
# Force TLS version
curl --tlsv1.2 https://api.example.com
curl --tlsv1.3 https://api.example.com
# Show certificate info
curl -vvI https://api.example.com 2>&1 | grep -A6 "Server certificate"
Proxy Settings
# HTTP proxy
curl -x http://proxy.example.com:8080 https://api.example.com
# SOCKS proxy
curl --socks5 localhost:9050 https://api.example.com
# Proxy with auth
curl -x http://user:pass@proxy.example.com:8080 https://api.example.com
# Bypass proxy
curl --noproxy "*.internal.com" https://api.example.com
curl -w "\n
time_namelookup: %{time_namelookup}s\n
time_connect: %{time_connect}s\n
time_appconnect: %{time_appconnect}s\n
time_pretransfer: %{time_pretransfer}s\n
time_redirect: %{time_redirect}s\n
time_starttransfer: %{time_starttransfer}s\n
time_total: %{time_total}s\n
http_code: %{http_code}\n
size_download: %{size_download} bytes\n
" -o /dev/null -s https://api.example.com
Timeouts
# Connection timeout (seconds)
curl --connect-timeout 5 https://api.example.com
# Max time for whole operation
curl --max-time 30 https://api.example.com
Debugging
Verbose Output
# Standard verbose
curl -v https://api.example.com
# Very verbose
curl -vvv https://api.example.com
# Trace (most detailed)
curl --trace - https://api.example.com
curl --trace-ascii - https://api.example.com
# HEAD request (just headers)
curl -I https://api.example.com
# GET with headers shown
curl -i https://api.example.com
Useful Patterns
Check if URL is up
curl -Is https://api.example.com | head -1
# HTTP/2 200
Get public IP
curl ifconfig.me
curl ipinfo.io/ip
curl icanhazip.com
JSON Pretty Print
curl -s https://api.example.com/data | jq .
curl -s https://api.example.com/data | python -m json.tool
Loop with delay
while true; do
curl -s https://api.example.com/health
sleep 5
done
Save headers and body separately
curl -D headers.txt -o body.json https://api.example.com/data
# Content type
-H "Content-Type: application/json"
-H "Content-Type: application/x-www-form-urlencoded"
-H "Content-Type: multipart/form-data"
# Accept
-H "Accept: application/json"
-H "Accept: text/html"
# Auth
-H "Authorization: Bearer TOKEN"
-H "X-API-Key: KEY"
# Custom
-H "X-Request-ID: $(uuidgen)"
-H "X-Forwarded-For: 10.1.1.1"
Exit Codes
| Code | Meaning |
|---|
| 0 | Success |
| 1 | Unsupported protocol |
| 3 | Malformed URL |
| 6 | Couldn’t resolve host |
| 7 | Couldn’t connect |
| 22 | HTTP error (with -f) |
| 28 | Timeout |
| 35 | SSL connect error |
| 52 | Empty reply |
| 56 | Network recv error |
Use -f to fail on HTTP errors:
curl -f https://api.example.com/endpoint || echo "Request failed"