How to Use Curl

Curl is a powerful command-line utility and underlying library (libcurl) used to transfer data across a wide range of network protocols, including HTTP, HTTPS, FTP, FTPS, SCP, SFTP, LDAP, MQTT, and more. It supports features like proxy support, user authentication, cookies, file uploads, and SSL connections, making it a go-to tool for developers, system administrators, and anyone working with web APIs or networked services.

This article walks you through using curl to perform a variety of HTTP requests from your terminal. You’ll learn how to download files, set custom headers, work with different HTTP methods, handle redirects, send JSON payloads, authenticate with servers, and troubleshoot using verbose mode. Whether you're testing APIs or automating network operations, curl is a powerful tool to have in your workflow.

The Short Answer Version

If you just want a quick reference for common curl commands, here’s a compact list of essentials:

# Basic GET request
$ curl https://example.com

# Save output to file
$ curl -o page.html https://example.com

# Follow redirects
$ curl -L http://example.com

# Send POST form data
$ curl -d "name=John&age=30" -X POST https://example.com

# Send JSON payload
$ curl -X POST -H "Content-Type: application/json" -d '{"name":"John"}' https://example.com

# Add custom header
$ curl -H "Authorization: Bearer <token>" https://api.example.com

# Basic auth
$ curl -u user:pass https://example.com

Using Curl

This section expands on the quick reference above and explains basic curl operations in more detail, including file downloads, protocol handling, and request formatting. These commands are commonly used for testing connectivity or fetching public web content.

The basic syntax of the curl command is:

$ curl [options] <URL>

curl Command Options

Detailed Usage

The following sections explain how each curl command works in more detail. You'll find examples, syntax breakdowns, and usage notes to help you understand what each option does and when to use it. These walkthroughs complement the quick reference section above for users who prefer step-by-step explanations.

Download a Webpage

To download a webpage and print its source code to the terminal.

Command Syntax

$ curl <URL>

Example

$ curl https://www.example.com/index.html

Use FTP Protocol

To retrieve a file using FTP.

Command Syntax

$ curl ftp://<host>/<path>

Example

$ curl ftp://ftp.example.com/public/readme.txt

Save Output to a File

Save the downloaded output to a local file instead of printing it to the terminal.

Command Syntax

$ curl -o <filename> <URL>
$ curl -O <URL>

• -o: Save output with a custom filename.
• -O: Save output using the remote filename.

Example

$ curl -o localcopy.html https://example.com/index.html
$ curl -O https://example.com/index.html

Resume an Interrupted Download

If a download was interrupted (e.g., due to network issues), use this option to resume it from where it left off instead of restarting from scratch.

Command Syntax

$ curl -C -O <URL>

• -C -: Resume download.
• -O: Save using remote file name.

Example

$ curl -C -O https://example.com/bigfile.zip

Enable Verbose Output

Enable verbose output to debug request/response communication.

Command Syntax

$ curl -v <URL>

• -v: Verbose mode.

Example

$ curl -v https://example.com

Making HTTP Requests

Curl provides a wide range of options to interact with web services. This section covers how to inspect headers, follow redirects, change HTTP methods, and customize request headers.

Get Only Response Headers

Fetch only the response headers of a URL.

Command Syntax

$ curl -I <URL>

• -I or --head: Fetch headers only.

Example

$ curl -I https://example.com

Follow Redirects

Enable following of HTTP 3xx redirects.

Command Syntax

$ curl -L <URL>

• -L: Follow redirects.

Example

$ curl -L http://example.com

Change the HTTP Method

Set a custom HTTP method using -X.

Command Syntax

$ curl -X [METHOD] <URL>

• -X: Specify HTTP method (e.g., GET, POST, DELETE).

Example

$ curl -X DELETE https://example.com/resource/123

Add Custom Headers

Use the -H flag to add one or more HTTP headers.

Command Syntax

$ curl -H "Header-Name: value" <URL>

Example

$ curl -H "User-Agent: Mozilla/5.0" -H "Cache-Control: no-cache" https://example.com

Set a Custom User-Agent

Use --user-agent to define the request’s User-Agent string.

Command Syntax

$ curl --user-agent "[Agent String]" <URL>

Example

$ curl --user-agent "Mozilla/5.0 (Macintosh)" https://example.com

Send Form or JSON Data (POST)

Use curl to send form-encoded or JSON data in HTTP POST requests. This is essential for interacting with REST APIs or submitting data to a server.

Command Syntax

$ curl -d "<key1=value1&key2=value2>" -X POST <URL>
$ curl -X POST -H "Content-Type: application/json" -d '<JSON>' <URL>

Example

$ curl -d "name=John&age=30" -X POST https://example.com
$ curl -X POST -H "Content-Type: application/json" -d '{"name":"John"}' https://example.com

Basic Authentication

When accessing resources protected by HTTP Basic Auth, use the -u option to include your credentials directly in the request.

Command Syntax

$ curl -u <username>:<password> <URL>

Example

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

Advanced Usage and Tips

This section covers advanced curl patterns commonly used in scripts, automation, and API integrations.

$ curl --fail <URL>

$ curl --fail https://example.com/missing-file

$ curl -w "%{time_total}\n" -o /dev/null -s <URL>

$ curl -w "%{time_total}\n" -o /dev/null -s https://example.com

$ curl -F "key=@filename.ext" <URL>

$ curl -F "file=@report.pdf" https://example.com/upload

$ curl -H "Authorization: Bearer <your_token>" <URL>

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

$ curl -s <URL>

$ curl -v <URL>

$ curl -s https://example.com

$ curl -v https://example.com

Conclusion

Curl is an essential tool for developers and system administrators who need to interact with web servers, APIs, and remote resources from the command line. This article covered both quick-use examples and detailed explanations for common curl operations such as downloading files, handling headers, sending data, and authenticating requests.

For further exploration, refer to the official curl documentation or man page to discover protocol-specific features, scripting tricks, and advanced usage patterns.