What is the cURL command? Understanding the syntax, options, and examples

The cURL (client URL) command in Linux enables your system to exchange data with servers via the internet. This tool is essential for various tasks, including downloading files and checking API functionality.

In this tutorial, we will explain all about the cURL command, including its installation and syntax. You will also learn several cURL command examples for real-world usage.

What is the cURL command?

The cURL utility lets you connect to a server and exchange data directly from your system’s command-line interface (CLI). You can determine the destination by specifying the endpoint’s URL address.

This command-line tool supports bidirectional transfer using different transfer methods, which we will explain in more detail later. Moreover, its compatibility with different protocols like HTTPS, SMTP, and FTP makes cURL a flexible utility.

Due to its convenience, the cURL Linux command is the preferred method for various tasks involving data transfer, like testing API. While alternative solutions, like Postman, are more comprehensive, they can be less straightforward.

Installing cURL

The cURL command should come pre-installed by default on most Linux operating systems. To check whether it is configured, open Terminal or connect via SSH if you use a remote virtual private server (VPS) platform. 

For Hostinger VPS users, you can also connect to your system with one click using Browser terminal. Simply open your VPS management page on hPanel and hit the button at the top right. 

After accessing your system’s CLI, run the following to check if cURL is installed:

curl --version

If your system has cURL, the CLI will return the installed version number. Otherwise, you will get the Command not found error.

To install it, run the following commands subsequently. Remember to replace apt with the correct package manager based on your Linux operating system:

sudo apt update && sudo apt upgrade

sudo apt install curl

cURL command basic syntax and options

The cURL command basic syntax looks as follows:

curl [options] [URL]

Here is the breakdown of the syntax:

• cURL – the command name telling your system that you are running cURL.
• Options – additional flags modifying the cURL command behavior.
• URL – the address of the destination server or endpoint. 

Since there are various options, check the cURL documentation for the full list. Among them, here are some of the most used ones:

• –help – prints the cURL command manual and options. 
• -O – downloads the original file from the given URL. 
• -L – follows the redirection URLs.
• -I – fetches only the header.
• -d – submits form data. 
• -F – uploads complex data or files. 
• -X – specifies the method for transferring data. 

The cURL command lets you send or fetch data from an endpoint using different HTTP methods:

• GET – the default method that fetches data from the server. 
• POST – sends data to the endpoint. 
• PUT – creates a resource on the endpoint or updates an existing one.
• DELETE – removes data from the endpoint.

cURL command examples

In this section, we will explore several real-world examples of the cURL command for various tasks.

Getting a web page

The most basic usage of the cURL command is to fetch the HTML content of a web page. To do so, simply run cURL with the destination endpoint like so:

curl https://www.google.com

The cURL command will output the web page’s HTML code as a standard output in your CLI.

You can also send HTTP requests to multiple URLs using a single command like so:

curl https://www.example1.com https://example2.com

Saving output to a file

You can save the cURL command’s output to a file by appending it with a redirection operation (>). This is helpful if you want to store the result for monitoring or archive.

For example, the following will store Google’s HTML content to file1.txt:

curl https://www.google.com > file1.txt

The command will create the file automatically if you don’t have one. Meanwhile, if file1.txt already exists, cURL will overwrite the existing file.

Downloading a file with its original name

One of cURL’s most common uses is downloading a remote file from the internet, similar to wget. To do so, use the -O option like:

curl -O http://www.example.com/path/file.zip

The command will download the specified file called file.zip to your current working directory. Without the -O option, cURL will display the file’s content as a standard output on your CLI.

Following redirects

If a URL redirects to another page, cURL won’t follow it and will return the 301 or 302 status. For example, let’s check googlr.com:

curl http://www.googlr.com

Since this URL redirects to google.com, cURL can’t follow it and return the 301 status indicating the document has moved.

To automatically follow the redirect and output google.com’s content, add the -L or –location option like so:

curl -L http://www.googlr.com

If the URL redirects multiple times, you can limit how many times cURL will follow it using the –max-redirs option like so:

curl -L --max-redirs 3 http://www.googlr.com

Fetching only headers

In some cases, fetching the endpoint’s response header is more helpful than retrieving the entire content. It shortens the output for simpler analysis and minimizes bandwidth consumption.

