cURL Command in Linux: A Comprehensive Guide

Table of Contents

• Introduction to cURL
• Basic cURL Usage
• Specifying HTTP Methods
• Handling Headers
• Data Submission with cURL
• Downloading Files with cURL
• Uploading Files with cURL
• Authentication with cURL
• Advanced cURL Options
• Troubleshooting Common cURL Errors

Introduction to cURL

cURL (Client URL) is a powerful command-line tool available on most Linux distributions (and other Unix-like systems) used to transfer data to or from a server. It supports various protocols, including HTTP, HTTPS, FTP, FTPS, SCP, SFTP, TFTP, and more. This makes it incredibly versatile for tasks ranging from simple web requests to complex file transfers and automated scripting. cURL’s flexibility stems from its extensive command-line options, allowing fine-grained control over every aspect of the data transfer process.

Basic cURL Usage

The simplest way to use cURL is to fetch the contents of a URL:

curl https://www.example.com

This command will retrieve the HTML source code of the example.com website and print it to your terminal. If the website contains images or other media, they will be displayed as raw data in the terminal.

Specifying HTTP Methods

cURL allows you to specify different HTTP methods, such as GET, POST, PUT, DELETE, etc., using the -X or --request option.

• GET: Retrieves data from the server. This is the default method if not specified.

curl -X GET https://www.example.com/api/data

• POST: Sends data to the server to create or update a resource.

curl -X POST -d "name=John&email=john@example.com" https://www.example.com/api/users

• PUT: Replaces an existing resource on the server.

curl -X PUT -d "updated_data" https://www.example.com/api/data/123

• DELETE: Deletes a resource from the server.

curl -X DELETE https://www.example.com/api/data/123

Handling Headers

You can add custom headers to your requests using the -H or --header option. This is crucial for tasks like setting the Content-Type for POST requests or including authentication tokens.

curl -H "Content-Type: application/json" -X POST -d '{"key": "value"}' https://api.example.com/data

This example sends a JSON payload with a Content-Type header specifying the data format.

Data Submission with cURL

cURL offers several ways to submit data:

• -d or --data: Sends data as part of the request body (typically used with POST requests). Data can be in various formats (e.g., key-value pairs, JSON).
• -F or --form: Sends data as multipart/form-data (useful for file uploads).

Downloading Files with cURL

To download a file, use the -O or --output option to specify the local filename:

curl -O https://www.example.com/file.zip

This will download file.zip and save it in the current directory. You can specify a different directory by providing a full path.

Uploading Files with cURL

Uploading files is done using the -F option:

curl -F "file=@/path/to/file.txt" https://www.example.com/upload

Replace /path/to/file.txt with the actual path to your file.

Authentication with cURL

cURL supports various authentication methods:

• Basic Authentication: Use the -u or --user option:

curl -u username:password https://www.example.com/protected

• Other authentication methods (e.g., OAuth, API keys) often require custom headers.

Advanced cURL Options

cURL boasts many advanced options for handling cookies, timeouts, proxies, and more. Refer to the official cURL documentation for a complete list.

Troubleshooting Common cURL Errors

• curl: (6) Could not resolve host: The DNS lookup failed. Check your network connection and the URL.
• curl: (7) Failed to connect to: The server is unreachable. Check the server’s status and your network connection.
• curl: (28) Operation timed out: The request timed out. Increase the timeout using the --connect-timeout and --max-time options.
• HTTP error codes (e.g., 404 Not Found, 500 Internal Server Error): These indicate problems on the server side. Check the server logs for more details.

Remember to always consult the official cURL manual (man curl) for the most up-to-date information and a comprehensive list of options.