cURL is a powerful command-line tool for transferring data with servers using various protocols. Here's a comprehensive guide to the most essential cURL options and flags every developer should know.
Request Methods and Data
-d or --data
Sends data in a POST request using application/x-www-form-urlencoded format.
# Form data
curl -d "username=user&password=pass" https://example.com/login
# JSON data (requires Content-Type header)
curl -d '{"name":"John","email":"john@example.com"}' \
-H "Content-Type: application/json" \
https://example.com/api/users
-X or --request
Specifies the HTTP request method (GET, POST, PUT, DELETE, PATCH, etc.).
# DELETE request
curl -X DELETE https://api.example.com/users/123
# PUT request with data
curl -X PUT -d '{"status":"active"}' \
-H "Content-Type: application/json" \
https://api.example.com/users/123
-F or --form
Submits form data using multipart/form-data encoding, perfect for file uploads.
# Simple form data
curl -F "name=John" -F "age=30" https://example.com/submit
# File upload
curl -F "file=@document.pdf" -F "description=Important doc" \
https://example.com/upload
Headers and Authentication
-H or --header
Adds custom headers to the request. Can be used multiple times.
# API key authentication
curl -H "Authorization: Bearer your-token-here" \
-H "Content-Type: application/json" \
https://api.example.com/data
# Multiple headers
curl -H "Accept: application/json" \
-H "User-Agent: MyApp/1.0" \
-H "X-Custom-Header: value" \
https://example.com/api
-u or --user
Provides username and password for HTTP basic authentication.
# Basic auth
curl -u username:password https://secure.example.com/data
# Prompt for password (more secure)
curl -u username https://secure.example.com/data
Output and Information
-o or --output
Saves output to a specific file instead of displaying it.
# Save to file
curl -o webpage.html https://example.com
# Save API response
curl -o users.json https://api.example.com/users
-O (uppercase)
Saves the file using the remote filename from the URL.
# Downloads and saves as "file.zip"
curl -O https://example.com/downloads/file.zip
-I or --head
Fetches only HTTP headers, useful for checking status codes and metadata.
# Check if URL exists
curl -I https://example.com
# Check API endpoint status
curl -I https://api.example.com/health
-v or --verbose
Shows detailed information about the request and response process.
# Debug request/response
curl -v https://example.com
# Combine with other options
curl -v -H "Authorization: Bearer token" https://api.example.com/data
Navigation and Redirects
-L or --location
Automatically follows HTTP redirects (301, 302, etc.).
# Follow redirects
curl -L https://short.ly/redirect-url
# Limit redirect hops
curl -L --max-redirs 5 https://example.com
Timeouts and Retries
--connect-timeout
Sets maximum time for connection establishment.
# 10 second connection timeout
curl --connect-timeout 10 https://slow-server.com
--max-time
Sets maximum total time for the entire operation.
# 30 second total timeout
curl --max-time 30 https://example.com/large-file
--retry
Automatically retries failed requests.
# Retry up to 3 times on failure
curl --retry 3 --retry-delay 2 https://unreliable-api.com
Cookies and Sessions
-c or --cookie-jar
Saves cookies to a file for session persistence.
# Save cookies
curl -c cookies.txt https://example.com/login
# Use saved cookies
curl -b cookies.txt https://example.com/dashboard
-b or --cookie
Sends cookies with the request.
# Send specific cookie
curl -b "session=abc123" https://example.com/protected
# Use cookie file
curl -b cookies.txt https://example.com/api
Advanced Options
-s or --silent
Suppresses progress meter and error messages.
# Silent mode for scripts
curl -s https://api.example.com/status | grep "ok"
-w or --write-out
Displays specific information after the request completes.
# Show response time and status
curl -w "Status: %{http_code}\nTime: %{time_total}s\n" \
-s -o /dev/null https://example.com
# Show various metrics
curl -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTotal: %{time_total}s\n" \
-s -o /dev/null https://example.com
Practical Examples
API Testing
# Complete API workflow
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-token" \
-d '{"title":"New Post","content":"Hello World"}' \
-w "Status: %{http_code}\n" \
https://api.example.com/posts
File Download with Progress
# Download with progress bar
curl -L -o large-file.zip https://example.com/files/large-file.zip
# Download silently for scripts
curl -s -L -o update.tar.gz https://releases.example.com/latest.tar.gz
Health Check Script
# Simple health check returning only status code
curl -s -o /dev/null -w "%{http_code}" https://api.example.com/health
These options can be combined to create powerful, customized requests for any scenario. Use curl --help or man curl to explore the complete list of available options and flags.