Information in response headers are generally sufficient for testing purposes. For example, it contains the HTTP response status, the remaining API calls, and redirects.

To fetch only the headers using cURL, add the -I (uppercase i) or –head option like so:

curl -I http://www.google.com

Authenticated requests

When sending a request to a secured endpoint like an internal API, typically you need to authenticate it by including the credentials in your cURL command.

Depending on the authentication method, however, the command and option differ. For example, run the following if you use a typical username and password:

curl -u username:password <URL>

You can also omit :password and enter it separately later to prevent the credential from showing on the bash history.

If you use the Bearer token, use the following command syntax:

curl -H "Authorization: Bearer <token>" <URL>

The command is similar if you use an API key in the header for authentication:

curl -H "Authorization: ApiKey <API key>" <URL>

If your API specifically needs the authorization key directly in the URL, you can add it using the following command:

curl "https://api.example.com/data?api_key=api_key"

Submitting form data

cURL lets you easily submit data to forms on an endpoint. This is useful if you want to automate the process using bash script or when you don’t want to interact with the destination’s web interface. 

Form submission using cURL requires you to specify the key-value pair. The key refers to the form name, while the value indicates the data you want to insert. The syntax looks like this:

key1=value1&key2=value2

You need two options, -X to specify the submission method and -d to indicate cURL that you want to insert data. The full command might look like this:

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

In the example, cURL uses the POST request to enter the credentials into the login page’s form.

When submitting form data, ensure it follows the URL naming format. For example, replace a space with %20 and an ampersand (&) with %26.

You can also insert data from a file using the following syntax. Make sure the file contains the data in the proper key-value pair format.

curl -X POST -d @data.txt https://example.com/login

Uploading a file

If you want to submit a local file or more complex data to an endpoint, use the -F option. This flag also assumes you use the POST method by default, so you don’t need to specify it manually with -X.

For example, the following sends a text file to the endpoint:

curl -F "file=@test.txt" https://example.com/upload

If you want to send multiple files, simply list them in your command, each starting with the -F option like so:

curl -F "file=@/path/to/image.jpg" -F "file=@/path/to/image2.jpg" https://example.com/upload

You can also upload files using cURL via the file transfer protocol (FTP). The difference is that you use the  -T option like so:

curl -T /path/to/file ftp://ftp.example.com/remote/path/

For a secure file transfer protocol (SFTP) or protected FTP server, add the authentication credentials before the -T option like so:

curl -u username:password -T /path/to/file sftp://sftp.example.com/remote/path/

Setting custom headers

Using custom request headers lets you interact with the web server or API in a specific way. It enables you to add specific metadata for a personalized response, which is useful when testing the endpoint’s functionality.

You can set a custom header with the -H option using this syntax:

​​curl -H "Header: value" <URL>

For example, you can specify the type of content you want to send in the header. Here’s the command:

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

You can also set a custom header to define the type of content you accept as a response. For example, if you want the endpoint to respond with JSON, use the following:

curl -H "Accept: application/json" https://api.example.com/data

When testing API, you can set a custom header to specify the version to use. The command looks like this:

curl -H "X-API-Version: 2" https://api.example.com/v2/data

Using different protocols

Depending on the endpoint, you might need to use different protocols with cURL. For example, you might want to use SFTP to transfer files while testing a mailing server requires SMTP.

To run cURL using different protocols, simply specify it at the beginning of your endpoint’s URL before ://. For example, this command will transfer data using SMTP:

curl --url smtp://smtp.example.com --mail-from "user@example.com" --mail-rcpt "recipient@example.com" -T email.txt

The command will send a message from user@example.com to recipient@example.com via the smtp.example.com mailing server using the SMTP protocol.

Conclusion

The cURL command in Linux lets your system connect to and transfer data with a server. It is known for its compatibility with various protocols and ability to include additional information, like a custom header.

While cURL is pre-installed in most Linux distributions, you can configure it manually using your package manager. The basic usage of this command is to fetch a web page’s content or an API response.

You can also download files using cURL with the -O option or upload items by adding the -F flag. Moreover, use -H to specify a custom request header for various purposes, including adding an authentication token and specifying the API version.

To send form data using cURL, use the -d option. Meanwhile, add the -F flag to upload more complex resources like files.

cURL command FAQ