19 Useful cURL Commands that You Should Know

cURL is a command-line utility and a library for receiving and sending data between a client and a server, or any two machines connected via the internet. HTTP, FTP, IMAP, LDAP, POP3, SMTP, and a variety of other protocols are supported.

cURL is a project with the primary goal of creating two products:

• curl is a command-line tool
• libcurl is a C-based transfer library

Both the tool and the library use Internet protocols to transport resources given as URLs.

Curl is in charge of anything and anything that has to do with Internet protocol transfers. Things unrelated to that should be avoided and secured for other initiatives and products.

It's also worth remembering that curl and libcurl aim to avoid handling the actual data being sent. It knows nothing about HTML or any other type of content that is commonly transferred over HTTP, but it understands all there is to know about transferring data over HTTP.

Both products are frequently used for server testing, protocol fiddling, and trying out new things, in addition to driving thousands or millions of scripts and applications for an Internet-connected society. With its versatility, cURL is utilized in a wide range of applications and scenarios.

We'll look at how to utilize the UNIX cURL command line to conduct various tasks in this tutorial.

1. Set Up First
2. cURL Simple Command Usage
3. Downloading Files
4. Following Redirects
5. Viewing Response Headers
6. View Request Headers and Connection Information
7. Silencing Errors
8. Setting HTTP Request Headers
9. Make POST Requests
10. Submit JSON Data
11. Change the Request Method
12. Making cURL Fail on HTTP Errors
13. Make Authenticated Requests
14. Testing Protocol Support
15. Setting the Host Header
16. cURL's --resolve Flag
17. Resolve Domains to IPv4 and IPv6 Addresses
18. Disabling cURL’s Certificate Checks
19. cURL Configuration Files

#1 Set Up First

macOS

cURL is preloaded on macOS and receives upgrades whenever Apple publishes new versions of the operating system. You can, however, install the curl Homebrew package if you want to install the most latest version of cURL. You can use the following commands to install Homebrew:

brew install curl

Windows

Since version 1804 of Windows 10, the curl tool has been included as part of the operating system. Download and install the newest official curl release for Windows from curl.se/windows if you have an older Windows version or simply want to upgrade to the latest version delivered by the curl project.

You'll discover a folder titled curl-<version number>-mingw once you've downloaded and extracted the ZIP file. Place this folder in a location of your choosing. We'll assume that our folder is called curl-7.98.0-win64-mingw and that it's located on C:\.

The bin directory of cURL should then be added to the Windows PATH environment variable so that Windows can discover it when you run curl on the command prompt. You must take the following steps for this to work:

• Run systempropertiesadvanced from the Windows Run dialogue (Windows key + R) to open the "Advanced System Properties" window.
• Select “Environment Variables”.
• Add the path C:\curl-7.98.0-win64-mingw\bin by double-clicking on “Path” in the “System variables” section. This may be done in Windows 10 by pressing the right-hand “New” button. You can enter ;C:\curl-7.98.0-win64-mingw\bin (note the semicolon at the beginning) at the end of the “Value” text box on previous versions of Windows.

After you've completed the preceding steps, use curl to see if it's working. If everything went well, you should be able to see something similar to this:

C:\Users\Administrator> curl

Linux

cURL is installed by default on most Linux distributions. Type curl into your terminal window and press enter to see if it's installed on your machine. It will display a “command not found” message if it is not installed. To install it on your machine, run the steps listed below.

Use the following for Ubuntu/Debian-based systems:

sudo apt update
sudo apt install curl

For CentOS/RHEL systems:

sudo yum install curl

For Fedora systems:

sudo dnf install curl

#2 cURL Simple Command Usage

The following is the basic syntax for using cURL:

curl <url>

This retrieves the content from the specified URL and prints it to the terminal.

At funet's ftp-server, get the README file in the user's home directory:

curl ftp://ftp.funet.fi/README

Using port 8000, retrieve a web page from a server:

curl http://www.weirdserver.com:8000/

Obtain an FTP site's directory listing:

curl ftp://ftp.funet.fi

Use a dictionary to look up the meaning of curl:

curl dict://dict.org/m:curl

This is the most basic action that cURL can take. We'll look at the many command-line functions that cURL accepts in the following sections.

#3 Downloading Files

As we've seen, cURL downloads the content of a URL and publishes it to the terminal. If you want to save the output as a file, use the -o option to provide a filename, such as:

curl -o vlc.dmg
http://ftp.belnet.be/mirror/videolan/vlc/3.0.4/macosx/vlc-3.0.4.dmg

cURL switches to displaying a lovely progress bar with download information, such as the speed and time taken, in addition to saving the contents.

