What is the cURL Command

Understanding HTTP requests and how to interact with APIs is crucial, particularly when it comes to automating requests and debugging. In such scenarios, when I need to execute a quick HTML request, cURL comes in handy.

Client URL (cURL) lets you exchange data between your device and a server through a command-line interface (CLI). By simply specifying a server URL and the data to be sent, cURL enables diverse request forms, much like API tools like Postman and Insomnia, but directly from your terminal.

In this article, I will introduce the cURL command, explore how and why it's used, and showcase some common cURL command examples and use cases.

What is the cURL command?

Client URL (cURL, pronounced "curl") is a command line tool that enables data exchange between a device and a server through a terminal. Using this command line interface (CLI), a user specifies a server URL (the location where they want to send a request) and the data they want to send to that server URL.

API tools like Postman and Insomnia provide an interactive user interface (UI) that allows you to make different requests to URLs for receiving and processing requests. The cURL command does the same thing, except in your terminal. cURL works on Linux, Mac, and Windows.

The cURL command uses the libcURL client-side URL transfer library. This library supports many different transfer protocols, including HTTPS, SMTP, and FTP. It also enables you to include cookies, set proxies, and add authentication credentials when making requests.

Use cases of cURL include testing APIs, downloading data from sources, testing websites, and following redirects from the terminal.

Syntax of A cURL Command

The basic syntax of the curl command can include options and the URL:

cURL [options] [URL]

• options: I take advantage of options when I want to customize the behaviors of my request.
• URL: The URL or location specified tells the cURL command where I want to access data from or send data.

Curl Command Without Options

I stored a list of my favorite books in a JSON file on Git Hub. To retrieve the list of books in the terminal, I used the cURL command without any options. You can try the command below, and your output will look exactly like the example below.

Curl Command With Options

Using the cURL command without options displayed the raw contents of the file. However, when I want to download the file to my server, I run the cURL command with the -O option.

After running this command, I see an output that confirms the file has been downloaded.

I always run the ls command to double-check the file is listed in my directory.

In the next section, I will explain how to use the cURL command in more detail.

How to Use cURL Command in Linux

You know what the cURL command is and its syntax, but how does it work?

cURL comes pre-installed on Windows and macOS - otherwise, you can download the package from thecURL website.

The cURL command receives the URL to transfer data to - or receive data from - along with other options for different purposes.

In this section, I will use the JSONPlaceholderFake API to explain the different ways to use cURL. This mock API contains different example paths for making requests.

Request Data From a Source

Using the GET method with cURL, you can quickly request data from a source or API. Here's a simple cURL command that makes a GET request:

Without passing any flags or options, the cURL command defaults to making a GET request to the specified URL. The command returns the response body sent from the API, which would look like this in your terminal:

{ "userId": 1, "id": 1, "title": "delectus aut autem", "completed": false }

This is similar to the results from platforms like Postman, shown below:

Additionally, you can include options and values to use a different request method with the cURL command. For example, you can use the -X (hyphen and uppercase X) option with the request method. The -X option is an alias for --request.

Write the command as follows:

The default GET method in the first cURL command above is the same as the following:

Send Data to a Source

Using the POST method and the cURL command, you can transfer data to a server through an API. The API processes the data, then takes steps such as saving it to a database, and returns a response indicating the status of your request.

To make a POST request to a URL, use the -X option and pass the POST method as the value. But how about adding data with the request? You use another option, -d (hyphen and lowercase d), an alias for --data.

You can use the two popular data formats when sending data with a request: application/x-www-form-urlencoded or application/json. We'll cover both of these methods next.

application/x-www-form-URLencoded

If you do not specify the format you want, cURL uses application/x-www-form-urlencoded by default. Here's an example using this format and the JSON fake API:

This command makes a POST request to https://jsonplaceholder.typicode.com/posts and passes the URL encoded data "name=cURL&type=article" which is a name key with a cURL value and a type key with an article value.

For POST requests made to the JSON Fake API, the response body is the data object sent along with an ID property.

Here's the response body from the API after entering the command:

{ "name": "cURL", "type": "article", "id": 101 }

application/JSON

With cURL, you can also send a stringified JSON object like this:

As described above, the data in this request is sent in the application/x-www-form-urlencoded format. Here's the result from the API:

{ "{\"name\": \"cURL\", \"type\": \"article\"}": "", "id": 101 }

The API understands the request data to be in URL encoded data format, so it doesn't interpret it as you would expect. You must specify that this is the JSON data format by using the -H (hyphen with an uppercase H) option, an alias for --header, and passing the Content-Type header as follows:

Now, you get the right response body from the API:

{ "name": "cURL", "type": "article", "id": 101 }

Instead of typing the JSON string in the terminal, you can specify a JSON file that the cURL command will use for the data option. For example, suppose you have a file called data.json with the following contents:

{ "name": "cURL", "type": "article" }

You can run the cURL command, assuming it's in the same project as the file. This command will get the JSON file, stringify it, and send it with the request. You get the same result as above:

{ "name": "cURL", "type": "article" }

Delete Resources on a Server

You can send deletion requests to an API using the DELETE method and the cURL command. The URL and data you provide to this request depend on the API configuration.

For the JSON Fake API, you specify the resource path and the DELETE method like this:

The response body is an empty object:

{}

Best for Updating Existing Resources Using an API

Using the PUT method and the cURL command, you can make "update" requests to an API that modify an existing resource. For the JSON Fake API, you specify the resource path and the PUT method and pass some data to update the resource.

You can use any data format you want here. This example uses application/json:

You must directly specify the data format in the header so that the API can interpret the request correctly.

The above code returns this response body:

{ "name": "json", "type": "post", "id": 1 }

cURL Protocols and Formats

By default, cURL uses the HTTP protocol. Here are some other protocols and formats that cURL can use:

File Transfer Protocol(FTP)

The File Transfer Protocol (FTP) transfers files from a server to a client. Use this protocol with cURL to upload files like this:

cURL makes for a good replacement for a standardFTP client.

Simple Mail Transfer Protocol(SMTP)

The Simple Mail Transfer Protocol (SMTP) is used to send data to an SMTP server. This data consists of the text you're sending, the sender, and the receiver. It looks like this:

Dictionary Network Protocol(DICT)

The Dictionary Network Protocol (DICT) provides access to dictionaries. Using it with cURL, you run the following command:

With this command, you get a result showing the dictionary selected and the meaning of "hello" from the dictionary.

Gopher(s)

The gopher protocol can be used to search, distribute, and retrieve documents from the web in the terminal. The command looks like this:

Hypertext Protocol Transfer Secure(HTTPS)

HTTPS is a popular protocol that simplifies retrieving data, API interactions, automating tasks such as tests, and several network operations when used with the curl from the command line.

When using this protocol, the data that is transmitted across servers can maintain confidentiality and integrity thanks to HTTP's secure encrypted connection. Run the following command, but be sure to specify the web address you want to access:

Internet Message Protocol(IMAP)

Using IMAP(s) with the curl command enables mail server interaction, retrieval and reading of email messages, and mailbox management. I use the IMAP protocol when I want to search my inbox from the command line.

Using the command structure above, I am able to search my inbox for emails containing a certain word.Replace "example" with the word you want to find in emails. Change "//imap.example.com/INBOX" with your IMAP server address + the mailbox you want to search.

Lightweight Directory Access Protocol(LDAP)

Using cURL with LDAP is great for accessing and managing servers that store directory service information. If you want to use the command line to complete tasks like authenticate users, update your directory, or modify your access control list, it's worth using the LDAP protocol.

This command will start an LDAP connection to example.com on port 389 and perform a search starting from the base distinguished name(DN) dc=example,dc=com. Make sure to replace example.com and the base DN with your LDAP server's actual hostname and base DN.

Post Office Protocol Version 3(POP3)

POP3 can be used with the cURL command to retrieve emails from a mail server to a local environment. If you want to use a script to automate managing your email, you should definitely try out this command protocol duo.

While it's possible to use POP3 with curl, it is less secure and has limited capabilities.

Real-Time Streaming Protocol(RTSP)

If you want to interact with streaming media servers from the command line, you can use the RTMP protocol with cURL. The command structure looks like this:

Keep in mind, that the actual video will not be displayed in the terminal. Instead, you will get a text-based response about the media you are requesting.

You can find more protocols on the cURL man page.

Outputs of Curl Command

While API platforms usually provide intuitive interfaces for requesting and transferring data to a URL, cURL can be an excellent tool for the terminal. Here are some everyday use cases for the cURL command and the output of the system.

Quickly Testing APIs From the Terminal Output

As we've seen, cURL allows you to test APIs quickly from your terminal without downloading any API-based application. Let's use the geolocation API provided by Google. The following command returns the time zone of the Dallas Cowboy Stadium:

Check out the output from the command below:

Downloading Images and Files to a Device Output

Since the terminal has access to the file system, you can also download images from URLs easily. For example, here's the Google logoURL. Using cURL, you can download the image like this:

Check out the output from the command below:

Using cURL and the URL of the image returns the binary data of the image. By storing the raw image data in an image file (with a .png extension matching the extension of the original image), you can save the image on your device.

Saving URL Content Output

Like downloading images, you can also save the content of a URL (for example, a web page) to a file. Here's an example for the Google homepage:

The output below saves the source code of the Google homepage to a file called google.html.

Make cURL work for you.

cURL is a CLI tool that allows you to request and transfer data over a URL using different protocols. It gives you flexibility and control of URLs on the terminal.

Using cURL on the terminal is simple but may not be intuitive for every user. By providing the URL and the options needed, you can request and download data from URLs, transfer data to URLs, and more.

Editor's note: This post was originally published in August 2022 and has been updated for comprehensiveness.

Don't forget to share this post!