Programming Field

Curl - DOS/Command Prompt Reference

‘Abbreviation of client URL’ (from Everything curl)

It is a program that facilitates data exchange using URLs through the command line. ‘cURL’ is an open-source project with broad platform support, not limited to Windows. The Curl program is available on various platforms, and its usage is nearly consistent across different operating systems.

In Windows, Curl is included by default starting from Windows 10 April Update (Build 1803; 10.0.17134.*; Insider builds 10.0.17063.*). However, due to its open-source nature, updates (version upgrades) may be available earlier than official Windows updates. If you want to use the latest version, you need to download it from the official website. Additionally, if you wish to use Curl on earlier versions of Windows, such as versions before Windows 10 or on Windows 8.1, you'll need to obtain it separately in a similar manner.

* When downloading and using Curl from official sources or elsewhere, it's essential to be mindful of the program's search path, including setting the PATH. This ensures that the system can locate and execute the cURL program from any directory in the command prompt or terminal.

* The versions included in Windows 10/11 are as follows: As of November 2023, the version installed on the latest Windows is 8.4.0.

Versions of curl.exe included in Windows 10/11
curl versionWindows 10Windows 11DateRemarks
curl 7.55.110.0.17134.* (1803)(10.0.22000.194)Initial bundled version
curl 7.79.110.0.18363.2037 (1909)
10.0.19042.1466 (20H2)
10.0.19043.1466 (21H1)
10.0.19044.1466 (21H2)		10.0.22000.434 (21H2)2022-01-11
curl 7.83.110.0.19042.1826 (20H2)
10.0.19043.1826 (21H1)
10.0.19044.1826 (21H2)		10.0.22000.795 (21H2)2022-07-12Windows 11 22H2 comes with this version from the beginning.
curl 8.0.110.0.19042.2846 (20H2)
10.0.19044.2846 (21H2)
10.0.19045.2846 (22H2)		10.0.22000.1817 (21H2)
10.0.22621.1555 (22H2)		2023-04-11Windows 11 23H2 comes with this version from the beginning.
curl 8.4.010.0.19044.3693 (21H2)
10.0.19045.3693 (22H2)		10.0.22000.2600 (21H2)
10.0.22621.2506 (22H2)
10.0.22631.2506 (23H2)		2023-11-14

Options may vary depending on the version or platform, so in such cases, please refer to the official curl documentation or check the content of ‘curl --help’ for details.

[PowerShell up to 5.x] Until PowerShell 5.x, by default, ‘curl’ is registered as an alias for ‘Invoke-WebRequest’, and using ‘curl’ will result in behavior different from ‘curl.exe’. If you want to use the Curl command mentioned on this page, you need to input ‘curl.exe’ without omitting the ‘.exe’.

Usage

curl help

Curl is used as following syntax.

curl[.exe] [<options>] [<url>]

※ [PowerShell up to 5.x] As mentioned earlier, when using Curl in the PowerShell environment, (by default) you cannot omit the ‘.exe’ extension.

In [options], you can specify optional options in the form of ‘--xxx’ or ‘-x’ (zero, one, or multiple, combined as needed). For example, it would look like the following:

curl -L --user-agent FooBar https://www.example.com/

Additionally, the options are specified in a format commonly used in Linux systems, starting with ‘-’ or ‘--’, and are case-sensitive. Moreover, options starting with ‘/’ as commonly seen in DOS/Windows commands are not applicable. Therefore, ‘/?’ would be treated as an ‘invalid URL’, and to display usage information, you should use ‘--help’ (or ‘-h’).

With a few exceptions, options apply to the preceding URL specification. They are interpreted in order, so in many cases, if the same option is encountered again, it will overwrite the previous one (except for some options like --url).

Options that toggle between ON and OFF (boolean values) can be negated by adding ‘no-’ before the option name, indicating ‘do not specify’ or ‘disable’. For example, if ‘--location’ is specified, adding ‘--no-location’ afterward will negate the effect of ‘--location’. This is useful not only for command-line usage but also when canceling options specified in a configuration file.

Furthermore, for single-character options in the ‘-x’ format, you can concatenate multiple single-character options, such as ‘-xyz’ (however, options requiring additional parameters can only be combined at the end). Additionally, for single-character options that require additional parameters, like ‘-o <file>’, you can omit the space between the option name and the additional parameter, for example, ‘-oNUL’.

For detailed options, please see curl official site. In the list of options, please consider that Curl is using ‘Schannel’.

Details

General overview

The Curl command-line program is a tool for transferring data (such as downloading or uploading) by specifying a URL. As a simple usage, you can just provide the URL as a parameter, and it will output the downloaded data to the standard output.

> curl https://www.example.com/
<!doctype html>
<html>
<head>
...