You can use the -O option to let cURL figure out the filename instead of manually giving one. So, if you want to save the above URL to the vlc-3.0.4.dmg file, just type:

curl -O http://ftp.belnet.be/mirror/videolan/vlc/3.0.4/macosx/vlc-3.0.4.dmg

If you use the -o or -O options and a file with the same name already exists, cURL will overwrite it.

If you have a partially downloaded file, use the -C - option to resume the download, as demonstrated below:

curl -O -C - http://ftp.belnet.be/mirror/videolan/vlc/3.0.4/macosx/vlc-3.0.4.dmg

You may combine different options, just like with most other command-line tools. You could, for example, combine -O -C - and write it as -OC - in the above command.

#4 Following Redirects

When cURL gets a redirect after a request, it does not initiate a request to the new URL by default. Consider the online cURL test URL http://www.instagram.com as an example. The server sends an HTTP 3XX redirect to https://www.instagram.com/ when you make a request using this URL. The response body, on the other hand, is completely empty.

The -L option should be used if you wish cURL to follow these redirects. Make a request for http://www.instagram.com/ with the -L flag again, as follows:

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

Please keep in mind that cURL can only follow redirects if the server returned an "HTTP redirect" response, which means the server used a 3XX status code and the "Location" header to identify the new URL. Javascript or HTML-based redirection mechanisms, as well as the "Refresh header," are not supported by cURL.

#5 Viewing Response Headers

When troubleshooting a website, look at the HTTP response headers given by the server. The -i option can be used to enable this feature.

Let's stick with our prior example and see if there is an HTTP 3XX redirect when you go to http://www.instagram.com/ by running:

curl -L -i http://www.instagram.com/

It's worth noting that we also used -L to allow cURL to track redirects. Instead of -L -i, you can combine these two options and write them as -iL or -Li.

The response headers and body will be stored in a single file if you use the -o/-O option in combination with -i.

#6 View Request Headers and Connection Information

We saw how to use cURL to inspect HTTP response headers in the previous section. However, you may wish to see more information about a request, such as the request headers sent and the connection procedure, on occasion. For this, cURL provides the -v flag (sometimes known as "verbose mode"), which can be used as follows:

curl -v https://www.atatus.com/

Request data, response headers, and other information about the request, such as the IP used and the SSL handshake process, are all included in the output.

Most of the time, we aren't interested in the body of the cURL show response. Simply “save” the output to the null device, which on Linux and macOS is /dev/null and on Windows is NUL.

curl -vo /dev/null https://www.atatus.com/    # Linux/MacOS
curl -vo NUL https://www.atatus.com/          # Windows

#7 Silencing Errors

When you save the output to a file, cURL displays a progress bar, as we've seen before. Unfortunately, the progress bar may not be appropriate in many situations. When you use -vo /dev/null to hide the output, for example, a progress bar shows, which is completely useless.

Using the -s header, you can hide all of these extra outputs. If we go with our prior example but remove the progress indicator, the commands are as follows:

curl -svo /dev/null https://www.atatus.com/      # Linux/MacOS
curl -svo NUL https://www.atatus.com/            # Windows

The -s option, on the other hand, is a little overbearing, as it even hides error messages. If you wish to conceal the progress bar but still see any errors, you can combine the -S option with your use case.

If you merely want to conceal the progress indicator while saving cURL output to a file, you can use:

curl -sSvo file.html https://www.atatus.com/

#8 Setting HTTP Request Headers

You may need to set special headers on HTTP requests while testing APIs. The -H option in cURL can be used for this purpose. You should run the following command to transmit the custom header X-My-Custom-Header with the value 123 to https://httpbin.org/get:

curl -H 'X-My-Custom-Header: 123' https://httpbin.org/get

httpbin.org is a very helpful website that allows you to see the specifics of each HTTP request you've made to it.

The data provided by the URL confirms that this header was set.

You can also override any of cURL's default headers, such as the "User-Agent" and "Host" headers.

• The “User-Agent” header is sent by the HTTP client (in our example, cURL) to inform the server about the type and version of the client being used.
• The “Host” header is also used by the client to inform the server about the site it should serve. Since a web server might host numerous websites at the same IP address, this header is required.

You can also repeat the -H option as needed if you wish to set numerous headers.

curl -H 'User-Agent: Mozilla/5.0' -H 'Host: www.instagram.com' https://www.instagram.com/

cURL, on the other hand, has a few shortcuts for commonly used flags. The "User-Agent" header can be set with the -A option:

curl -A Mozilla/5.0 http://httpbin.org/get

