What is cURL?
curl, which stands for client URL, is a command-line tool for transferring data to or from a server. curl lets you talk to a server by specifying the location in the form of a URL and the data you want to send.
curl supports several different protocols, including HTTP, HTTPS, SCP, POP3, SMTP, IMAP, SFTP, and FTP, and runs on almost any platform. This makes curl ideal for testing communication from almost any local server with command line access and network connectivity.
curl provides a load of options such as proxy support, user authentication, FTP upload, HTTP post, SSL connections, cookies, file transfer resume and many more.
Why use curl?
curl is an extremely useful tool with the following benefits:
- curl is highly portable and is compatible with virtually every operating system and connected device.
- curl is useful for testing endpoints, to quickly check if they are working.
- curl can be provide verbose output, providing details of exactly what has been sent and received which is very useful for debugging.
- curl has excellent error logging.
- curl can be rate limited.
In this tutorial, we will show you how to use the curl tool through practical examples and detailed explanations of the most common curl options.
How to Install curl on Linux
curl is pre-installed on most Linux distributions. To check on your system, open up a console, type curl, and then press enter. If curl is installed, you will see the following:
$ curl
curl: try 'curl --help' or 'curl --manual' for more information
Install Curl on Ubuntu and Debian
$ sudo apt update
$ sudo apt install curlInstall Curl on CentOS and Fedora
$ sudo yum install curlHow to Use curl
The syntax for the curl command is as follows:
$ curl [options] [URL...]
Basic HTTP GET Request
The basic GET command without any options:
$ curl example.com
This command will retrieve the example.com homepage and displays it to the default standard output, in this case the terminal.
If no protocol is specified, curl tries to guess the protocol you want to use, and it will default to HTTP. To choose HTTPS use:
$ curl https://example.com/
Get the HTTP Response Headers
By default the response headers are hidden in the output of curl. To show them, use the i option:
$ curl -i https://example.com/
Show only the HTTP response headers
Using the I option, you can get just the headers, and not the response body:
$ curl -I https://example.com/
Perform an HTTP POST request
The X option lets you change the HTTP method used. By default, GET is used, and would be the same as entering:
$ curl -X GET https://example.com/
Using -X POST will perform a POST request instead.
For example, you can perform a POST request while passing URL-encoded data with the d option as follows:
$ curl -d "option=VALUE1&something=VALUE2" -X POST https://example.com/
Perform an HTTP POST request sending JSON
Instead of posting data URL-encoded, like in the previous example, you might want to send JSON.
To do this you can explicitly set the Content-Type header using the H option:
$ curl -d '{"option": "value1", "something": "value2"}' -H "Content-Type: application/json" -X POST https://example.com/You can also send a JSON file from your local file system:
$ curl -d "@my-local-file.json" -X POST https://example.com/Perform a PUT request
Perhaps the best way to upload data to a HTTP server is to use PUT:
$ curl --upload-file myfile http://www.example.com/Of course, this requires that the server knows how to receive the HTTP PUT stream.
Follow a redirect
You can automatically follow a redirect response, such as 301, by specifying the L option:
$ curl -L http://example.com/The above command will automatically follow to the HTTPS version if a redirect has been setup.
Store the response to a file
Using the o option you can tell curl to save the response to a file:
$ curl -o file.html https://example.com/You can also just save a file by its name on the server, using the O option:
$ curl -O https://example.com/index.htmlUse curl with Basic HTTP authentication
If a resource requires Basic HTTP Authentication, you can use the u option to pass user:password values:
$ curl -u user:pass https://example.com/Use curl with Proxy Authentication
Sometimes HTTP access is only available through the use of a HTTP proxy, and this may require its own user and password to allow the client to get through.
$ curl --proxy-user proxyuser:proxypassword example.comIf the proxy requires the authentication to be done using the NTLM method, use --proxy-ntlm, if it requires Digest use --proxy-digest.
If you use any one of these user+password options but leave out the password, curl will prompt for the password interactively.
Specify a different User Agent
The user agent tells the server which client is performing the request.
By default curl sends the curl/<version> user agent, for example: curl/7.54.0.
You can specify a different user agent using the --user-agent option:
$ curl --user-agent "my-user-agent" https://example.comShow all of the request and response details
Use the --verbose option to make curl output all the request and response details:
$ curl --verbose -I https://example.com/--verbose is probably the most useful option when it comes to debugging, but sometimes even that is not enough.
In that case, use --trace and --trace-ascii to show everything curl sends and receives.
$ curl --trace-ascii debugdump.txt http://www.example.com/
See the Timing
Use the --trace-time option to prepend the time to each trace output line This is useful when you need to find out the amount of time taken at each point in the transfer:
$ curl --trace-ascii d.txt --trace-time http://example.com/
Some tips on using curl with HTTPS
HTTPS, HTTP over SSL, gives you the ability to secure the HTTP transfers. SSL encrypts all the data that is sent and received over the network.
SSL (or TLS as the latest version of the standard is called) offers many advanced features to allow all of the encryptions and key infrastructure mechanisms that HTTPS requires.
Curl supports encrypted fetches when built to use a TLS library and it can be built to use one out of a fairly large set of libraries. Use curl -V to show which library your particular installation of curl was built to use (if any!).
To get a page from a HTTPS server, simply run curl as follows:
$ curl https://secure.example.comcurl and HTTPS Certificates
Certificates are used to validate your identity, in addition to normal passwords.
Curl supports client-side certificates. All certificates are locked with a pass phrase, which you need to enter before the certificate can be used by curl. The pass phrase can be specified on the command line or if not, entered interactively when curl queries for it.
To use a certificate with curl on a HTTPS server:
$ curl --cert mycert.pem https://secure.example.comcurl also tries to check the server’s identity by verifying the server’s certificate against a locally stored CA cert bundle. Failing this verification will cause curl to deny the connection.
You could use your own CA cert store and then tell curl to use that to verify the server’s certificate:
$ curl --cacert ca-bundle.pem https://example.com/
