The Ultimate cURL Guide and Cheat Sheet

Introduction

cURL is a command-line tool for transferring data with URLs, supporting various protocols like HTTP, HTTPS, FTP, and more. It’s designed to be minimalistic yet powerful, making it ideal for tasks like testing APIs, downloading files, and sending data to web services. Unlike Wget, cURL focuses on transferring data rather than mirroring or recursion, and it often shines in scripting workflows and interacting with RESTful APIs.

By default, cURL comes pre-installed on most Unix-like operating systems including macOS and many Linux distros. It can also be installed on Windows. Understanding its basic and advanced features helps you automate network data transfers efficiently.

cURL is also one of the now core commands implemented in Linux during the 1996 major update. You can read more about the Linux Command history and timeline following this command: The Linux Command Timeline.

General Syntax

curl [options] <URL>

• Where URL is just the address of the resource or service you want to interact with.

Key Options

Below is a list of frequently used cURL options. Each option is followed by an example since sometimes with cURL you have to enter specific values to certain options which vary in format. So, by adding an example right below the option we hope it’ll help you understand how to properly apply the option.

• -o — Writes output to the specified file instead of stdout.

curl -o archive.zip https://example.com/data.zip

-O — Saves the file with the same name as it appears on the server.

curl -O https://example.com/data.zip

-L / –location — Follows server redirects (3xx responses) automatically.

curl -L https://example.com/redirect

-I —Fetches HTTP headers only (HEAD request), no response body.

curl -I https://example.com/

-s / –silent — Suppresses progress bar and error messages (combine with -S to show errors).

curl -s https://example.com/data.zip -o data.zip

-S / –show-error —Shows errors when combined with –silent.

curl -sS https://example.com/nonexistent.txt -o output.txt

-v / –verbose —Displays detailed debugging information about the request.

curl -v https://example.com/

-X — Specifies the request method (e.g., GET, POST, PUT, DELETE).

curl -X PUT -d 'update' https://api.example.com/resource

-d — Sends data with the request (usually for POST). If used with -X GET, it will still send data, but some servers might ignore it.

curl -d "username=admin&password=secret" https://example.com/login

-H “Header: value” —Adds or modifies an HTTP header.

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

-u — Uses basic HTTP authentication.

curl -u admin:secret https://example.com/protected/

Basic Usage Examples

1. Download a File and Rename It

curl https://example.com/file.txt -o myfile.txt

Saves the downloaded file as myfile.txt.

2. Follow Redirects

curl -L https://example.com/redirect -o final.html

Ensures cURL follows all HTTP 3xx redirects until it reaches the final page.

3. Send Data with POST

curl -X POST -d 'param1=value1&param2=value2' https://example.com/api/submit

Sends form URL-encoded data to the server.

Advanced Usage

Working with APIs

JSON Data and Headers

curl -X POST -H "Content-Type: application/json" \
-d '{"title":"Test","content":"Hello world"}' \
https://example.com/api/posts

• Sets the Content-Type header to application/json.
• Sends JSON data with -d.

Authentication

Basic Authentication

curl -u username:password https://example.com/secret

Bearer Token Authentication

curl -H "Authorization: Bearer <token>" https://example.com/secure-data

Passing Cookies

Using a Cookie File

curl --cookie cookies.txt https://example.com/account

• –cookie: Reads the stored cookies from cookies.txt and includes them in the request.

Saving Cookies

curl --cookie-jar new_cookies.txt https://example.com/login

• –cookie-jar: Saves cookies received from the server into new_cookies.txt.

Proxy Support

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

• -x: Specifies the proxy server to use for all requests.

Insecure SSL / Custom CA Certificates

Skip SSL Certificate Validation
(Use only if you trust the target and need to bypass validation.)

curl -k https://example.com/

Use a Custom CA Certificate

curl --cacert /path/to/ca.crt https://internal.example.com/

• –cacert: Uses the provided certificate to validate the server.

Additional Tips

1. Output to stdout vs. File: By default, cURL prints the response body to stdout. Use -o or -O to save to a file.
2. Custom Request Methods: While cURL defaults to GET, you can specify any valid HTTP method with -X. If sending data, cURL typically sets the method to POST unless overridden.
3. Combine Flags: You can combine short flags like -sS (silent with error output) or -vL (verbose + follow redirects).
4. Debugging: -v, –trace, and –trace-ascii options are invaluable for debugging complex request/response scenarios.
5. Using with Shell Scripts: cURL is easily integrated into scripts for automation, e.g., checking server health or uploading files periodically.

Related Tools

cURL is more than often used in combination with Wget. You can access the Wget tutorial following this link: The Ultimate Wget Guide and Cheat Sheet.