cURL is a powerful command-line tool for transferring data with URLs. Below are commonly used options and real-world usage patterns, rewritten for clarity, correctness, and reduced redundancy.

Core Options Overview

• -v / --verbose: Enables detailed output—including request headers, response headers, and connection metadata—ideal for debugging HTTP interactions.
• -m / --max-time <seconds>: Sets the total timeout (in seconds) for the entire operation, including DNS resolution, connection, and transfer.
• -H / --header <header>: Adds custom HTTP headers (e.g., -H "Accept: application/json").
• -s / --silent: Suppresses progress meter and error messages; often paired with -w for structured output.
• -x / --proxy <[protocol://]host[:port]>: Routes requests through an HTTP or SOCKS proxy.
• -T / --upload-file <file>: Uploads a local file via PUT or POST depending on context (e.g., to FTP or HTTP endpoints).
• -o / --output <file>: Writes response body to a specified local file (e.g., curl -o report.json https://api.example.com/data).
• -O / --remote-name: Saves the remote resource using its original filename (requires full path in URL).
• -d / --data / --data-ascii: Sends data in a POST request with Content-Type: application/x-www-form-urlencoded.
• --connect-timeout <seconds>: Limits how long cURL waits to establish a connection.
• --retry <num>: Retries failed requests up to n times (useful for flaky networks).
• -e / --referer <URL>: Sets the Referer header explicitly.
• -I / --head: Sends a HEAD request and prints only response headers.

HTTP Status Code Inspection

To extract only the HTTP status code without body or verbose noise:

curl -s -w "%{http_code}" -o /dev/null https://httpbin.org/status/200

This outputs 200, discarding the response body and suppressing progress indicators.

Inspecting Response Headers

Use -i to include headers *and* body in output:

curl -i https://httpbin.org/get?test=1

Use -I to fetch headers only (HEAD request):

curl -I https://httpbin.org/status/404

Proxy Configuration

Route traffic through a corporate or local proxy:

curl -x http://192.168.1.10:8080 https://example.com

Connectivity Verification

A simple GET to test basic reachability and TLS handsahke:

curl -s -o /dev/null -w "%{http_code}\n" https://www.baidu.com

Downloading Files

Save responses to disk:

• curl -o index.html https://example.com → saves as index.html
• curl -O https://example.com/file.pdf → saves as file.pdf
• Fetch multiple resources efficiently (reuses connections):
  curl -O https://site.com/a.txt -O https://site.com/b.txt

Resumable Downloads

Resume interrupted transfers using -C -:

# Initial partial download
curl -C - -o manual.html https://www.gnu.org/software/gettext/manual/gettext.html

# Later, resume from last known byte offset
curl -C - -o manual.html https://www.gnu.org/software/gettext/manual/gettext.html

Bandwidth Throttling

Limit transfer rate for testing or fairness:

curl --limit-rate 50K -O https://example.com/large.zip

Conditional Fetching with Timestamps

Download only if remote file was modified after a given date:

curl -z "15-Oct-2024" -O https://example.com/log.txt

Authentication

Basic auth with username/password:

# Inline credentials (avoid in shared environments)
curl -u alice:secret123 https://api.example.com/private

# Secure variant: prompts for password interactively
curl -u alice https://api.example.com/private

FTP Uploads

Push files to FTP servers:

# Single file
curl -u user:pass -T document.pdf ftp://ftp.example.com/uploads/

# Multiple files using brace expansion
curl -u user:pass -T "{report.csv,config.json}" ftp://ftp.example.com/uploads/

# Stream stdin directly
echo '{"status":"active"}' | curl -u user:pass -T - ftp://ftp.example.com/data/payload.json

Cookie Management

Persist session state across requests:

# Save cookies from login response
curl -c session.cookie -d "user=admin&pass=123" https://app.example.com/login

# Reuse saved cookies in subsequent calls
curl -b session.cookie https://app.example.com/dashboard

Data Submission Methods

Send payloads beyond simple GET parameters:

• POST with form-encoded data:
  curl -d "name=John&city=NYC" https://api.example.com/users
• Auto-urlencode spaces and special chars:
  curl --data-urlencode "query=hello world!" https://api.example.com/search
• Read payload from file:
  curl --data @payload.json https://api.example.com/submit
• Custom HTTP method:
  curl -X PATCH -H "Content-Type: application/json" --data '{"active":true}' https://api.example.com/item/123
• File upload via multipart/form-data:
  curl -F "file=@photo.jpg;type=image/jpeg" https://api.example.com/upload