If you want to save the retrieved content to a file, you can use the ‘-o’ option.

Furthermore, since Curl supports not only downloads but also uploads (data transmission), you can, for example, execute a POST request from the command line in HTTP communication.

You can confirm which protocols Curl supports, including HTTP and HTTPS, by using the ‘curl -V’ command to output version information.

(The following is the sample execution in Windows 10.0.17763.*:)

> curl -V
curl 7.55.1 (Windows) libcurl/7.55.1 WinSSL
Release-Date: [unreleased]
Protocols: dict file ftp ftps http https imap imaps pop3 pop3s smtp smtps telnet tftp
Features: AsynchDNS IPv6 Largefile SSPI Kerberos SPNEGO NTLM SSL

* cURL itself is a project that includes the library ‘libcurl’, and the command-line ‘curl’ is built on top of the ‘libcurl’ library. To distinguish between the command-line tool and the library, the library is explicitly referred to as ‘libcurl’, and when simply saying ‘curl’, it often refers to the command-line program. In this page, ‘Curl’ is used to refer to the command-line program.

Using from batch files or etc.

Curl itself is a program that can be used straightforwardly, but due to its convenience, it is often utilized from various script programs such as batch files or PowerShell. This allows for tasks such as interpreting data obtained with Curl, branching or executing different processes based on that data, and automating the transmission of data to a server by interpreting data stored in files, among other possibilities.

* Implementing communication processes on the program side can be complex, even when libraries are provided. Therefore, not only in scripts but also in programs that aim for simplicity and are written in languages like C/C++ or Node.js, Curl is often utilized for its ease of use in handling various network protocols.

PowerShell sample:

# Keep encoding of Console
$enc = [Console]::OutputEncoding
# Change to UTF-8 according to the assumed character encoding of the destination
[Console]::OutputEncoding = [Text.Encoding]::UTF8
# Retrieve data from a remote source and store it as text in a variable
$content = curl.exe -s 'https://www.pg-fl.jp/release.xml'
# Restore encoding of Console
[Console]::OutputEncoding = $enc
# Parse the retrieved text as XML to obtain an XmlDocument
$doc = [xml] $content
# (Now you can use XML operation for $doc)

* The above is just an example, and in PowerShell, using Invoke-WebRequest (the default alias for ‘curl’) is often more suitable for convenient communication processing.

Date syntax on Curl

(Reference: libcurl - curl_getdate() man page 3)

When specifying dates and times using options such as ‘--time-cond’, you need to use the following format either individually or separated by spaces (or commas). However, specifying multiple dates or times is not allowed and would be considered invalid. Date specification is mandatory, but time specification is optional. If time is not provided, it is treated as ‘00:00:00’ (midnight; UTC/GMT if no timezone is specified, or in the specified timezone). If no timezone is specified, it is treated as UTC/GMT.

Date specification (calendar date items)
Specifies the ‘month’ using a 3-letter English abbreviation (Jan, Nov, etc.), the ‘day’ with a 1 or 2-digit number, and the ‘year’ with a 1 to 4-digit number. You must connect these using space, comma, or hyphen. Whether a number is a ‘year’ is determined by it being 0, 32 or higher, or having 3 or more digits. If it's not distinguishable, the earlier number is considered the ‘day’, and the later number is considered the ‘year’. Note that in this format, you cannot specify the ‘month’ using a numeric value.
Example: Jul-7-10 ... July 7, 2010 / 10-Jul-7 ... July 10, 2007 / 2020 Dec 10 ... December 10, 2020
Time specification (time of the day items)
Uses the so-called ‘HH:MM:SS’ format, where you specify two digits for ‘hour’ (00 to 23), two digits for ‘minute’, and two digits for ‘second’, all connected with colons.
Example: 18:34:56 ... 6:34:56 PM
Timezone specification (time zone items)
Specifies the timezone for time calculations using a 3-letter abbreviation (UTC, PDT, JST, etc.) or a relative time notation (-0700 or +0900, without colons).
Example: 12:00:00 JST ... 12:00:00 in Japan Standard Time (3:00:00 in UTC) / 03:00:00-0700 ... 10:00:00 in UTC
Day of the week specification (day of the week items)
You can specify a 3-letter English abbreviation (Sun, Thu, etc.), but it is not actually used, as it is automatically calculated from the date specification.
Number specification (pure numbers)
If there is an 8-digit number, it is treated as the so-called ‘YYYYMMDD’ format, where the number is composed of ‘year’ (4 digits) + ‘month’ (2 digits) + ‘day’ (2 digits). If there are out-of-range values mixed in, it is considered an invalid value.
Example: 20120304 … March 4, 2012

Combination example: ‘12:30:00 JST, 05-May 2020’ ... represents ‘May 5, 2020 3:30:00 in UTC(GMT)’ (In this case the comma is optional.)