The “Referer” header is used to inform the server of where they were referred from the previous site. Browsers like google chrome send it when they request Javascript or images linked to a page, or when they follow redirects. The -e flag can be used to provide a "Referer" header:

curl -e https://www.instagram.com/ https://httpbin.org/get

And if you're following a series of redirects, simply use -e ';auto', and cURL will handle the redirects for you.

#9 Make POST Requests

cURL sends GET requests by default, but you can use the -d or --data options to send POST requests. The ampersand (&) character must be used to separate all of the fields as key=value pairs. Make a POST request to httpbin.org with the following arguments, for example:

curl --data "firstname=atatus" https://httpbin.org/post

Any special characters in the value, such as @, %, =, or spaces, should be manually URL-encoded. So, if you wanted to enter the value "test@example.com" for the argument "email," you'd use:

curl --data "email=test%40example.com" https://httpbin.org/post

You may also use --data-urlencode to take care of this for you. This is how you should use the option if you wanted to input two arguments, email, and name:

curl --data-urlencode "email=test@example.com" --data-urlencode "name=atatus" https://httpbin.org/post

If the --data option is too long to type in on the terminal, save it to a file and submit it with @:

curl --data @params.txt example.com

So far, we've seen how to use cURL to make POST requests. Use the -F (“form”) option if you want to upload files using a POST request. We'll send the file test.c here, with the parameter name file:

curl -F file=@test.c https://httpbin.org/post

#10 Submit JSON Data

We saw how to use cURL to submit POST requests in the previous section. You can also use the --data option to input JSON data. Most servers, on the other hand, anticipate receiving a POST request with key=value pairs similar to the ones we mentioned earlier.

As a result, you'll need to add a header named "Content-Type: application/json" to ensure that the server recognizes that it's working with JSON data and responds accordingly. When uploading JSON, you also don't need to URL-encode the data.

So, suppose you wish to send a POST request to https://httpbin.org/post with the following JSON data:

{
  "email": "test@example.com",
  "name": [ "atatus" ]
}

After that, send the data to:

curl --data '{"email":"test@example.com", "name": ["atatus"]}' -H 'Content-Type: application/json' https://httpbin.org/post

In the httpbin.org output, the data appears beneath the JSON value.

You may alternatively save the JSON file and submit it using the same method as before:

curl --data @data.json https://httpbin.org/post

#11 Change the Request Method

We've already seen how to use cURL to send POST requests. You may need to send a POST request with no data at all on occasion. In that scenario, simply use the -X option to change the request method to POST, as seen below:

curl -X POST https://httpbin.org/post

You can also alter the method of the request to anything other, like PUT, DELETE, or PATCH. The HEAD method is one significant example, as it cannot be set using the -X option. The HEAD method is used to see if a document is available on the server without having to download it. Use the -I option to use the HEAD method:

curl -I https://www.atatus.com/

When you make a HEAD request, cURL automatically displays all of the request headers. When servers get a HEAD request, they do not send any content, therefore there is nothing after the headers.

#12 Making cURL Fail on HTTP Errors

Interestingly, cURL does not distinguish between a successful (2xx) and an unsuccessful (4xx/5xx) HTTP request.

Learn more about HTTP Status code - A Complete Guide to Understand HTTP Status Codes

As a result, if there was no trouble connecting to the site, it always returns a 0 (zero) exit status. This makes creating shell scripts difficult because there is no method to check if the file was correctly downloaded.

You can manually verify this by submitting the following request:

curl https://www.atatus.com/404 -sSo file.txt

If you wish to take into account certain HTTP errors as well, use the -f option, as follows:

curl https://www.atatus.com/404 -fsSo file.txt

#13 Make Authenticated Requests

Some websites and APIs require login and password authentication. There are two options for accomplishing this. With the -u option, you can specify the username and password:

curl -u atatus:@t@tus https://example.com/

Alternatively, you can simply include it in the URL itself, using the format <username>:<password>@<host>, as shown:

curl https://atatus:@t@tus@example.com/

Curl uses “Basic” authentication with the server in each of these techniques.

#14 Testing Protocol Support

You can even use cURL to evaluate protocol support because of the vast number of protocols it supports. The --<sslvversion> and --tlsv<version> flags can be used to see if a site supports a specific version of SSL. If you wish to see if a site supports TLS v1.2, for example, you can use:

curl -v --tlsv1.2 https://www.atatus.com/

The request is processed normally, indicating that the site is compatible with TLSv1.2. Let's see if the site supports SSL v3 now:

curl -v --sslv3 https://www.atatus.com/

This command throws a handshake_failed exception because the server doesn’t support this version of SSL.

Please keep in mind that some of these version options may not work based on your system and library version/configuration.

