curl is entirely free and open source software, it is a complete and powerful tool to transfer data from/to a server.
Daniel Stenberg is the founder and lead developer of cURL and libcurl since 1996.
curl is used daily by virtually every Internet-using human on the globe, it is used everywhere !
cURL is an Open Source project consisting of voluntary members from all over the world.
The cURL project is completely independent and free.
It is a client-side program (the ‘c’), a URL (Uniform Resource Locator) client, and shows the data (by default).
So ‘c’ for Client and URL: cURL
Everything curl is a detailed and free book that explains basically everything there is to know about curl, libcurl and the associated project.
cURL is a project and its primary purpose and focus is to make two products:
– curl, the command-line tool
– libcurl the transfer library with a C API
Both the tool and the library do Internet transfers for resources specified as URLs using Internet protocols.
Everything and anything that is related to Internet protocol transfers can be considered curl’s business.
The protocol describes exactly how to ask the server for data, or to tell the server that there is data coming.
Protocols are typically defined by the IETF (Internet Engineering Task Force ),
which hosts RFC documents that describe exactly how each protocol works: how clients and servers are supposed to act and what to send and so on.
curl and libcurl are distributed under an Open Source license known as a MIT license derivative.
A key thing to remember is, that libcurl is the library and that this library is the biggest component of the curl command-line tool.
Where’s the code ?
The curl git tree can be browsed with a web browser at https://github.com/curl/curl
To check out the curl source code from git, you can clone it like this:
$ git clone https://github.com/curl/curl.git
curl started out as a command-line tool and it has been invoked from shell prompts and from within scripts by an uncountable number of users over the years.
curl has established itself as one of those trusty tools that is there for you to help you get your work done.
Here you can find why curl is your first choice.
curl vs. wget
https://daniel.haxx.se/docs/curl-vs-wget.html
wget has (recursive) downloading powers that curl does not feature and it also handle download retries over unreliable connections possibly slightly more effective.
For just about everything else, curl is probably the more suitable tool.
curl operates on URLs. URI (Uniform Resource Identifier) is actually the correct name for them.
The syntax is defined in RFC 3986 (2005): https://datatracker.ietf.org/doc/html/rfc3986
Install curl (Debian)
# apt install curl
curl options basics
-V, --version
Displays information about curl and the libcurl version it uses.
The output from that command line is typically four lines, out of which some will be rather long and might wrap in your terminal window
Line 1: curl
The first line includes the full version of curl, libcurl and other 3rd party libraries linked with the executable.
The first line starts with ‘curl’ and first shows the main version number of the tool.
Then follows the “platform” the tool was built for within parentheses and the libcurl version.
Those three fields are common for all curl builds.
If the curl version number has -DEV appended to it, it means the version is built straight from a in-development source code and it is not an officially released and “blessed” version.
The rest of this line contains names of third party components this build of curl uses, often with their individual version number next to it with a slash separator.
Line 2: Release-Date
This line shows the date this curl version was released by the curl project,
and it can also show a secondary “Patch date” if it has been updated somehow after it was originally released.
Line 3: Protocols
The third line (starts with “Protocols:”) is a list of all transfer protocols (URL schemes really) in alphabetical order that this curl build supports.
All names are shown in lowercase letters.
Line 4: Features
The fourth line (starts with “Features:”) is the list of features this build of curl supports.
If the name is present in the list, that feature is enabled. If the name is not present, that feature is not enabled.
-v, --verbose
Makes curl verbose during the operation.
Useful for debugging and seeing what’s going on “under the hood”.
When verbose mode is enabled, curl gets more talkative and will explain and show a lot more of its doings.
It will add informational tests and prefix them with ‘*’.
A line starting with ‘>’ means “header data” sent by curl,
A line starting with ‘<‘ means “header data” received by curl that is hidden in normal cases,
A line starting with ‘*’ means additional info provided by curl.
If you only want HTTP headers in the output, -i, --include
might be the option you’re looking for.
If you think this option still doesn’t give you enough details, consider using --trace
or --trace-ascii
instead.
See also -i, --include
. This option overrides --trace
and --trace-ascii
.
-s, --silent
Silent or quiet mode.
Don’t show progress meter or error messages when errors occur. Makes Curl mute.
It will still output the downloaded data you ask for, potentially even to the terminal/stdout unless you redirect it.
Use -S, --show-error
in addition to this option to only disable progress meter but still show error messages.
-S, --show-error
When used with -s, --silent
, it makes curl show an error message if it fails.
-I, --head
(HTTP, FTP, FILE) Fetch the headers only.
HTTP-servers feature the command HEAD which this uses to get nothing but the header of a document.
When used on an FTP or FILE file, curl displays the file size and last modification time only.
--ssl
Try to use SSL/TLS for the connection.
Reverts to a non-secure connection if the server doesn’t support SSL/TLS.--ssl-reqd
Require SSL/TLS for the connection. Terminates the connection if the server doesn’t support SSL/TLS.-L, --location
(HTTP 3NN Redirection)
(HTTP) If the server reports that the requested page has moved to a different location (indicated with a Location: header and a 3NN response code), this option will make curl redo the request automatically on the new place.
If used together with -i, –include or -I, –head, headers from all requested pages will be shown.--stderr
Redirect all writes to stderr to the specified file instead.
If the file name is a plain ‘-‘, it is instead written to stdout.
If this option is used several times, the last one will be used.
OUPUT
If not told otherwise, curl writes the received data to stdout.
It can be instructed to instead save that data into a local file, using the -o, --output
OR -O, --remote-name
options.
If curl is given multiple URLs to transfer on the command line, it similarly needs multiple options for where to save them.
curl does not parse or otherwise “understand” the content it gets or writes as output.
It does no encoding or decoding, unless explicitly asked so with dedicated command line options.-o, --output <path>
Write output to <path> instead of stdout.-O, --remote-name
Write output to a local file named like the remote file you get.
(Only the file part of the remote file is used, the path is cut off)
The file will be saved in the current working directory.
If you want the file saved in a different directory, make sure you change the current working directory before invoking curl with this option.
The remote file name to use for saving is extracted from the given URL, nothing else, and if it already exists it will be overwritten.
There is no URL decoding done on the file name. If it has %20 or other URL encoded parts of the name, they will end up as-is as file name.
You may use this option as many times as the number of URLs you have.-C, --continue-at
Continue/Resume a previous file transfer at the given offset.
The given offset is the exact number of bytes that will be skipped, counting from the beginning of the source file before it is transferred to the destination.
Use '-C -'
to tell curl to automatically find out where/how to resume the transfer.
It then uses the given output/input files to figure that out.
If this option is used several times, the last one will be used.
Download a file
$ curl URL -o /path/to/dst_filename
Download a file to the current directory
$ curl -O URL
Resume an interrupted download
$ curl -O -C - URL
PROGRESS METER
curl normally displays a progress meter during operations, indicating the amount of transferred data, transfer speeds and estimated time left, etc.
The progress meter displays number of bytes and the speeds are in bytes per second.
The suffixes (K, M, G, T, P) are 1024 based. For example 1K is 1024 bytes. 1M is 1048576 bytes (1024^2).
curl displays this data to the terminal by default, so if you invoke curl to do an operation and it is about to write data to the terminal, it disables the progress meter as otherwise it would mess up the output mixing progress meter and response data.
If you want a progress meter for HTTP POST or PUT requests, you need to redirect the response output to a file, using shell redirect (>), -o, --output
or similar.
It is not the same case for FTP upload as that operation does not spit out any response data to the terminal.
If you prefer a progress “bar” instead of the regular meter, -#, --progress-bar
is your friend.
You can also disable the progress meter completely with the -s, --silent
option.
-#, --progress-bar
Make curl display transfer progress as a simple progress bar instead of the standard, more informational, meter.
This progress bar draws a single line of ‘#’ characters across the screen and shows a percentage if the transfer size is known.
For transfers without a known size, there will be space ship (-=o=-) that moves back and forth but only while data is being transferred, with a set of flying hash sign symbols on top.
--no-progress-meter
Option to switch off the progress meter output without muting or otherwise affecting warning and informational messages like -s, --silent
does.
Note that this is the negated option name documented.
You can thus use --progress-meter
to enable the progress meter again.
Added in version 7.67.0.
Connection Test: Get Server Information
$ curl -I -v --silent --ssl [protocol://]ip_or_hostname | grep '^[><*]'
If you specify URL without protocol:// prefix, curl will attempt to guess what protocol you might want.
It will then default to HTTP but try other protocols based on often-used host name prefixes.
For example, for host names starting with “ftp.” curl will assume you want to speak FTP.
curl will do its best to use what you pass to it as a URL.
https://everything.curl.dev/usingcurl/tls/enable
Using --ssl
means that curl will attempt to upgrade the connection to TLS but if that fails, it will still continue with the transfer using the plain-text version of the protocol.
To make the --ssl
option require TLS to continue, there is instead the --ssl-reqd
option which will make the transfer fail if curl cannot successfully negotiate TLS.