curl HTTP Client

curl cheatsheet — every flag for HTTP requests, downloads, auth, headers, and APIs. GET, POST, PUT, DELETE with real examples. No placeholders.

7 min read

What it is

curl is a command-line tool for transferring data with URLs, most commonly used for making HTTP requests to interact with web servers and APIs.

Installation

Linux (Debian/Ubuntu)

sudo apt update
sudo apt install curl

Linux (Fedora/CentOS/RHEL)

sudo dnf install curl
# or
sudo yum install curl

macOS

curl is typically pre-installed on macOS. If not, you can install it using Homebrew:

brew install curl

Windows

curl is included in Windows 10 and later. You can also install it via package managers like Chocolatey:

choco install curl

Or download from the official curl website.

Core Concepts

URL: The address of the resource you want to interact with (e.g., https://example.com/api/users).
Method: The HTTP method used for the request (e.g., GET, POST, PUT, DELETE). curl defaults to GET.
Headers: Metadata sent with the request (e.g., Content-Type, Authorization).
Body: Data sent with requests like POST or PUT.
Response: The data and status code returned by the server.

Commands / Usage

Making Basic Requests

GET a URL and show output:
```
curl https://httpbin.org/get
```
Fetches the content of the URL and prints it to standard output.
GET a URL and save to a file:
```
curl -o output.html https://example.com
```
Downloads the content of https://example.com and saves it to output.html.
GET a URL and save with original filename:
```
curl -O https://example.com/path/to/file.zip
```
Downloads the file and saves it with its original name (file.zip).
Follow redirects:
```
curl -L https://bit.ly/example-short-url
```
Automatically follows HTTP redirects (3xx status codes).
Show request and response headers:
```
curl -i https://example.com
```
Includes HTTP response headers in the output.
Show only response headers:
```
curl -I https://example.com
```
Performs a HEAD request and shows only the response headers.

Sending Data

POST data with application/x-www-form-urlencoded:
```
curl -d "name=John Doe&age=30" https://httpbin.org/post
```
Sends URL-encoded form data in the request body.

POST JSON data:

curl -X POST -H "Content-Type: application/json" -d '{"username": "testuser", "password": "password123"}' https://httpbin.org/post

Sends JSON data in the request body, setting the appropriate Content-Type header.

POST data from a file:

curl -d @data.json -H "Content-Type: application/json" https://httpbin.org/post

Reads the request body from the file data.json.

PUT data from a file:
```
curl -X PUT -T new_file.txt https://example.com/api/files/123
```
Uploads the content of new_file.txt using the PUT method.

Authentication

Basic Authentication:
```
curl -u username:password https://example.com/protected
```
Sends credentials using HTTP Basic Authentication.

Bearer Token Authentication:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" https://example.com/api/data

Sends an API key or token in the Authorization header.

Customizing Requests

Specify HTTP Method:
```
curl -X PUT https://example.com/api/resource/456
```
Uses the PUT HTTP method. Common methods: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS.

Add Custom Headers:

curl -H "X-Custom-Header: MyValue" https://example.com/api

Adds a custom header to the request.

Set User-Agent:
```
curl -A "MyCoolApp/1.0" https://example.com
```
Sets the User-Agent header to identify your client.
Set Referer:
```
curl -e "https://www.google.com" https://example.com
```
Sets the Referer header, indicating the page that linked to the current page.
Connect to a specific IP address:
```
curl --resolve example.com:443:192.168.1.100 https://example.com
```
Forces curl to use a specific IP address for a given host and port, bypassing DNS.
Use a specific network interface:
```
curl --interface eth0 https://example.com
```
Uses the specified network interface for the connection.
Timeout for connection and transfer:
```
curl --connect-timeout 5 --max-time 10 https://example.com
```
Sets a 5-second timeout for establishing the connection and a 10-second total timeout for the entire operation.

SSL/TLS

Insecure (ignore SSL errors):
```
curl -k https://self-signed.example.com
```
Skips SSL certificate verification. Use with extreme caution.
Specify SSL certificate:
```
curl --cert client.pem --key client.key https://example.com/secure
```
Uses a client certificate and private key for authentication.
Specify CA certificate bundle:
```
curl --cacert /path/to/ca-bundle.crt https://example.com
```
Uses a specific file containing trusted Certificate Authority certificates.

Cookies

Send a cookie:

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

Sends the specified cookie in the request.

Read cookies from a file:
```
curl -b cookies.txt https://example.com/login
```
Loads cookies from a Netscape cookie file.
Save cookies to a file:
```
curl -c cookies.txt https://example.com/login
```
Saves all cookies received from the server into cookies.txt.

Other Useful Options

Verbose output:
```
curl -v https://example.com
```
Shows detailed information about the connection and the request/response, including headers.
Silent mode (no progress meter):
```
curl -s https://example.com
```
Suppresses the progress meter and error messages.
Show only response body (even on errors):
```
curl -s -S --fail https://example.com/nonexistent-page
```
Shows the body even on HTTP errors (like 404) but fails silently otherwise.
Retry on failure:
```
curl --retry 5 --retry-delay 2 https://example.com/api/resource
```
Retries the request up to 5 times, with a 2-second delay between retries.
Pass through proxy:
```
curl -x http://proxy.example.com:8080 https://example.com
```
Uses the specified HTTP proxy for the request.
Download multiple files concurrently (requires parallel):
```
parallel --jobs 4 curl -O ::: https://example.com/file1.zip https://example.com/file2.zip
```
Uses parallel to download multiple files faster.

Common Patterns

Check API endpoint status:
```
curl -s -o /dev/null -w "%{http_code}" https://api.example.com/health
```
Prints only the HTTP status code (e.g., 200, 404, 500). Useful for scripting.

Send JSON and check status code:

curl -s -X POST -H "Content-Type: application/json" -d '{"key":"value"}' -o response.json -w "%{http_code}" https://api.example.com/create

Posts JSON, saves the response body to response.json, and prints the HTTP status code.

Download and extract a zip file:
```
curl -L -O https://example.com/archive.zip && unzip archive.zip
```
Downloads a zip file and then extracts it if the download was successful.
Fetch HTML and parse with grep:
```
curl -s https://example.com | grep "<h1>"
```
Fetches the HTML content of a page and searches for lines containing <h1> tags.
Automate login and get a session cookie:
```
curl -s -c cookies.txt -X POST -d "username=user&password=pass" https://example.com/login
```
Logs in to a site, saving the session cookie for subsequent requests.
Use saved cookies for subsequent requests:
```
curl -s -b cookies.txt https://example.com/dashboard
```
Accesses a protected page using previously saved session cookies.
Upload a file with a specific filename in the request:
```
curl -F "file=@/path/to/local/image.jpg;filename=profile.jpg" https://example.com/upload
```
Uploads image.jpg as a multipart/form-data field named file, with the server-side filename set to profile.jpg.

Gotchas

Default Method is GET: If you don’t specify a method (-X), curl assumes GET. This is often a surprise when trying to POST data without -X POST.
-d vs -F: -d sends data as the request body (often application/x-www-form-urlencoded or application/json if Content-Type is set). -F is for multipart/form-data, typically used for file uploads.
SSL Certificate Verification: By default, curl verifies SSL certificates. If you’re working with self-signed certificates or internal CAs, you’ll need -k (insecure) or --cacert.
Output Redirection: curl -o file.txt writes the body to file.txt. Use -O to save with the remote filename. Use -v or -i to see headers.
Progress Meter: The progress meter can interfere with scripts expecting clean output. Use -s (silent) to suppress it.
--data vs -d: Both are aliases. curl --data-urlencode is useful for ensuring data is correctly encoded for form submissions.
curl version differences: Some newer features or flags might not be available in older curl versions. Check curl --version.
Windows paths: On Windows, paths for -d @ or -F @ might require careful handling of backslashes depending on the shell. Using forward slashes often works reliably.