About config file

Curl supports reading options from a configuration file.

Curl sequentially checks the following settings (including environment variables) and uses the first one with a set value to read the ‘default configuration file’.

  1. The path set in the environment variable CURL_HOME
  2. [curl 7.73.0 or later] The path set in the environment variable XDG_CONFIG_HOME
  3. The path set in the environment variable HOME
  4. [Non-Windows] The path of pw_dir field returned by getpwuid function
  5. [Windows] The path set in the environment variable APPDATA
  6. [Windows] The ‘Application Data’ directory in the path set in the environment variable USERPROFILE

Once it determines the available directory using this process, it reads the ‘.curlrc’ file (‘_curlrc’ file for Windows) from that directory as the ‘default configuration file’. If the file is not found at this point, for Windows, it uses the directory where ‘curl.exe’ is located, and for Unix-based systems, it uses the home directory for another attempt to read the configuration file.

Additionally, you can explicitly specify the configuration file using the ‘--config’ option.

The configuration file should be written as followings.

  • Each option should be written on a separate line using the following format:
    1. Write each option without the ‘--’ prefix on separate lines
    2. Write one or more characters of space, ‘=’, or ‘:’ as separators on the same line
    3. Subsequently, write the parameter values to be specified for the options
      • Parameter values can be enclosed in double quotation marks (" ").
      • However, if the value contains a space or begins with ‘=’, or ‘:’, it must be enclosed in double quotation marks (" ").
      • Within the " " (quotation marks), the following escape sequences are available: ‘\\’, ‘\"’, ‘\t’, ‘\n’, ‘\r’, ‘\v’. (A single ‘\’ character without an escape sequence is ignored.)
  • When using single-character options, prefix them with "-" at the beginning
  • Lines beginning with ‘#’ (excluding space characters) are treated as comments and will be ignored
  • (Lines with no characters other than space characters will also be ignored)

For example, it would look like the following (quoting from the Curl documentation with additional explanations):

# --- The sample file ---
# Lines beginning with ‘#’ are the comments

# Using ‘--url’ option (same below)
url = "example.com"
output = "curlhere.html"
user-agent = "superagent/1.0"

# Retrieve another page
# (When you add the new ‘--url’ option, you can retrieve data from a different URL)
url = "example.com/docs/manpage.html"
# Single-character options should be prefixed with ‘-’
-O
referer = "http://nowhereatall.example.com/"
# --- End of sample file ---

Samples

Sample 1

curl -LO http://www.pg-fl.jp/music/Simple.sf2

Accesses ‘http://www.pg-fl.jp/music/Simple.sf2’ and downloads it as ‘Simple.sf2’ in the current directory. Due to the presence of ‘-L’, it will follow redirects, and in reality, it will download from ‘https://www.pg-fl.jp/music/Simple.sf2’.

Sample 2

curl ftp://ftp.example.com/foo/bar/ --ssl-reqd -Q"CWD /" -uhoge -Tbaz.dat

Accesses the FTP server ‘ftp.example.com’ and uploads ‘baz.dat’ to the ‘/foo/bar’ directory (using the --upload-file (-T) option). SSL/TLS connection is enforced with the --ssl-reqd option. Considering the possibility that the home directory after connection completion may not be the root, use the --quote (-Q) option to specify sending the ‘CWD /’ command initially. Note that since only the username is specified with the --user (-u) option, the user will be prompted for the password during execution.

Sample 3 (Batch file)

for /F "tokens=1,2 delims=: " %%A in ('curl -s https://www.example.com/_health') do (
    if "%%A"=="Service1" (
        if "%%B"=="OK" exit /b 0
        exit /b 1
    )
)
exit /b 2

[Extensions] Requests ‘https://www.example.com/_health’, and if the response contains ‘Service1: OK’, exits with code 0. If ‘Service1’ is present but not ‘OK’, exits with code 1. If ‘Service1’ is not present, exits with code 2. Since Curl outputs the response to standard output, you can perform text analysis using the For command. (Note: the ‘-s’ option is included to prevent mixing with non-response content.)

Sample 4

-- ‘checklog.curlrc’ file

url: "ftp://www.example.com/logs/access_log"
output: "access_log.dat"
url = "ftp://www.example.com/logs/error_log"
output = "error_log.dat"

-- command line

curl -K checklog.curlrc

Executes Curl using the configuration file ‘checklog.curlrc’. By pre-specifying URLs in the configuration file, you can omit specifying the URL each time on the command line. (It can be used in a similar way to the ‘job file’ in Robocopy.)

Note that in the above example, both ‘=’ and ‘:’ are used as separators for demonstration purposes. You can use either without any issues. (It is recommended to use a consistent and clear format.)