repo
reprioritized
resending
+resends
RETR
retransmit
retrigger
### Body
The body of the description. Only refer to options with their long form option
-version, like `--verbose`. The output generator will replace such with the
+version, like `--verbose`. The output generator replaces such option with the
correct markup that shows both short and long version.
-Text written within `*asterisks*` will get shown using italics. Text within
-two `**asterisks**` will get shown using bold.
+Text written within `*asterisks*` is shown using italics. Text within two
+`**asterisks**` is shown using bold.
-Text that is prefixed with a space will be treated like an "example" and will
-be output in monospace.
+Text that is prefixed with a space is treated like an "example" and gets
+output in monospace.
## Header and footer
-`page-header` is the file that will be output before the generated options
-output for the master man page.
+`page-header` is the file that is output before the generated options output
+for the master man page.
`page-footer` is appended after all the individual options.
Multi: append
---
This option enables the alt-svc parser in curl. If the file name points to an
-existing alt-svc cache file, that will be used. After a completed transfer,
-the cache will be saved to the file name again if it has been modified.
+existing alt-svc cache file, that gets used. After a completed transfer, the
+cache is saved to the file name again if it has been modified.
Specify a "" file name (zero length) to avoid loading/saving and make curl
just handle the cache in memory.
-If this option is used several times, curl will load contents from all the
-files but the last one will be used for saving.
+If this option is used several times, curl loads contents from all the
+files but the last one is used for saving.
Using --anyauth is not recommended if you do uploads from stdin, since it may
require data to be sent twice and then the client must be able to rewind. If
-the need should arise when uploading from stdin, the upload operation will
-fail.
+the need should arise when uploading from stdin, the upload operation fails.
Used together with --user.
Added: 4.8
Multi: boolean
---
-When used in an upload, this makes curl append to the target file instead of
-overwriting it. If the remote file does not exist, it will be created. Note
-that this flag is ignored by some SFTP servers (including OpenSSH).
+When used in an upload, this option makes curl append to the target file
+instead of overwriting it. If the remote file does not exist, it is
+created. Note that this flag is ignored by some SFTP servers (including
+OpenSSH).
Multi: boolean
---
Tells curl to use the CA store from the native operating system to verify the
-peer. By default, curl will otherwise use a CA store provided in a single file
-or directory, but when using this option it will interface the operating
-system's own vault.
+peer. By default, curl otherwise uses a CA store provided in a single file or
+directory, but when using this option it interfaces the operating system's
+own vault.
This option only works for curl on Windows when built to use OpenSSL. When
curl on Windows is built to use Schannel, this feature is implied and curl
then only uses the native CA store.
+
+curl built with wolfSSL also supports this option (added in 8.3.0).
set, and uses the given path as a path to a CA cert bundle. This option
overrides that variable.
-The windows version of curl will automatically look for a CA certs file named
+The windows version of curl automatically looks for a CA certs file named
'curl-ca-bundle.crt', either in the same directory as curl.exe, or in the
Current Working Directory, or in any folder along your PATH.
(iOS and macOS only) If curl is built against Secure Transport, then this
option is supported for backward compatibility with other SSL engines, but it
-should not be set. If the option is not set, then curl will use the
-certificates in the system and user Keychain to verify the peer, which is the
-preferred method of verifying the peer's certificate chain.
+should not be set. If the option is not set, then curl uses the certificates
+in the system and user Keychain to verify the peer, which is the preferred
+method of verifying the peer's certificate chain.
(Schannel only) This option is supported for Schannel in Windows 7 or later
(added in 7.60.0). This option is supported for backward compatibility with
OpenSSL-powered curl to make SSL-connections much more efficiently than using
--cacert if the --cacert file contains many CA certificates.
-If this option is set, the default capath value will be ignored.
+If this option is set, the default capath value is ignored.
Tells curl to use the specified client certificate file when getting a file
with HTTPS, FTPS or another SSL-based protocol. The certificate must be in
PKCS#12 format if using Secure Transport, or PEM format if using any other
-engine. If the optional password is not specified, it will be queried for on
+engine. If the optional password is not specified, it is queried for on
the terminal. Note that this option assumes a certificate file that is the
private key and the client certificate concatenated. See --cert and --key to
specify them independently.
If curl is built against OpenSSL library, and the engine pkcs11 is available,
then a PKCS#11 URI (RFC 7512) can be used to specify a certificate located in
-a PKCS#11 device. A string beginning with "pkcs11:" will be interpreted as a
-PKCS#11 URI. If a PKCS#11 URI is provided, then the --engine option will be set
-as "pkcs11" if none was provided and the --cert-type option will be set as
-"ENG" if none was provided.
+a PKCS#11 device. A string beginning with "pkcs11:" is interpreted as a
+PKCS#11 URI. If a PKCS#11 URI is provided, then the --engine option is set as
+"pkcs11" if none was provided and the --cert-type option is set as "ENG" if
+none was provided.
(iOS and macOS only) If curl is built against Secure Transport, then the
certificate string can either be the name of a certificate/private key in the
separately again at a later point they might appear to be saying that the
content is (still) compressed; while in fact it has already been decompressed.
-If this option is used and the server sends an unsupported encoding, curl will
-report an error. This is a request, not an order; the server may or may not
+If this option is used and the server sends an unsupported encoding, curl
+reports an error. This is a request, not an order; the server may or may not
deliver data compressed.
Multi: append
---
Specify a text file to read curl arguments from. The command line arguments
-found in the text file will be used as if they were provided on the command
+found in the text file are used as if they were provided on the command
line.
Options and their parameters must be specified on the same line in the file,
and \\v. A backslash preceding any other letter is ignored.
If the first non-blank column of a config line is a '#' character, that line
-will be treated as a comment.
+is treated as a comment.
Only write one option per physical line in the config file. A single line is
required to be no more than 10 megabytes (since 8.2.0).
---
Maximum time in seconds that you allow curl's connection to take. This only
limits the connection phase, so if curl connects within the given period it
-will continue - if not it will exit.
+continues - if not it exits.
This option accepts decimal values (added in 7.32.0). The decimal value needs
to be provided using a dot (.) as decimal separator - not the local version
Multi: single
---
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
+is the exact number of bytes that are skipped, counting from the beginning
of the source file before it is transferred to the destination. If used with
-uploads, the FTP server command SIZE will not be used by curl.
+uploads, the FTP server command SIZE is not used by curl.
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.
---
Specify to which file you want curl to write all cookies after a completed
operation. Curl writes all cookies from its in-memory cookie storage to the
-given file at the end of operations. If no cookies are known, no data will be
-written. The file will be written using the Netscape cookie file format. If
-you set the file name to a single dash, "-", the cookies will be written to
-stdout.
+given file at the end of operations. If no cookies are known, no data is
+written. The file is created using the Netscape cookie file format. If you set
+the file name to a single dash, "-", the cookies are written to stdout.
-The file specified with --cookie-jar is only used for output. No cookies will
-be read from the file. To read cookies, use the --cookie option. Both options
+The file specified with --cookie-jar is only used for output. No cookies are
+read from the file. To read cookies, use the --cookie option. Both options
can specify the same file.
-This command line option will activate the cookie engine that makes curl
-record and use cookies. The --cookie option also activates it.
+This command line option activates the cookie engine that makes curl record
+and use cookies. The --cookie option also activates it.
If the cookie jar cannot be created or written to, the whole curl operation
-will not fail or even report an error clearly. Using --verbose will get a
-warning displayed, but that is the only visible feedback you get about this
-possibly lethal situation.
+does not fail or even report an error clearly. Using --verbose gets a warning
+displayed, but that is the only visible feedback you get about this possibly
+lethal situation.
should be in the format "NAME1=VALUE1; NAME2=VALUE2". This makes curl use the
cookie header with this content explicitly in all outgoing request(s). If
multiple requests are done due to authentication, followed redirects or
-similar, they will all get this cookie passed on.
+similar, they all get this cookie passed on.
If no '=' symbol is used in the argument, it is instead treated as a filename
to read previously stored cookie from. This option also activates the cookie
-engine which will make curl record incoming cookies, which may be handy if
-you are using this in combination with the --location option or do multiple URL
+engine which makes curl record incoming cookies, which may be handy if you are
+using this in combination with the --location option or do multiple URL
transfers on the same invoke. If the file name is exactly a minus ("-"), curl
-will instead read the contents from stdin.
+instead reads the contents from stdin.
The file format of the file to read cookies from should be plain HTTP headers
(Set-Cookie style) or the Netscape/Mozilla cookie file format.
-The file specified with --cookie is only used as input. No cookies will be
-written to the file. To store cookies, use the --cookie-jar option.
+The file specified with --cookie is only used as input. No cookies are written
+to the file. To store cookies, use the --cookie-jar option.
If you use the Set-Cookie file format and do not specify a domain then the
-cookie is not sent since the domain will never match. To address this, set a
-domain in Set-Cookie line (doing that will include subdomains) or preferably:
-use the Netscape format.
+cookie is not sent since the domain never matches. To address this, set a
+domain in Set-Cookie line (doing that includes subdomains) or preferably: use
+the Netscape format.
Users often want to both read cookies from a file and write updated cookies
back to a file, so using both --cookie and --cookie-jar in the same command
See-also: ftp-create-dirs output-dir
Multi: boolean
---
-When used in conjunction with the --output option, curl will create the
-necessary local directory hierarchy as needed. This option creates the
-directories mentioned with the --output option, nothing else. If the --output
-file name uses no directory, or if the directories it mentions already exist,
-no directories will be created.
+When used in conjunction with the --output option, curl creates the necessary
+local directory hierarchy as needed. This option creates the directories
+mentioned with the --output option, nothing else. If the --output file name
+uses no directory, or if the directories it mentions already exist, no
+directories are created.
Created directories are made with mode 0750 on unix style file systems.
the (EC) curve requested by the client, avoiding nontransparent client/server
negotiations.
-If this option is set, the default curves list built into OpenSSL will be
-ignored.
+If this option is set, the default curves list built into OpenSSL are ignored.
arbitrary binary data by the server then set the content-type to octet-stream:
-H "Content-Type: application/octet-stream".
-If this option is used several times, the ones following the first will append
+If this option is used several times, the ones following the first append
data as described in --data.
curl using one of the following syntaxes:
.RS
.IP "content"
-This will make curl URL-encode the content and pass that on. Just be careful
-so that the content does not contain any = or @ symbols, as that will then make
+This makes curl URL-encode the content and pass that on. Just be careful
+so that the content does not contain any = or @ symbols, as that makes
the syntax match one of the other cases below!
.IP "=content"
-This will make curl URL-encode the content and pass that on. The preceding =
+This makes curl URL-encode the content and pass that on. The preceding =
symbol is not included in the data.
.IP "name=content"
-This will make curl URL-encode the content part and pass that on. Note that
+This makes curl URL-encode the content part and pass that on. Note that
the name part is expected to be URL-encoded already.
.IP "@filename"
-This will make curl load data from the given file (including any newlines),
+This makes curl load data from the given file (including any newlines),
URL-encode that data and pass it on in the POST.
.IP "name@filename"
-This will make curl load data from the given file (including any newlines),
+This makes curl load data from the given file (including any newlines),
URL-encode that data and pass it on in the POST. The name part gets an equal
sign appended, resulting in *name=urlencoded-file-content*. Note that the
name is expected to be URL-encoded already.
---
Sends the specified data in a POST request to the HTTP server, in the same way
that a browser does when a user has filled in an HTML form and presses the
-submit button. This will cause curl to pass the data to the server using the
+submit button. This makes curl pass the data to the server using the
content-type application/x-www-form-urlencoded. Compare to --form.
--data-raw is almost the same but does not have a special interpretation of
--data-urlencode.
If any of these options is used more than once on the same command line, the
-data pieces specified will be merged with a separating &-symbol. Thus, using
+data pieces specified are merged with a separating &-symbol. Thus, using
'-d name=daniel -d skill=lousy' would generate a post chunk that looks like
'name=daniel&skill=lousy'.
read the data from, or - if you want curl to read the data from stdin. Posting
data from a file named 'foobar' would thus be done with --data @foobar. When
--data is told to read from a file like that, carriage returns and newlines
-will be stripped out. If you do not want the @ character to have a special
+are stripped out. If you do not want the @ character to have a special
interpretation use --data-raw instead.
The data for this option is passed on to the server exactly as provided on the
-command line. curl will not convert it, change it or improve it. It is up to
-the user to provide the data in the correct form.
+command line. curl does not convert, change or improve it. It is up to the
+user to provide the data in the correct form.
Multi: boolean
---
Tell curl to disable the use of the EPRT and LPRT commands when doing active
-FTP transfers. Curl will normally always first attempt to use EPRT, then LPRT
-before using PORT, but with this option, it will use PORT right away. EPRT and
-LPRT are extensions to the original FTP protocol, and may not work on all
-servers, but they enable more functionality in a better way than the
-traditional PORT command.
+FTP transfers. Curl normally first attempts to use EPRT before using PORT, but
+with this option, it uses PORT right away. EPRT is an extension to the
+original FTP protocol, and does not work on all servers, but enables more
+functionality in a better way than the traditional PORT command.
--eprt can be used to explicitly enable EPRT again and --no-eprt is an alias
for --disable-eprt.
-If the server is accessed using IPv6, this option will have no effect as EPRT
-is necessary then.
+If the server is accessed using IPv6, this option has no effect as EPRT is
+necessary then.
Disabling EPRT only changes the active behavior. If you want to switch to
passive mode you need to not use --ftp-port or force it with --ftp-pasv.
Multi: boolean
---
Tell curl to disable the use of the EPSV command when doing passive FTP
-transfers. Curl will normally always first attempt to use EPSV before
-PASV, but with this option, it will not try using EPSV.
+transfers. Curl normally first attempts to use EPSV before PASV, but with this
+option, it does not try EPSV.
--epsv can be used to explicitly enable EPSV again and --no-epsv is an alias
for --disable-epsv.
-If the server is an IPv6 host, this option will have no effect as EPSV is
-necessary then.
+If the server is an IPv6 host, this option has no effect as EPSV is necessary
+then.
Disabling EPSV only changes the passive behavior. If you want to switch to
active mode you need to use --ftp-port.
Multi: boolean
---
If used as the **first** parameter on the command line, the *curlrc* config
-file will not be read and used. See the --config for details on the default
-config file search path.
+file is not read or used. See the --config for details on the default config
+file search path.
Prior to 7.50.0 curl supported the short option name *q* but not the long
option name *disable*.
Specifies which DNS-over-HTTPS (DoH) server to use to resolve hostnames,
instead of using the default name resolver mechanism. The URL must be HTTPS.
-Some SSL options that you set for your transfer will apply to DoH since the
+Some SSL options that you set for your transfer also applies to DoH since the
name lookups take place over SSL. However, the certificate verification
-settings are not inherited and can be controlled separately via
---doh-insecure and --doh-cert-status.
+settings are not inherited but are controlled separately via --doh-insecure
+and --doh-cert-status.
This option is unset if an empty string "" is used as the URL.
(Added in 7.85.0)
Multi: single
---
Write the received protocol headers to the specified file. If no headers are
-received, the use of this option will create an empty file.
+received, the use of this option creates an empty file.
When used in FTP, the FTP server response lines are considered being "headers"
and thus are saved there.
Having multiple transfers in one set of operations (i.e. the URLs in one
---next clause), will append them to the same file, separated by a blank line.
+--next clause), appends them to the same file, separated by a blank line.
---
Maximum time in seconds that you allow curl to wait for a 100-continue
response when curl emits an Expects: 100-continue header in its request. By
-default curl will wait one second. This option accepts decimal values! When
-curl stops waiting, it will continue as if the response has been received.
+default curl waits one second. This option accepts decimal values! When
+curl stops waiting, it continues as if the response has been received.
The decimal value needs to provided using a dot (.) as decimal separator - not
the local version even if it might be using another separator.
---
Fail and exit on the first detected transfer error.
-When curl is used to do multiple transfers on the command line, it will
-attempt to operate on each given URL, one by one. By default, it will ignore
-errors if there are more URLs given and the last URL's success will determine
-the error code curl returns. So early failures will be "hidden" by subsequent
-successful transfers.
+When curl is used to do multiple transfers on the command line, it attempts to
+operate on each given URL, one by one. By default, it ignores errors if there
+are more URLs given and the last URL's success determines the error code curl
+returns. So early failures are "hidden" by subsequent successful transfers.
-Using this option, curl will instead return an error on the first transfer
-that fails, independent of the amount of URLs that are given on the command
+Using this option, curl instead returns an error on the first transfer that
+fails, independent of the amount of URLs that are given on the command
line. This way, no transfer failures go undetected by scripts and similar.
This option does not imply --fail, which causes transfers to fail due to the
Help: Fail on HTTP errors but save the body
Category: http output
Added: 7.76.0
-See-also: fail
+See-also: fail fail-early
Mutexed: fail
Example: --fail-with-body $URL
Multi: boolean
Return an error on server errors where the HTTP response code is 400 or
greater). In normal cases when an HTTP server fails to deliver a document, it
returns an HTML document stating so (which often also describes why and
-more). This flag will still allow curl to output and save that content but
-also to return error 22.
+more). This flag allows curl to output and save that content but also to
+return error 22.
This is an alternative option to --fail which makes curl fail for the same
circumstances but without saving the content.
Short: f
Protocols: HTTP
Help: Fail fast with no output on HTTP errors
-See-also: fail-with-body
+See-also: fail-with-body fail-early
Category: important http
Example: --fail $URL
Mutexed: fail-with-body
Fail fast with no output at all on server errors. This is useful to enable
scripts and users to better deal with failed attempts. In normal cases when an
HTTP server fails to deliver a document, it returns an HTML document stating
-so (which often also describes why and more). This flag will prevent curl from
+so (which often also describes why and more). This flag prevents curl from
outputting that and return error 22.
This method is not fail-safe and there are occasions where non-successful
-response codes will slip through, especially when authentication is involved
+response codes slip through, especially when authentication is involved
(response codes 401 and 407).
Multi: boolean
---
Tells curl to use false start during the TLS handshake. False start is a mode
-where a TLS client will start sending application data before verifying the
+where a TLS client starts sending application data before verifying the
server's Finished message, thus saving a round trip when performing a full
handshake.
Tell curl to read content from stdin instead of a file by using - as
filename. This goes for both @ and < constructs. When stdin is used, the
contents is buffered in memory first by curl to determine its size and allow a
-possible resend. Defining a part's data from a named non-regular file (such
-as a named pipe or similar) is unfortunately not subject to buffering and will
-be effectively read at transmission time; since the full size is unknown
-before the transfer starts, such data is sent as chunks by HTTP and rejected
-by IMAP.
+possible resend. Defining a part's data from a named non-regular file (such as
+a named pipe or similar) is not subject to buffering and is instead read at
+transmission time; since the full size is unknown before the transfer starts,
+such data is sent as chunks by HTTP and rejected by IMAP.
Example: send an image to an HTTP server, where 'profile' is the name of the
-form-field to which the file **portrait.jpg** will be the input:
+form-field to which the file **portrait.jpg** is the input:
curl -F profile=@portrait.jpg https://example.com/upload.cgi
---
If authenticating with the USER and PASS commands fails, send this command.
When connecting to Tumbleweed's Secure Transport server over FTPS using a
-client certificate, using "SITE AUTH" will tell the server to retrieve the
+client certificate, using "SITE AUTH" tells the server to retrieve the
username from the certificate.
---
When an FTP or SFTP URL/operation uses a path that does not currently exist on
the server, the standard behavior of curl is to fail. Using this option, curl
-will instead attempt to create missing directories.
+instead attempts to create missing directories.
hierarchies this means many commands. This is how RFC 1738 says it should
be done. This is the default but the slowest behavior.
.IP nocwd
-curl does no CWD at all. curl will do SIZE, RETR, STOR etc and give a full
+curl does no CWD at all. curl does SIZE, RETR, STOR etc and give a full
path to the server for all these commands. This is the fastest behavior.
.IP singlecwd
curl does one CWD with the full target directory and then operates on the file
Reversing an enforced passive really is not doable but you must then instead
enforce the correct --ftp-port again.
-Passive mode means that curl will try the EPSV command first and then PASV,
+Passive mode means that curl tries the EPSV command first and then PASV,
unless --disable-epsv is used.
Multi: boolean
---
Tell curl to not use the IP address the server suggests in its response to
-curl's PASV command when curl connects the data connection. Instead curl will
-reuse the same IP address it already uses for the control connection.
+curl's PASV command when curl connects the data connection. Instead curl
+reuses the same IP address it already uses for the control connection.
This option is enabled by default (added in 7.74.0).
Example: --ftp-ssl-ccc-mode active --ftp-ssl-ccc ftps://example.com/
Multi: boolean
---
-Sets the CCC mode. The passive mode will not initiate the shutdown, but
-instead wait for the server to do it, and will not reply to the shutdown from
+Sets the CCC mode. The passive mode does not initiate the shutdown, but
+instead waits for the server to do it, and does not reply to the shutdown from
the server. The active mode initiates the shutdown and waits for a reply from
the server.
Multi: boolean
---
Use CCC (Clear Command Channel) Shuts down the SSL/TLS layer after
-authenticating. The rest of the control channel communication will be
+authenticating. The rest of the control channel communication is be
unencrypted. This allows NAT routers to follow the FTP transaction. The
default mode is passive.
my @extra;
if($multi eq "single") {
push @extra, "\nIf --$long is provided several times, the last set ".
- "value will be used.\n";
+ "value is used.\n";
}
elsif($multi eq "append") {
push @extra, "\n--$long can be used several times in a command line\n";
See-also: data request
Multi: boolean
---
-When used, this option will make all data specified with --data, --data-binary
+When used, this option makes all data specified with --data, --data-binary
or --data-urlencode to be used in an HTTP GET request instead of the POST
-request that otherwise would be used. The data will be appended to the URL
+request that otherwise would be used. The data is appended to the URL
with a '?' separator.
-If used in combination with --head, the POST data will instead be appended to
-the URL with a HEAD request.
+If used in combination with --head, the POST data is instead appended to the
+URL with a HEAD request.
acceptance of one double colon sequence to replace the largest acceptable range
of consecutive zeroes. The total number of decoded bits must exactly be 128.
-Otherwise, any string can be accepted for the client IP and will be sent.
+Otherwise, any string can be accepted for the client IP and get sent.
It replaces --haproxy-protocol if used, it is not necessary to specify both flags.
You may specify any number of extra headers. Note that if you should add a
custom header that has the same name as one of the internal ones curl would
-use, your externally set header will be used instead of the internal one.
-This allows you to make even trickier stuff than curl would normally do. You
-should not replace internally set headers without knowing perfectly well what
-you are doing. Remove an internal header by giving a replacement without
-content on the right side of the colon, as in: -H "Host:". If you send the
-custom header with no-value then its header must be terminated with a
-semicolon, such as \-H "X-Custom-Header;" to send "X-Custom-Header:".
-
-curl will make sure that each header you add/replace is sent with the proper
+use, your externally set header is used instead of the internal one. This
+allows you to make even trickier stuff than curl would normally do. You should
+not replace internally set headers without knowing perfectly well what you are
+doing. Remove an internal header by giving a replacement without content on
+the right side of the colon, as in: -H "Host:". If you send the custom header
+with no-value then its header must be terminated with a semicolon, such as \-H
+"X-Custom-Header;" to send "X-Custom-Header:".
+
+curl makes sure that each header you add/replace is sent with the proper
end-of-line marker, you should thus **not** add that as a part of the header
-content: do not add newlines or carriage returns, they will only mess things
-up for you.
+content: do not add newlines or carriage returns, they only mess things up for
+you.
This option can take an argument in @filename style, which then adds a header
-for each line in the input file. Using @- will make curl read the header file
-from stdin. Added in 7.55.0.
+for each line in the input file. Using @- makes curl read the header file from
+stdin. Added in 7.55.0.
Please note that most anti-spam utilities check the presence and value of
several MIME mail headers: these are "From:", "To:", "Date:" and "Subject:"
proxy. Added in 7.37.0.
Passing on a "Transfer-Encoding: chunked" header when doing an HTTP request
-with a request body, will make curl send the data using chunked encoding.
+with a request body, makes curl send the data using chunked encoding.
-**WARNING**: headers set with this option will be set in all HTTP requests
-- even after redirects are followed, like when told with --location. This can
-lead to the header being sent to other hosts than the original host, so
-sensitive headers should be used with caution combined with following
-redirects.
+**WARNING**: headers set with this option are set in all HTTP requests - even
+after redirects are followed, like when told with --location. This can lead to
+the header being sent to other hosts than the original host, so sensitive
+headers should be used with caution combined with following redirects.
Multi: single
---
Pass a string containing 32 hexadecimal digits. The string should
-be the 128 bit MD5 checksum of the remote host's public key, curl will refuse
+be the 128 bit MD5 checksum of the remote host's public key, curl refuses
the connection with the host unless the md5sums match.
See-also: hostpubmd5
Multi: single
---
-Pass a string containing a Base64-encoded SHA256 hash of the remote
-host's public key. Curl will refuse the connection with the host
-unless the hashes match.
+Pass a string containing a Base64-encoded SHA256 hash of the remote host's
+public key. Curl refuses the connection with the host unless the hashes match.
This feature requires libcurl to be built with libssh2 and does not work with
other SSH backends.
Multi: append
---
This option enables HSTS for the transfer. If the file name points to an
-existing HSTS cache file, that will be used. After a completed transfer, the
-cache will be saved to the file name again if it has been modified.
+existing HSTS cache file, that is used. After a completed transfer, the
+cache is saved to the file name again if it has been modified.
If curl is told to use HTTP:// for a transfer involving a host name that
exists in the HSTS cache, it upgrades the transfer to use HTTPS. Each HSTS
Specify a "" file name (zero length) to avoid loading/saving and make curl
just handle HSTS in memory.
-If this option is used several times, curl will load contents from all the
-files but the last one will be used for saving.
+If this option is used several times, curl loads contents from all the
+files but the last one is used for saving.
Tells curl to be fine with HTTP version 0.9 response.
HTTP/0.9 is a response without headers and therefore you can also connect with
-this to non-HTTP servers and still get a response since curl will simply
-transparently downgrade - if allowed.
+this to non-HTTP servers and still get a response since curl simply
+transparently downgrades - if allowed.
HTTP/0.9 is disabled by default (added in 7.66.0)
---
Tells curl to issue its non-TLS HTTP requests using HTTP/2 without HTTP/1.1
Upgrade. It requires prior knowledge that the server supports HTTP/2 straight
-away. HTTPS requests will still do HTTP/2 the standard way with negotiated
-protocol version in the TLS handshake.
+away. HTTPS requests still do HTTP/2 the standard way with negotiated protocol
+version in the TLS handshake.
---
Tells curl to use HTTP version 2.
-For HTTPS, this means curl will attempt to negotiate HTTP/2 in the TLS
-handshake. curl does this by default.
+For HTTPS, this means curl negotiates HTTP/2 in the TLS handshake. curl does
+this by default.
-For HTTP, this means curl will attempt to upgrade the request to HTTP/2 using
-the Upgrade: request header.
+For HTTP, this means curl attempts to upgrade the request to HTTP/2 using the
+Upgrade: request header.
When curl uses HTTP/2 over HTTPS, it does not itself insist on TLS 1.2 or
higher even though that is required by the specification. A user can add this
---
Instructs curl to use HTTP/3 to the host in the URL, with no fallback to
earlier HTTP versions. HTTP/3 can only be used for HTTPS and not for HTTP
-URLs. For HTTP, this option will trigger an error.
+URLs. For HTTP, this option triggers an error.
This option allows a user to avoid using the Alt-Svc method of upgrading to
HTTP/3 when you know that the target speaks HTTP/3 on the given host and port.
-This option will make curl fail if a QUIC connection cannot be established, it
-will not attempt any other HTTP version on its own. Use --http3 for similar
+This option makes curl fail if a QUIC connection cannot be established, it
+does not attempt any other HTTP versions on its own. Use --http3 for similar
functionality *with* a fallback.
This option allows a user to avoid using the Alt-Svc method of upgrading to
HTTP/3 when you know that the target speaks HTTP/3 on the given host and port.
-When asked to use HTTP/3, curl will issue a separate attempt to use older HTTP
+When asked to use HTTP/3, curl issues a separate attempt to use older HTTP
versions with a slight delay, so if the HTTP/3 transfer fails or is slow, curl
-will still try to proceed with an older HTTP version.
+still tries to proceed with an older HTTP version.
Use --http3-only for similar functionality *without* a fallback.
Multi: boolean
---
For HTTP, Ignore the Content-Length header. This is particularly useful for
-servers running Apache 1.x, which will report incorrect Content-Length for
+servers running Apache 1.x, which reports incorrect Content-Length for
files larger than 2 gigabytes.
For FTP, this makes curl skip the SIZE command to figure out the size before
--json @foobar and to instead read the data from stdin, use --json @-.
If this option is used more than once on the same command line, the additional
-data pieces will be concatenated to the previous before sending.
+data pieces are concatenated to the previous before sending.
The headers this option sets can be overridden with --header as usual.
Added: 7.9.7
Multi: boolean
---
-When curl is told to read cookies from a given file, this option will make it
-discard all "session cookies". This will basically have the same effect as if
-a new session is started. Typical browsers always discard session cookies when
-they are closed down.
+When curl is told to read cookies from a given file, this option makes it
+discard all "session cookies". This has the same effect as if a new session is
+started. Typical browsers discard session cookies when they are closed down.
'~/.ssh/id_rsa', '~/.ssh/id_dsa', './id_rsa', './id_dsa'.
If curl is built against OpenSSL library, and the engine pkcs11 is available,
-then a PKCS#11 URI (RFC 7512) can be used to specify a private key located in a
-PKCS#11 device. A string beginning with "pkcs11:" will be interpreted as a
-PKCS#11 URI. If a PKCS#11 URI is provided, then the --engine option will be set
-as "pkcs11" if none was provided and the --key-type option will be set as
-"ENG" if none was provided.
+then a PKCS#11 URI (RFC 7512) can be used to specify a private key located in
+a PKCS#11 device. A string beginning with "pkcs11:" is interpreted as a
+PKCS#11 URI. If a PKCS#11 URI is provided, then the --engine option is set as
+"pkcs11" if none was provided and the --key-type option is set as "ENG" if
+none was provided.
If curl is built against Secure Transport or Schannel then this option is
ignored for TLS protocols (HTTPS, etc). Those backends expect the private key
---
Enable Kerberos authentication and use. The level must be entered and should
be one of 'clear', 'safe', 'confidential', or 'private'. Should you use a
-level that is not one of these, 'private' will instead be used.
+level that is not one of these, 'private' is used.
Multi: single
Scope: global
---
-Append this option to any ordinary curl command line, and you will get
-libcurl-using C source code written to the file that does the equivalent
-of what your command-line operation does!
+Append this option to any ordinary curl command line, and you get
+libcurl-using C source code written to the file that does the equivalent of
+what your command-line operation does!
otherwise would be.
The given speed is measured in bytes/second, unless a suffix is appended.
-Appending 'k' or 'K' will count the number as kilobytes, 'm' or 'M' makes it
+Appending 'k' or 'K' counts the number as kilobytes, 'm' or 'M' makes it
megabytes, while 'g' or 'G' makes it gigabytes. The suffixes (k, M, G, T, P)
are 1024 based. For example 1k is 1024. Examples: 200K, 3m and 1G.
The rate limiting logic works on averaging the transfer speed to no more than
the set threshold over a period of multiple seconds.
-If you also use the --speed-limit option, that option will take precedence and
+If you also use the --speed-limit option, that option takes precedence and
might cripple the rate-limiting slightly, to help keeping the speed-limit
logic working.
---
Set a preferred single number or range (FROM-TO) of local port numbers to use
for the connection(s). Note that port numbers by nature are a scarce resource
-that will be busy at times so setting this range to something too narrow might
-cause unnecessary connection setup failures.
+so setting this range to something too narrow might cause unnecessary
+connection setup failures.
Added: 7.10.4
Multi: boolean
---
-Like --location, but will allow sending the name + password to all hosts that
-the site may redirect to. This may or may not introduce a security breach if
-the site redirects you to a site to which you will send your authentication
-info (which is plaintext in the case of HTTP Basic authentication).
+Like --location, but allows sending the name + password to all hosts that the
+site may redirect to. This may or may not introduce a security breach if the
+site redirects you to a site to which you send your authentication info
+(which is plaintext in the case of HTTP Basic authentication).
---
If the server reports that the requested page has moved to a different
location (indicated with a Location: header and a 3XX response code), this
-option will make curl redo the request on the new place. If used together with
---include or --head, headers from all requested pages will be shown. When
-authentication is used, curl only sends its credentials to the initial
-host. If a redirect takes curl to a different host, it will not be able to
-intercept the user+password. See also --location-trusted on how to change
-this. You can limit the amount of redirects to follow by using the
---max-redirs option.
+option makes curl redo the request on the new place. If used together with
+--include or --head, headers from all requested pages are shown.
-When curl follows a redirect and if the request is a POST, it will send the
+When authentication is used, curl only sends its credentials to the initial
+host. If a redirect takes curl to a different host, it does not get the
+user+password pass on. See also --location-trusted on how to change this.
+
+Limit the amount of redirects to follow by using the --max-redirs option.
+
+When curl follows a redirect and if the request is a POST, it sends the
following request with a GET if the HTTP response was 301, 302, or 303. If the
-response code was any other 3xx code, curl will re-send the following request
-using the same unmodified method.
+response code was any other 3xx code, curl resends the following request using
+the same unmodified method.
You can tell curl to not change POST requests to GET after a 30x response by
using the dedicated options for that: --post301, --post302 and --post303.
https://datatracker.ietf.org/doc/html/draft-earhart-url-smtp-00.
Since 8.2.0, IMAP supports the login option "AUTH=+LOGIN". With this option,
-curl uses the plain (not SASL) LOGIN IMAP command even if the server advertises
-SASL authentication. Care should be taken in using this option, as it will send
-out your password in plain text. This will not work if the IMAP server disables
-the plain LOGIN (e.g. to prevent password snooping).
+curl uses the plain (not SASL) LOGIN IMAP command even if the server
+advertises SASL authentication. Care should be taken in using this option, as
+it sends your password over the network in plain text. This does not work if
+the IMAP server disables the plain LOGIN (e.g. to prevent password snooping).
Example: --mail-auth user@example.come -T mail smtp://example.com/
Multi: single
---
-Specify a single address. This will be used to specify the authentication
-address (identity) of a submitted message that is being relayed to another
-server.
+Specify a single address. This is used to specify the authentication address
+(identity) of a submitted message that is being relayed to another server.
See-also: mail-rcpt
Multi: boolean
---
-When sending data to multiple recipients, by default curl will abort SMTP
+When sending data to multiple recipients, by default curl aborts SMTP
conversation if at least one of the recipients causes RCPT TO command to
return an error.
The default behavior can be changed by passing --mail-rcpt-allowfails
-command-line option which will make curl ignore errors and proceed with the
+command-line option which makes curl ignore errors and proceed with the
remaining valid recipients.
If all recipients trigger RCPT TO failures and this flag is specified, curl
-will still abort the SMTP conversation and return the error received from to
-the last RCPT TO command.
+still aborts the SMTP conversation and returns the error received from to the
+last RCPT TO command.
Multi: single
---
Specify the maximum size (in bytes) of a file to download. If the file
-requested is larger than this value, the transfer will not start and curl will
-return with exit code 63.
+requested is larger than this value, the transfer does not start and curl
+returns with exit code 63.
-A size modifier may be used. For example, Appending 'k' or 'K' will count the
+A size modifier may be used. For example, Appending 'k' or 'K' counts the
number as kilobytes, 'm' or 'M' makes it megabytes, while 'g' or 'G' makes it
gigabytes. Examples: 200K, 3m and 1G. (Added in 7.58.0)
or relative) to the netrc file that curl should use. You can only specify one
netrc file per invocation.
-It will abide by --netrc-optional if specified.
+It abides by --netrc-optional if specified.
---
Makes curl scan the *.netrc* (*_netrc* on Windows) file in the user's home
directory for login name and password. This is typically used for FTP on
-Unix. If used with HTTP, curl will enable user authentication. See
-*netrc(5)* and *ftp(1)* for details on the file format. Curl will not
-complain if that file does not have the right permissions (it should be
-neither world- nor group-readable). The environment variable "HOME" is used
-to find the home directory.
+Unix. If used with HTTP, curl enables user authentication. See *netrc(5)* and
+*ftp(1)* for details on the file format. Curl does not complain if that file
+does not have the right permissions (it should be neither world- nor
+group-readable). The environment variable "HOME" is used to find the home
+directory.
A quick and simple example of how to setup a *.netrc* to allow curl to FTP to
the machine host.domain.com with user name 'myself' and password 'secret'
specific options, for example, such as different user names or custom requests
for each.
---next will reset all local options and only global ones will have their
-values survive over to the operation following the --next instruction. Global
-options include --verbose, --trace, --trace-ascii and --fail-early.
+--next resets all local options and only global ones have their values survive
+over to the operation following the --next instruction. Global options include
+--verbose, --trace, --trace-ascii and --fail-early.
For example, you can do both a GET and a POST in a single command line:
Multi: boolean
---
Disables the buffering of the output stream. In normal work situations, curl
-will use a standard buffered output stream that will have the effect that it
-will output the data in chunks, not necessarily exactly when the data arrives.
-Using this option will disable that buffering.
+uses a standard buffered output stream that has the effect that it outputs the
+data in chunks, not necessarily exactly when the data arrives. Using this
+option disables that buffering.
Note that this is the negated option name documented. You can use --buffer to
enable buffering again.
---
When used in conjunction with the --output, --remote-header-name,
--remote-name, or --remote-name-all options, curl avoids overwriting files
-that already exist. Instead, a dot and a number gets appended to the name
-of the file that would be created, up to filename.100 after which it will not
+that already exist. Instead, a dot and a number gets appended to the name of
+the file that would be created, up to filename.100 after which it does not
create any file.
Note that this is the negated option name documented. You can thus use
The given output directory is used for all URLs and output options on the
command line, up until the first --next.
-If the specified target directory does not exist, the operation will fail
-unless --create-dirs is also used.
+If the specified target directory does not exist, the operation fails unless
+--create-dirs is also used.
---
Write output to <file> instead of stdout. If you are using {} or [] to fetch
multiple documents, you should quote the URL and you can use '#' followed by a
-number in the <file> specifier. That variable will be replaced with the current
+number in the <file> specifier. That variable is replaced with the current
string for the URL being fetched. Like in:
curl "http://{one,two}.example.com" -o "file_#1.txt"
curl example.com example.net -o aa -o bb
See also the --create-dirs option to create the local directories
-dynamically. Specifying the output as '-' (a single dash) will force the
-output to be done to stdout.
+dynamically. Specifying the output as '-' (a single dash) passes the output to
+stdout.
To suppress response bodies, you can redirect output to /dev/null:
On Windows, this variable is used when trying to find the home directory. If
the primary home variable are all unset.
.IP "COLUMNS <terminal width>"
-If set, the specified number of characters will be used as the terminal width
-when the alternative progress-bar is shown. If not set, curl will try to
-figure it out using other ways.
+If set, the specified number of characters is used as the terminal width when
+the alternative progress-bar is shown. If not set, curl tries to figure it out
+using other ways.
.IP "CURL_CA_BUNDLE <file>"
-If set, will be used as the --cacert value.
+If set, it is used as the --cacert value.
.IP "CURL_HOME <dir>"
If set, is the first variable curl checks when trying to find its home
directory. If not set, it continues to check *XDG_CONFIG_HOME*
If curl was built with support for "MultiSSL", meaning that it has built-in
support for more than one TLS backend, this environment variable can be set to
the case insensitive name of the particular backend to use when curl is
-invoked. Setting a name that is not a built-in alternative will make curl
-stay with the default.
+invoked. Setting a name that is not a built-in alternative makes curl stay
+with the default.
SSL backend names (case-insensitive): **bearssl**, **gnutls**, **mbedtls**,
**openssl**, **rustls**, **schannel**, **secure-transport**, **wolfssl**
have preference.
.IP "QLOGDIR <directory name>"
If curl was built with HTTP/3 support, setting this environment variable to a
-local directory will make curl produce **qlogs** in that directory, using file
+local directory makes curl produce **qlogs** in that directory, using file
names named after the destination connection id (in hex). Do note that these
files can become rather large. Works with the ngtcp2 and quiche QUIC backends.
.IP SHELL
Used on VMS when trying to detect if using a **DCL** or a **unix** shell.
.IP "SSL_CERT_DIR <dir>"
-If set, will be used as the --capath value.
+If set, it is used as the --capath value.
.IP "SSL_CERT_FILE <path>"
-If set, will be used as the --cacert value.
+If set, it is used as the --cacert value.
.IP "SSLKEYLOGFILE <file name>"
-If you set this environment variable to a file name, curl will store TLS
-secrets from its connections in that file when invoked to enable you to
-analyze the TLS traffic in real time using network analyzing tools such as
-Wireshark. This works with the following TLS backends: OpenSSL, libressl,
-BoringSSL, GnuTLS and wolfSSL.
+If you set this environment variable to a file name, curl stores TLS secrets
+from its connections in that file when invoked to enable you to analyze the
+TLS traffic in real time using network analyzing tools such as Wireshark. This
+works with the following TLS backends: OpenSSL, libressl, BoringSSL, GnuTLS
+and wolfSSL.
.IP "USERPROFILE <dir>"
On Windows, this variable is used when trying to find the home directory. If
-the other, primary, variable are all unset. If set, curl will use the path
+the other, primary, variable are all unset. If set, curl uses the path
**"$USERPROFILE\\Application Data"**.
.IP "XDG_CONFIG_HOME <dir>"
If *CURL_HOME* is not set, this variable is checked when looking for a
The proxy string may be specified with a protocol:// prefix to specify
alternative proxy protocols. (Added in 7.21.7)
-If no protocol is specified in the proxy string or if the string does not match
-a supported one, the proxy will be treated as an HTTP proxy.
+If no protocol is specified in the proxy string or if the string does not
+match a supported one, the proxy is treated as an HTTP proxy.
The supported proxy protocol prefixes are as follows:
.IP "http://"
.IP 88
FTP chunk callback reported error.
.IP 89
-No connection available, the session will be queued.
+No connection available, the session is queued.
.IP 90
SSL public key does not matched pinned public key.
.IP 91
.IP 99
Poll or select returned fatal error.
.IP XX
-More error codes will appear here in future releases. The existing ones
-are meant to never change.
+More error codes might appear here in future releases. The existing ones are
+meant to never change.
.SH BUGS
If you experience any problems with curl, submit an issue in the project's bug
tracker on GitHub: https://github.com/curl/curl/issues
often-used host name prefixes. For example, for host names starting with
"ftp." curl assumes you want FTP.
-You can specify any amount of URLs on the command line. They will be fetched
-in a sequential manner in the specified order unless you use --parallel. You
-can specify command line options and URLs mixed and in any order on the
-command line.
+You can specify any amount of URLs on the command line. They are fetched in a
+sequential manner in the specified order unless you use --parallel. You can
+specify command line options and URLs mixed and in any order on the command
+line.
curl attempts to reuse connections when doing multiple transfers, so that
getting many files from the same server do not use multiple connects and setup
with *json*, URL encode the string with *url* or base64 encode it with
*b64*. You apply function to a variable expansion, add them colon separated to
the right side of the variable. Variable content holding null bytes that are
-not encoded when expanded, will cause error.
+not encoded when expanded cause error.
Example: get the contents of a file called $HOME/.secret into a variable
called "fix". Make sure that the content is trimmed and percent-encoded sent
.IP FILE
Read or write local files. curl does not support accessing file:// URL
remotely, but when running on Microsoft Windows using the native UNC approach
-will work.
+works.
.IP FTP(S)
curl supports the File Transfer Protocol with a lot of tweaks and levers. With
or without using TLS.
When --next is used, it resets the parser state and you start again with a
clean option state, except for the options that are "global". Global options
-will retain their values and meaning even after --next.
+retain their values and meaning even after --next.
The following options are global:
%GLOBALS.
Multi: boolean
Scope: global
---
-When doing parallel transfers, this option will instruct curl that it should
+When doing parallel transfers, this option instructs curl that it should
rather prefer opening up more connections in parallel at once rather than
waiting to see if new transfers can be added as multiplexed streams on another
connection.
Multi: boolean
---
Tell curl to not handle sequences of /../ or /./ in the given URL
-path. Normally curl will squash or merge them according to standards but with
+path. Normally curl squashes or merges them according to standards but with
this option set you tell it not to do that.
When negotiating a TLS or SSL connection, the server sends a certificate
indicating its identity. A public key is extracted from this certificate and
-if it does not exactly match the public key provided to this option, curl will
-abort the connection before sending or receiving any data.
+if it does not exactly match the public key provided to this option, curl
+aborts the connection before sending or receiving any data.
PEM/DER support:
The pre proxy string should be specified with a protocol:// prefix to specify
alternative proxy protocols. Use socks4://, socks4a://, socks5:// or
socks5h:// to request the specific SOCKS version to be used. No protocol
-specified will make curl default to SOCKS4.
+specified makes curl default to SOCKS4.
If the port number is not specified in the proxy string, it is assumed to be
1080.
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
+known size, there is a 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.
curl --proto-redir -all,http,https http://example.com
-By default curl will only allow HTTP, HTTPS, FTP and FTPS on redirect
-(added in 7.65.2). Specifying *all* or *+all* enables all protocols on
-redirects, which is not good for security.
+By default curl only allows HTTP, HTTPS, FTP and FTPS on redirects (added in
+7.65.2). Specifying *all* or *+all* enables all protocols on redirects, which
+is not good for security.
Multi: boolean
---
Tells curl to use the CA store from the native operating system to verify the
-HTTPS proxy. By default, curl will otherwise use a CA store provided in a
-single file or directory, but when using this option it will interface the
-operating system's own vault.
+HTTPS proxy. By default, curl uses a CA store provided in a single file or
+directory, but when using this option it interfaces the operating system's own
+vault.
This option only works for curl on Windows when built to use OpenSSL. When
curl on Windows is built to use Schannel, this feature is implied and curl
then only uses the native CA store.
+
+curl built with wolfSSL also supports this option (added in 8.3.0).
but is for proxy communication only like in CONNECT requests when you want a
separate header sent to the proxy to what is sent to the actual remote host.
-curl will make sure that each header you add/replace is sent with the proper
+curl makes sure that each header you add/replace is sent with the proper
end-of-line marker, you should thus **not** add that as a part of the header
-content: do not add newlines or carriage returns, they will only mess things
-up for you.
+content: do not add newlines or carriage returns, they only mess things up for
+you.
-Headers specified with this option will not be included in requests that curl
-knows will not be sent to a proxy.
+Headers specified with this option are not included in requests that curl
+knows are not be sent to a proxy.
This option can take an argument in @filename style, which then adds a header
-for each line in the input file (added in 7.55.0). Using @- will make curl
-read the header file from stdin.
+for each line in the input file (added in 7.55.0). Using @- makes curl read
+the headers from stdin.
This option can be used multiple times to add/replace/remove multiple headers.
Multi: boolean
---
Tells curl to try negotiate HTTP version 2 with an HTTPS proxy. The proxy might
-still only offer HTTP/1 and then curl will stick to using that version.
+still only offer HTTP/1 and then curl sticks to using that version.
This has no effect for any other kinds of proxies.
When negotiating a TLS or SSL connection, the server sends a certificate
indicating its identity. A public key is extracted from this certificate and
-if it does not exactly match the public key provided to this option, curl will
-abort the connection before sending or receiving any data.
+if it does not exactly match the public key provided to this option, curl
+aborts the connection before sending or receiving any data.
authentication then you can tell curl to select the user name and password
from your environment by specifying a single colon with this option: "-U :".
-On systems where it works, curl will hide the given option argument from
-process listings. This is not enough to protect credentials from possibly
-getting seen by other users on the same system as they will still be visible
-for a moment before cleared. Such sensitive data should be retrieved from a
-file instead or similar and never used in clear text in a command line.
+On systems where it works, curl hides the given option argument from process
+listings. This is not enough to protect credentials from possibly getting seen
+by other users on the same system as they still are visible for a moment
+before cleared. Such sensitive data should be retrieved from a file instead or
+similar and never used in clear text in a command line.
Use the specified proxy.
The proxy string can be specified with a protocol:// prefix. No protocol
-specified or http:// will be treated as HTTP proxy. Use socks4://, socks4a://,
-socks5:// or socks5h:// to request a specific SOCKS version to be used.
-(Added in 7.21.7)
+specified or http:// it is treated as an HTTP proxy. Use socks4://,
+socks4a://, socks5:// or socks5h:// to request a specific SOCKS version to be
+used. (Added in 7.21.7)
Unix domain sockets are supported for socks proxy. Set localhost for the host
part. e.g. socks5h://localhost/path/to/socket.sock
use. If there is an environment variable setting a proxy, you can set proxy to
"" to override it.
-All operations that are performed over an HTTP proxy will transparently be
+All operations that are performed over an HTTP proxy are transparently
converted to HTTP. It means that certain protocol specific operations might
not be available. This is not the case if you can tunnel through the proxy, as
one with the --proxytunnel option.
assumed at port 1080.
The only difference between this and the HTTP proxy option --proxy, is that
-attempts to use CONNECT through the proxy will specify an HTTP 1.0 protocol
+attempts to use CONNECT through the proxy specifies an HTTP 1.0 protocol
instead of the default HTTP 1.1.
Added: 7.3
Multi: boolean
---
-When an HTTP proxy is used --proxy, this option will make curl tunnel through
-the proxy. The tunnel approach is made with the HTTP proxy CONNECT request and
-requires that the proxy allows direct connect to the remote port number curl
-wants to tunnel through to.
+When an HTTP proxy is used --proxy, this option makes curl tunnel the traffic
+through the proxy. The tunnel approach is made with the HTTP proxy CONNECT
+request and requires that the proxy allows direct connect to the remote port
+number curl wants to tunnel through to.
To suppress proxy CONNECT response headers when curl is set to output headers
use --suppress-connect-headers.
You may specify any number of commands.
-By default curl will stop at first failure. To make curl continue even if the
+By default curl stops at first failure. To make curl continue even if the
command fails, prefix the command with an asterisk (*). Otherwise, if the
-server returns failure for one of the commands, the entire operation will be
+server returns failure for one of the commands, the entire operation is
aborted.
You must send syntactically correct FTP commands as RFC 959 defines to FTP
Deprecated option. This option is ignored (added in 7.84.0). Prior to that it
only had an effect on curl if built to use old versions of OpenSSL.
-Specify the path name to file containing what will be considered as random
-data. The data may be used to seed the random engine for SSL connections.
+Specify the path name to file containing random data. The data may be used to
+seed the random engine for SSL connections.
specifies two separate 100-byte ranges(*) (HTTP)
.RE
.IP
-(*) = NOTE that this will cause the server to reply with a multipart
-response, which will be returned as-is by curl! Parsing or otherwise
-transforming this response is the responsibility of the caller.
+(*) = NOTE that this causes the server to reply with a multipart response,
+which is returned as-is by curl! Parsing or otherwise transforming this
+response is the responsibility of the caller.
Only digit characters (0-9) are valid in the 'start' and 'stop' fields of the
-'start-stop' range syntax. If a non-digit character is given in the range,
-the server's response will be unspecified, depending on the server's
-configuration.
+'start-stop' range syntax. If a non-digit character is given in the range, the
+server's response is unspecified, depending on the server's configuration.
-You should also be aware that many HTTP/1.1 servers do not have this feature
-enabled, so that when you attempt to get a range, you will instead get the
-whole document.
+Many HTTP/1.1 servers do not have this feature enabled, so that when you
+attempt to get a range, curl instead gets the whole document.
FTP and SFTP range downloads only support the simple 'start-stop' syntax
(optionally with one of the numbers omitted). FTP use depends on the extended
---
Specify the maximum transfer frequency you allow curl to use - in number of
transfer starts per time unit (sometimes called request rate). Without this
-option, curl will start the next transfer as fast as possible.
+option, curl starts the next transfer as fast as possible.
If given several URLs and a transfer completes faster than the allowed rate,
-curl will wait until the next transfer is started to maintain the requested
+curl waits until the next transfer is started to maintain the requested
rate. This option has no effect when --parallel is used.
The request rate is provided as "N/U" where N is an integer number and U is a
/(day, as in a 24 hour unit). The default time unit, if no "/U" is provided,
is number of transfers per hour.
-If curl is told to allow 10 requests per minute, it will not start the next
+If curl is told to allow 10 requests per minute, it does not start the next
request until 6 seconds have elapsed since the previous transfer was started.
This function uses millisecond resolution. If the allowed frequency is set
-more than 1000 per second, it will instead run unrestricted.
+more than 1000 per second, it instead runs unrestricted.
When retrying transfers, enabled with --retry, the separate retry delay logic
is used and not this setting.
---
This option tells the --remote-name option to use the server-specified
Content-Disposition filename instead of extracting a filename from the URL. If
-the server-provided file name contains a path, that will be stripped off
-before the file name is used.
+the server-provided file name contains a path, that is stripped off before the
+file name is used.
The file is saved in the current directory, or in the directory specified with
--output-dir.
If the server specifies a file name and a file with that name already exists
-in the destination directory, it will not be overwritten and an error will
-occur - unless you allow it by using the --clobber option. If the server does
-not specify a file name then this option has no effect.
+in the destination directory, it is not overwritten and an error occurs -
+unless you allow it by using the --clobber option. If the server does not
+specify a file name then this option has no effect.
There is no attempt to decode %-sequences (yet) in the provided file name, so
this option may provide you with rather unexpected file names.
Write output to a local file named like the remote file we 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 or use --output-dir.
+The file is 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 or use --output-dir.
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. If you want the
+nothing else, and if it already exists it is overwritten. If you want the
server to be able to choose the file name refer to --remote-header-name which
can be used in addition to this option. If the server chooses a file name and
-that name already exists it will not be overwritten.
+that name already exists it is not 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.
+encoded parts of the name, they end up as-is as file name.
You may use this option as many times as the number of URLs you have.
See-also: remote-name time-cond
Multi: boolean
---
-When used, this will make curl attempt to figure out the timestamp of the
-remote file, and if that is available make the local file get that same
+Makes curl attempt to figure out the timestamp of the remote file that is
+getting downloaded, and if that is available make the local file get that same
timestamp.
.RS
.TP 15
**HTTP**
-Specifies a custom request method to use when communicating with the
-HTTP server. The specified request method will be used instead of the method
-otherwise used (which defaults to *GET*). Read the HTTP 1.1 specification for
-details and explanations. Common additional HTTP requests include *PUT* and
-*DELETE*, but related technologies like WebDAV offers *PROPFIND*, *COPY*,
-*MOVE* and more.
+Specifies a custom request method to use when communicating with the HTTP
+server. The specified request method is used instead of the method otherwise
+used (which defaults to *GET*). Read the HTTP 1.1 specification for details
+and explanations. Common additional HTTP requests include *PUT* and *DELETE*,
+but related technologies like WebDAV offers *PROPFIND*, *COPY*, *MOVE* and
+more.
Normally you do not need this option. All sorts of *GET*, *HEAD*, *POST* and
*PUT* requests are rather invoked by using dedicated command line options.
This option only changes the actual word used in the HTTP request, it does not
alter the way curl behaves. So for example if you want to make a proper HEAD
-request, using -X HEAD will not suffice. You need to use the --head option.
+request, using -X HEAD does not suffice. You need to use the --head option.
-The method string you set with --request will be used for all requests, which
+The method string you set with --request is used for all requests, which
if you for example use --location may cause unintended side-effects when curl
does not change request method according to the HTTP 30x response codes - and
similar.
can make the curl requests(s) use a specified address and prevent the
otherwise normally resolved address to be used. Consider it a sort of
/etc/hosts alternative provided on the command line. The port number should be
-the number used for the specific protocol the host will be used for. It means
+the number used for the specific protocol the host is used for. It means
you need several entries if you want to provide address for the same host but
different ports.
By specifying '*' as host you can tell curl to resolve any host and specific
port pair to the specified address. Wildcard is resolved last so any --resolve
-with a specific host and port will be used first.
+with a specific host and port is used first.
-The provided address set by this option will be used even if --ipv4 or --ipv6
-is set to make curl use another IP version.
+The provided address set by this option is used even if --ipv4 or --ipv6 is
+set to make curl use another IP version.
By prefixing the host with a '+' you can make the entry time out after curl's
-default timeout (1 minute). Note that this will only make sense for long
-running parallel transfers with a lot of files. In such cases, if this option
-is used curl will try to resolve the host as it normally would once the
-timeout has expired.
+default timeout (1 minute). Note that this only makes sense for long running
+parallel transfers with a lot of files. In such cases, if this option is used
+curl tries to resolve the host as it normally would once the timeout has
+expired.
Support for providing the IP address within [brackets] was added in 7.57.0.
output via redirect in combination with this option, since you may receive
duplicate data.
-By default curl will not error on an HTTP response code that indicates an HTTP
-error, if the transfer was successful. For example, if a server replies 404
-Not Found and the reply is fully received then that is not an error. When
---retry is used then curl will retry on some HTTP response codes that indicate
-transient HTTP errors, but that does not include most 4xx response codes such
-as 404. If you want to retry on all response codes that indicate HTTP errors
-(4xx and 5xx) then combine with --fail.
+By default curl does not return error for transfers with an HTTP response code
+that indicates an HTTP error, if the transfer was successful. For example, if
+a server replies 404 Not Found and the reply is fully received then that is
+not an error. When --retry is used then curl retries on some HTTP response
+codes that indicate transient HTTP errors, but that does not include most 4xx
+response codes such as 404. If you want to retry on all response codes that
+indicate HTTP errors (4xx and 5xx) then combine with --fail.
Make curl sleep this amount of time before each retry when a transfer has
failed with a transient error (it changes the default backoff time algorithm
between retries). This option is only interesting if --retry is also
-used. Setting this delay to zero will make curl use the default backoff time.
+used. Setting this delay to zero makes curl use the default backoff time.
See-also: retry
Multi: single
---
-The retry timer is reset before the first transfer attempt. Retries will be
-done as usual (see --retry) as long as the timer has not reached this given
-limit. Notice that if the timer has not reached the limit, the request will be
+The retry timer is reset before the first transfer attempt. Retries are done
+as usual (see --retry) as long as the timer has not reached this given
+limit. Notice that if the timer has not reached the limit, the request is
made and while performing, it may take longer than this given time period. To
-limit a single request's maximum time, use --max-time. Set this option to
-zero to not timeout retries.
+limit a single request's maximum time, use --max-time. Set this option to zero
+to not timeout retries.
authentication, in addition to the authentication identity (**authcid**) as
specified by --user.
-If the option is not specified, the server will derive the **authzid** from
-the **authcid**, but if specified, and depending on the server implementation, it
+If the option is not specified, the server derives the **authzid** from the
+**authcid**, but if specified, and depending on the server implementation, it
may be used to access another user's inbox, that the user has been granted
access to, or a shared mailbox for example.
Multi: boolean
---
Silent or quiet mode. Do not show progress meter or error messages. Makes Curl
-mute. It will still output the data you ask for, potentially even to the
+mute. It still outputs the data you ask for, potentially even to the
terminal/stdout unless you redirect it.
Use --show-error in addition to this option to disable progress meter but
See-also: speed-limit limit-rate
Multi: single
---
-If a transfer runs slower than speed-limit bytes per second during a speed-time
-period, the transfer is aborted. If speed-time is used, the default
-speed-limit will be 1 unless set with --speed-limit.
+If a transfer runs slower than speed-limit bytes per second during a
+speed-time period, the transfer is aborted. If speed-time is used, the default
+speed-limit is 1 unless set with --speed-limit.
-This option controls transfers (in both directions) but will not affect slow
+This option controls transfers (in both directions) but does not affect slow
connects etc. If this is a concern for you, try the --connect-timeout option.
This option is unnecessary if you use a URL scheme that in itself implies
immediate and implicit use of TLS, like for FTPS, IMAPS, POP3S, SMTPS and
-LDAPS. Such transfers will always fail if the TLS handshake does not work.
+LDAPS. Such a transfer always fails if the TLS handshake does not work.
This option was formerly known as --ftp-ssl-reqd.
not succeed.
This option was formerly known as --ftp-ssl (added in 7.11.0). That option
-name can still be used but will be removed in a future version.
+name can still be used but might be removed in a future version.
Example: --sslv3 $URL
Multi: mutex
---
-
This option previously asked curl to use SSLv3, but is now ignored
(added in 7.77.0). SSLv3 is widely considered insecure (see RFC 7568).
Multi: single
---
Set the TFTP **BLKSIZE** option (must be >512). This is the block size that
-curl will try to use when transferring data to or from a TFTP server. By
-default 512 bytes will be used.
+curl tries to use when transferring data to or from a TFTP server. By
+default 512 bytes are used.
Multi: append
Scope: global
---
-Set configuration for trace output. A comma-separated list of components
-where detailed output will be made available from. Names are case-insensitive.
+Set configuration for trace output. A comma-separated list of components where
+detailed output can be made available from. Names are case-insensitive.
Specify 'all' to enable all trace components.
In addition to trace component names, specify "ids" and "time" to
See-also: get head
Multi: append
---
-This transfers the specified local file to the remote URL. If there is no file
-part in the specified URL, curl will append the local file name. NOTE that you
-must use a trailing / on the last directory to really prove to Curl that there
-is no file name or curl will think that your last directory name is the remote
-file name to use. That will most likely cause the upload operation to fail. If
-this is used on an HTTP(S) server, the PUT command will be used.
+This transfers the specified local file to the remote URL.
+
+If there is no file part in the specified URL, curl appends the local file
+name to the end of the URL before the operation starts. You must use a
+trailing slash (/) on the last directory to prove to curl that there is no
+file name or curl thinks that your last directory name is the remote file name
+to use. If this is used on an HTTP(S) server, the PUT command is used.
Use the file name "-" (a single dash) to use stdin instead of a given file.
Alternately, the file name "." (a single period) may be specified instead of
When uploading to an SMTP server: the uploaded data is assumed to be RFC 5322
formatted. It has to feature the necessary set of headers and mail body
-formatted correctly by the user as curl will not transcode nor encode it
+formatted correctly by the user as curl does not transcode nor encode it
further in any way.
URL(s) in a config file.
If the given URL is missing a scheme name (such as "http://" or "ftp://" etc)
-then curl will make a guess based on the host. If the outermost subdomain name
-matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that protocol will be used,
-otherwise HTTP will be used. Guessing can be disabled by setting a default
-protocol (added in 7.45.0), see --proto-default for details.
+then curl makes a guess based on the host. If the outermost subdomain name
+matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that protocol is used,
+otherwise HTTP is used. Guessing can be avoided by providing a full URL
+including the scheme, or disabled by setting a default protocol (added in
+7.45.0), see --proto-default for details.
To control where this URL is written, use the --output or the --remote-name
options.
the string, surround the string with single quote marks. This header can also
be set with the --header or the --proxy-header options.
-If you give an empty argument to --user-agent (""), it will remove the header
+If you give an empty argument to --user-agent (""), it removes the header
completely from the request. If you prefer a blank header, you can set it to a
single space (" ").
Specify the user name and password to use for server authentication. Overrides
--netrc and --netrc-optional.
-If you simply specify the user name, curl will prompt for a password.
+If you simply specify the user name, curl prompts for a password.
The user name and passwords are split up on the first colon, which makes it
impossible to use a colon in the user name with this option. The password can,
still.
-On systems where it works, curl will hide the given option argument from
-process listings. This is not enough to protect credentials from possibly
-getting seen by other users on the same system as they will still be visible
-for a moment before cleared. Such sensitive data should be retrieved from a
-file instead or similar and never used in clear text in a command line.
+On systems where it works, curl hides the given option argument from process
+listings. This is not enough to protect credentials from possibly getting seen
+by other users on the same system as they still are visible for a brief moment
+before cleared. Such sensitive data should be retrieved from a file instead or
+similar and never used in clear text in a command line.
When using Kerberos V5 with a Windows based server you should include the
Windows domain name in the user name, in order for the server to successfully
must consist of no other letters than a-z, A-Z, 0-9 or underscore. The
specified content is then associated with this identifier.
-Setting the same variable name again will overwrite the old contents with the
-new.
+Setting the same variable name again overwrites the old contents with the new.
The contents of a variable can be referenced in a later command line option
when that option name is prefixed with "--expand-", and the name is used as
variable contents more convenient to use. You apply a function to a variable
expansion by adding a colon and then list the desired functions in a
comma-separated list that is evaluated in a left-to-right order. Variable
-content holding null bytes that are not encoded when expanded, will cause
+content holding null bytes that are not encoded when expanded, causes an
error.
Available functions:
curl read the format from a file with "@filename" and to tell curl to read the
format from stdin you write "@-".
-The variables present in the output format will be substituted by the value or
+The variables present in the output format are substituted by the value or
text that curl thinks fit, as described below. All variables are specified as
%{variable_name} and to output a normal % you just write them as %%. You can
output a newline by using \\n, a carriage return with \\r and a tab space with
\\t.
-The output will be written to standard output, but this can be switched to
-standard error by using %{stderr}.
+The output is by default written to standard output, but can be changed with
+%{stderr} and %output{}.
Output HTTP headers from the most recent request by using *%header{name}*
where *name* is the case insensitive name of the header (without the trailing
.TP
**redirect_url**
When an HTTP request was made without --location to follow redirects (or when
---max-redirs is met), this variable will show the actual URL a redirect
+--max-redirs is met), this variable shows the actual URL a redirect
*would* have gone to. (Added in 7.18.2)
.TP
**referer**
means the verification was successful. (Added in 7.19.0)
.TP
**stderr**
-From this point on, the --write-out output will be written to standard
+From this point on, the --write-out output is written to standard
error. (Added in 7.63.0)
.TP
**stdout**
-From this point on, the --write-out output will be written to standard output.
+From this point on, the --write-out output is written to standard output.
This is the default, but can be used to switch back after switching to stderr.
(Added in 7.63.0)
.TP
projects / thirdparty / curl.git / commitdiff
