What Is the cURL Command? [+ How to Use It]

Roger Winter

Published:

As a current (or aspiring) web developer, there’s a good chance you’re familiar with HTTP requests, especially when interacting with APIs.

person writing a curl command on a laptop

API platforms can be helpful for automating your requests calls and building more sophisticated requests. But sometimes, whether you’re doing a one-off test or some debugging, you want to fire off a quick HTTML request from your terminal.

For these situations, cURL is one of the best free web dev tools around, and something every developer should have handy.

In this article, we’ll introduce the cURL command, explore how and why it’s used, and showcase some common cURL command examples and use cases.

Download Now: Free HTML & CSS Hacks

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 forms of 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.

How to Use cURL

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

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

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

The syntax of a cURL command is:

cURL [options] [URL]

This article uses the JSONPlaceholder Fake 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:

cURL https://jsonplaceholder.typicode.com/todos/1

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:

cURL -X [METHOD] [URL]

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

cURL -X GET https://jsonplaceholder.typicode.com/todos/1

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 return 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), which is 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:

cURL -X POST -d "name=cURL&type=article" https://jsonplaceholder.typicode.com/posts

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 to it 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:

cURL -X POST -d '{"name": "cURL", "type": "article"}' https://jsonplaceholder.typicode.com/posts

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:

cURL -X POST -d '{"name": "cURL", "type": "article"}' -H "Content-Type: application/json" https://jsonplaceholder.typicode.com/posts

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:

cURL -X DELETE https://jsonplaceholder.typicode.com/posts/1

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:

cURL -X PUT -d '{"name": "json", "type": "post"}' -H "Content-Type: application/json" https://jsonplaceholder.typicode.com/posts/1

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

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

cURL -T [selected-file] "ftp://[target-destination]"

cURL makes for a good replacement for a standard FTP client.

Simple Mail Transfer Protocol

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

cURL smtp://[smtp-sever] --mail-from [sender] --mail-rcpt \ [receiver] --upload-file [mail-content-file]

Dictionary Network Protocol

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

cURL "dict://dict.org/d:hello"

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

You can find more protocols on the cURL man page.

Common Use Cases for cURL

While API platforms usually provide intuitive interfaces for requesting and transferring data to a URL, cURL can be a great tool to use with the terminal. Here are some common use cases for the cURL command.

Quickly Testing APIs From the Terminal

As we’ve seen, cURL allows you to test APIs quickly form your terminal without having to download any API-based application.

Downloading Images and Files to a Device

Since the terminal has access to the file system, you can also download images from URLs easily.

For example, here’s the Google logo URL. Using cURL, you can download the image like this:

cURL https://www.google.com/images/branding/googlelogo/2x/googlelogo_light_color_272x92dp.png > google-logo.png

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

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:

cURL -o google.html https://www.google.com

This 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 under 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 to use by every user. By providing the URL and the options needed, you can request and download data from URLs, transfer data to URLs, and more.

New Call-to-action

Related Articles

We're committed to your privacy. HubSpot uses the information you provide to us to contact you about our relevant content, products, and services. You may unsubscribe from these communications at any time. For more information, check out our Privacy Policy.

Learn more about HTML and CSS and how to use them to improve your website.