#15 Setting the Host Header

We previously examined how a web server determines which websites to serve to users based on the "Host" header. By adjusting the "Host" header, you may check if your website's virtual hosting is configured appropriately.

As an example, suppose you have a local server with two websites configured, sample1.com and sample2.com, at 192.168.0.1. Set the Host header and check that the correct contents are served to see if everything is configured correctly:

curl -H 'Host: sample1.com' http://192.168.0.1/
curl -H 'Host: sample2.com' http://192.168.0.1/

Unfortunately, this isn't the case with HTTPS-enabled websites. A single website can be set up to serve several websites, each of which will have its SSL/TLS certificate.

Since SSL/TLS operates at a lower level than HTTP, clients like cURL must notify the server whose website we're trying to access at the SSL/TLS level for the server to select the appropriate certificate. By default, cURL informs the server of this.

However, if you want to send a request to a specific IP address, such as in the example above, the server may choose the incorrect certificate, causing the SSL/TLS verification to fail. The Host header is only useful on the HTTP level, not on SSL/TLS.

#16 cURL's --resolve Flag

The --resolve flag can be used to avoid the problem outlined above. The resolve flag will deliver the request to the port and IP of your choice, while appropriately sending the website name over SSL/TLS and HTTP.

Consider the preceding scenario. You can use the following syntax to send HTTPS to the local server 192.168.0.1:

curl https://sample1.com/ --resolve sample1.com:192.168.0.1:443

It's also good for HTTP. If your HTTP server was listening on port 8080, you might use the --resolve flag or manually set the Host header and the port, as seen below:

curl http://192.168.0.1:8080/ -H 'Host: sample1.com:8080'
curl http://sample.com/ --resolve sample1.com:192.168.0.1:8080

The two commands shown above are the same.

#17 Resolve Domains to IPv4 and IPv6 Addresses

Sometimes you'll want to see if a website can be accessed using both IPv4 and IPv6. Using the -4 and -6 flags, you may compel cURL to connect to either the IPv4 or IPv6 version of your site.

Please keep in mind that a website can only be accessed through IPv4 or IPv6 if:

• The website has appropriate DNS entries that connect it to IPv4 and IPv6 addresses.
• On your machine, you have IPv4 and IPv6 connectivity.

You can run the following command to see if you can visit the website icanhazip.com over IPv6:

curl -6 https://icanhazip.com/

If the site is accessible through HTTPS, the output should include your IPv6 address. Any client that connects to this website will receive the public IP address of that client. As a result, it shows an IPv4 or IPv6 address, depending on the protocol.

Know the difference between IPv4 and IPv6 - Difference Between IPv4 and IPv6: Why haven't We Entirely Moved to IPv6?

You can also use the -v option in combination with the -4 and -6 options to acquire extra information.

#18 Disabling cURL’s Certificate Checks

When connecting via HTTPS, cURL examines certificates by default. When you're trying to make requests to sites that utilize self-signed certificates, or if you need to test a site with a misconfigured certificate, it's typically handy to disable certificate checking.

Use the -k certificate to disable certificate checking. We'll put this to the test by sending a request to expired.badssl.com, a website with an expired SSL certificate.

curl -k https://expired.badssl.com/

The certificate checks are skipped when using the -k option. As a result, cURL successfully downloads the page and shows the request body. You will, however, receive an error if you did not utilize the -k option.

#19 cURL Configuration Files

You might want to use the same options for all cURL requests at times. Because passing these options by hand isn't a possibility, cURL lets you provide them in a configuration file.

In Linux/macOS, the default configuration file is placed in ~/.curlrc, whereas in Windows, it is found in %appdata%\_curlrc. You can define any options you require within this file.

Make a request with curl example.com after you've created the above file. You'll notice that these options are now active.

If you want to use a different configuration file than the default, use the -K option to point curl to it. If you have a configuration file named config.txt, for example, you can utilize it with:

curl -K config.txt example.com

Conclusion

The most common uses of the cURL command have been covered in this article. Of course, this article only scratches the surface; cURL is capable of much more. Visit the Curl Documentation website for more information about curl.

Monitor Your Entire Application with Atatus

Atatus provides a set of performance measurement tools to monitor and improve the performance of your frontend, backends, logs, and infrastructure applications in real-time. Our platform can capture millions of performance data points from your applications, allowing you to quickly resolve issues and ensure digital customer experiences.

Atatus can be beneficial to your business, which provides a comprehensive view of your application, including how it works, where performance bottlenecks exist, which users are most impacted, and which errors break your source code for your frontend, backend, and infrastructure.

Try your 14-day free trial of Atatus.