From c5a7f498d48f71b8a4a20eb0c7ae80b81075c6ee Mon Sep 17 00:00:00 2001 From: hovercats Date: Fri, 2 Feb 2024 12:39:27 +0100 Subject: [PATCH] curl: bump to 8.8.0 Upstream has decided that curl.1 should be generated instead of included as a standalone file. --- pkg/curl/.gitignore | 3 +- pkg/curl/README.md | 2 + pkg/curl/curl.1 | 6148 ++++++++++++++++++++++++++++++++++++++++ pkg/curl/curl_config.h | 37 +- pkg/curl/gen.lua | 52 +- pkg/curl/sha256 | 2 +- pkg/curl/url | 2 +- pkg/curl/ver | 2 +- 8 files changed, 6202 insertions(+), 46 deletions(-) create mode 100644 pkg/curl/curl.1 diff --git a/pkg/curl/.gitignore b/pkg/curl/.gitignore index 0160d609..f30119f0 100644 --- a/pkg/curl/.gitignore +++ b/pkg/curl/.gitignore @@ -1,2 +1,3 @@ -/curl-8.5.0.tar.gz +/curl-8.8.0.tar.xz +/curl.1.gz /src diff --git a/pkg/curl/README.md b/pkg/curl/README.md index bac36005..88d20a74 100644 --- a/pkg/curl/README.md +++ b/pkg/curl/README.md @@ -8,6 +8,8 @@ Generated with --disable-smb \ --with-ca-bundle=/etc/ssl/cert.pem \ --with-bearssl \ + --without-libpsl \ + --enable-docs \ CPPFLAGS='-I/src/oasis/out/pkg/bearssl/include -I/src/oasis/out/pkg/zlib/include' \ LDFLAGS='-L/src/oasis/out/pkg/bearssl -L/src/oasis/out/pkg/zlib' diff --git a/pkg/curl/curl.1 b/pkg/curl/curl.1 new file mode 100644 index 00000000..21c77c2a --- /dev/null +++ b/pkg/curl/curl.1 @@ -0,0 +1,6148 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" * SPDX-License-Identifier: curl +.\" * +.\" ************************************************************************** +.\" +.\" DO NOT EDIT. Generated by the curl project managen man page generator. +.\" +.TH curl 1 "2024-06-17" "curl 8.8.0" "curl Manual" +.SH NAME +curl \- transfer a URL +.SH SYNOPSIS +\fBcurl [options / URLs]\fP +.SH DESCRIPTION +\fBcurl\fP is a tool for transferring data from or to a server using URLs. It +supports these protocols: DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, +IMAP, IMAPS, LDAP, LDAPS, MQTT, POP3, POP3S, RTMP, RTMPS, RTSP, SCP, SFTP, +SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. + +curl is powered by libcurl for all transfer\-related features. See +\fIlibcurl(3)\fP for details. +.SH URL +The URL syntax is protocol\-dependent. You find a detailed description in +RFC 3986. + +If you provide a URL without a leading \fBprotocol://\fP scheme, curl guesses +what protocol you want. It then defaults to HTTP but assumes others based on +often\-used hostname prefixes. For example, for hostnames starting with "ftp." +curl assumes you want FTP. + +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 \fI\-Z, \-\-parallel\fP. 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 +handshakes. This improves speed. Connection reuse can only be done for URLs +specified for a single command line invocation and cannot be performed between +separate curl runs. + +Provide an IPv6 zone id in the URL with an escaped percentage sign. Like in +.nf + +\&"http://[fe80::3%25eth0]/" +.fi + +Everything provided on the command line that is not a command line option or +its argument, curl assumes is a URL and treats it as such. +.SH GLOBBING +You can specify multiple URLs or parts of URLs by writing lists within braces +or ranges within brackets. We call this "globbing". + +Provide a list with three different names like this: +.nf + +\&"http://site.{one,two,three}.com" +.fi + +Do sequences of alphanumeric series by using [] as in: +.nf + +\&"ftp://ftp.example.com/file[1\-100].txt" +.fi + +With leading zeroes: +.nf + +\&"ftp://ftp.example.com/file[001\-100].txt" +.fi + +With letters through the alphabet: +.nf + +\&"ftp://ftp.example.com/file[a\-z].txt" +.fi + +Nested sequences are not supported, but you can use several ones next to each +other: +.nf + +\&"http://example.com/archive[1996\-1999]/vol[1\-4]/part{a,b,c}.html" +.fi + +You can specify a step counter for the ranges to get every Nth number or +letter: +.nf + +\&"http://example.com/file[1\-100:10].txt" + +\&"http://example.com/file[a\-z:2].txt" +.fi + +When using [] or {} sequences when invoked from a command line prompt, you +probably have to put the full URL within double quotes to avoid the shell from +interfering with it. This also goes for other characters treated special, like +for example \(aq&\(aq, \(aq?\(aq and \(aq*\(aq. + +Switch off globbing with \fI\-g, \-\-globoff\fP. +.SH VARIABLES +curl supports command line variables (added in 8.3.0). Set variables with +\fI\-\-variable\fP name=content or \fI\-\-variable\fP name@file (where "file" can be stdin if +set to a single dash (\-)). + +Variable contents can be expanded in option parameters using "{{name}}" if the +option name is prefixed with "\fI\-\-expand\-\fP". This gets the contents of the +variable "name" inserted, or a blank if the name does not exist as a +variable. Insert "{{" verbatim in the string by prefixing it with a backslash, +like "\\{{". + +You an access and expand environment variables by first importing them. You +can select to either require the environment variable to be set or you can +provide a default value in case it is not already set. Plain \fI\-\-variable\fP %name +imports the variable called \(aqname\(aq but exits with an error if that environment +variable is not already set. To provide a default value if it is not set, use +\fI\-\-variable\fP %name=content or \fI\-\-variable\fP %name@content. + +Example. Get the USER environment variable into the URL, fail if USER is not +set: +.nf + +-\-variable \(aq%USER\(aq +-\-expand\-url = "https://example.com/api/{{USER}}/method" +.fi + +When expanding variables, curl supports a set of functions that can make the +variable contents more convenient to use. It can trim leading and trailing +white space with "trim", it can output the contents as a JSON quoted string +with "json", URL encode the string with "url" or base64 encode it with "b64". +To apply functions 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 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 when +sent as POST data: +.nf + +-\-variable %HOME +-\-expand\-variable fix@{{HOME}}/.secret +-\-expand\-data "{{fix:trim:url}}" +https://example.com/ +.fi + +Command line variables and expansions were added in 8.3.0. +.SH OUTPUT +If not told otherwise, curl writes the received data to stdout. It can be +instructed to instead save that data into a local file, using the \fI\-o, \-\-output\fP or +\fI\-O, \-\-remote\-name\fP options. If curl is given multiple URLs to transfer on the +command line, it similarly needs multiple options for where to save them. + +curl does not parse or otherwise "understand" the content it gets or writes as +output. It does no encoding or decoding, unless explicitly asked to with +dedicated command line options. +.SH PROTOCOLS +curl supports numerous protocols, or put in URL terms: schemes. Your +particular build may not support them all. +.IP DICT +Lets you lookup words using online dictionaries. +.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 +works. +.IP FTP(S) +curl supports the File Transfer Protocol with a lot of tweaks and levers. With +or without using TLS. +.IP GOPHER(S) +Retrieve files. +.IP HTTP(S) +curl supports HTTP with numerous options and variations. It can speak HTTP +version 0.9, 1.0, 1.1, 2 and 3 depending on build options and the correct +command line options. +.IP IMAP(S) +Using the mail reading protocol, curl can download emails for you. With or +without using TLS. +.IP LDAP(S) +curl can do directory lookups for you, with or without TLS. +.IP MQTT +curl supports MQTT version 3. Downloading over MQTT equals subscribe to a +topic while uploading/posting equals publish on a topic. MQTT over TLS is not +supported (yet). +.IP POP3(S) +Downloading from a pop3 server means getting a mail. With or without using +TLS. +.IP RTMP(S) +The \fBRealtime Messaging Protocol\fP is primarily used to serve streaming media +and curl can download it. +.IP RTSP +curl supports RTSP 1.0 downloads. +.IP SCP +curl supports SSH version 2 scp transfers. +.IP SFTP +curl supports SFTP (draft 5) done over SSH version 2. +.IP SMB(S) +curl supports SMB version 1 for upload and download. +.IP SMTP(S) +Uploading contents to an SMTP server means sending an email. With or without +TLS. +.IP TELNET +Fetching a telnet URL starts an interactive session where it sends what it +reads on stdin and outputs what the server sends it. +.IP TFTP +curl can do TFTP downloads and uploads. +.SH PROGRESS METER +curl normally displays a progress meter during operations, indicating the +amount of transferred data, transfer speeds and estimated time left, etc. The +progress meter displays the transfer rate in bytes per second. The suffixes +(k, M, G, T, P) are 1024 based. For example 1k is 1024 bytes. 1M is 1048576 +bytes. + +curl displays this data to the terminal by default, so if you invoke curl to +do an operation and it is about to write data to the terminal, it \fIdisables\fP +the progress meter as otherwise it would mess up the output mixing progress +meter and response data. + +If you want a progress meter for HTTP POST or PUT requests, you need to +redirect the response output to a file, using shell redirect (>), \fI\-o, \-\-output\fP +or similar. + +This does not apply to FTP upload as that operation does not spit out any +response data to the terminal. + +If you prefer a progress bar instead of the regular meter, \fI\-#, \-\-progress\-bar\fP is +your friend. You can also disable the progress meter completely with the +\fI\-s, \-\-silent\fP option. +.SH VERSION +This man page describes curl 8.8.0. If you use a later version, chances +are this man page does not fully document it. If you use an earlier version, +this document tries to include version information about which specific +version that introduced changes. + +You can always learn which the latest curl version is by running +.nf + +curl https://curl.se/info +.fi + +The online version of this man page is always showing the latest incarnation: +https://curl.se/docs/manpage.html +.SH OPTIONS +Options start with one or two dashes. Many of the options require an +additional value next to them. If provided text does not start with a dash, it +is presumed to be and treated as a URL. + +The short "single\-dash" form of the options, \-d for example, may be used with +or without a space between it and its value, although a space is a recommended +separator. The long double\-dash form, \fI\-d, \-\-data\fP for example, requires a space +between it and its value. + +Short version options that do not need any additional values can be used +immediately next to each other, like for example you can specify all the +options \fI\-O\fP, \fI\-L\fP and \fI\-v\fP at once as \fI\-OLv\fP. + +In general, all boolean options are enabled with \--\fBoption\fP and yet again +disabled with \--\fBno\-\fPoption. That is, you use the same option name but +prefix it with "no\-". However, in this list we mostly only list and show the +-\-\fBoption\fP version of them. + +When \fI\-:, \-\-next\fP 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 +retain their values and meaning even after \fI\-:, \-\-next\fP. + +The following options are global: \fI\-\-fail\-early\fP, \fI\-\-libcurl\fP, \fI\-\-parallel\-immediate\fP, \fI\-Z, \-\-parallel\fP, \fI\-#, \-\-progress\-bar\fP, \fI\-\-rate\fP, \fI\-S, \-\-show\-error\fP, \fI\-\-stderr\fP, \fI\-\-styled\-output\fP, \fI\-\-trace\-ascii\fP, \fI\-\-trace\-config\fP, \fI\-\-trace\-ids\fP, \fI\-\-trace\-time\fP, \fI\-\-trace\fP and \fI\-v, \-\-verbose\fP. +.IP "\-\-abstract\-unix\-socket " +(HTTP) Connect through an abstract Unix domain socket, instead of using the network. +Note: netstat shows the path of an abstract socket prefixed with "@", however +the argument should not have this leading character. + +If --abstract-unix-socket is provided several times, the last set value is used. + +Example: +.nf + curl --abstract-unix-socket socketpath https://example.com +.fi + +See also \fI\-\-unix\-socket\fP. Added in 7.53.0. +.IP "\-\-alt\-svc " +(HTTPS) Enable the alt\-svc parser. If the filename points to an existing alt\-svc cache +file, that gets used. After a completed transfer, the cache is saved to the +filename again if it has been modified. + +Specify a "" filename (zero length) to avoid loading/saving and make curl just +handle the cache in memory. + +If this option is used several times, curl loads contents from all the +files but the last one is used for saving. + +--alt-svc can be used several times in a command line + +Example: +.nf + curl --alt-svc svc.txt https://example.com +.fi + +See also \fI\-\-resolve\fP and \fI\-\-connect\-to\fP. Added in 7.64.1. +.IP "\-\-anyauth" +(HTTP) Figure out authentication method automatically, and use the most secure one +the remote site claims to support. This is done by first doing a request and +checking the response\-headers, thus possibly inducing an extra network +round\-trip. This option is used instead of setting a specific authentication +method, which you can do with \fI\-\-basic\fP, \fI\-\-digest\fP, \fI\-\-ntlm\fP, and \fI\-\-negotiate\fP. + +Using \fI\-\-anyauth\fP 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 fails. + +Used together with \fI\-u, \-\-user\fP. + +Providing --anyauth multiple times has no extra effect. + +Example: +.nf + curl --anyauth --user me:pwd https://example.com +.fi + +See also \fI\-\-proxy\-anyauth\fP, \fI\-\-basic\fP and \fI\-\-digest\fP. +.IP "\-a, \-\-append" +(FTP SFTP) 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). + +Providing --append multiple times has no extra effect. +Disable it again with \-\-no-append. + +Example: +.nf + curl --upload-file local --append ftp://example.com/ +.fi + +See also \fI-r, \-\-range\fP and \fI-C, \-\-continue\-at\fP. +.IP "\-\-aws\-sigv4 " +(HTTP) Use AWS V4 signature authentication in the transfer. + +The provider argument is a string that is used by the algorithm when creating +outgoing authentication headers. + +The region argument is a string that points to a geographic area of +a resources collection (region\-code) when the region name is omitted from +the endpoint. + +The service argument is a string that points to a function provided by a cloud +(service\-code) when the service name is omitted from the endpoint. + +If --aws-sigv4 is provided several times, the last set value is used. + +Example: +.nf + curl --aws-sigv4 "aws:amz:us-east-2:es" --user "key:secret" https://example.com +.fi + +See also \fI\-\-basic\fP and \fI-u, \-\-user\fP. Added in 7.75.0. +.IP "\-\-basic" +(HTTP) Use HTTP Basic authentication with the remote host. This method is the default +and this option is usually pointless, unless you use it to override a +previously set option that sets a different authentication method (such as +\fI\-\-ntlm\fP, \fI\-\-digest\fP, or \fI\-\-negotiate\fP). + +Used together with \fI\-u, \-\-user\fP. + +Providing --basic multiple times has no extra effect. + +Example: +.nf + curl -u name:password --basic https://example.com +.fi + +See also \fI\-\-proxy\-basic\fP. +.IP "\-\-ca\-native" +(TLS) Use the CA store from the native operating system to verify the 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\(aqs own +vault. + +This option works for curl on Windows when built to use OpenSSL, wolfSSL +(added in 8.3.0) or GnuTLS (added in 8.5.0). When curl on Windows is built to +use Schannel, this feature is implied and curl then only uses the native CA +store. + +Providing --ca-native multiple times has no extra effect. +Disable it again with \-\-no-ca-native. + +Example: +.nf + curl --ca-native https://example.com +.fi + +See also \fI\-\-cacert\fP, \fI\-\-capath\fP and \fI-k, \-\-insecure\fP. Added in 8.2.0. +.IP "\-\-cacert " +(TLS) Use the specified certificate file to verify the peer. The file may contain +multiple CA certificates. The certificate(s) must be in PEM format. Normally +curl is built to use a default file for this, so this option is typically used +to alter that default file. + +curl recognizes the environment variable named \(aqCURL_CA_BUNDLE\(aq if it is set +and the TLS backend is not Schannel, and uses the given path as a path to a CA +cert bundle. This option overrides that variable. + +The windows version of curl automatically looks for a CA certs file named +\(aqcurl\-ca\-bundle.crt\(aq, 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 uses the certificates +in the system and user Keychain to verify the peer, which is the preferred +method of verifying the peer\(aqs 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 +other SSL engines; instead it is recommended to use Windows\(aq store of root +certificates (the default for Schannel). + +If --cacert is provided several times, the last set value is used. + +Example: +.nf + curl --cacert CA-file.txt https://example.com +.fi + +See also \fI\-\-capath\fP and \fI-k, \-\-insecure\fP. +.IP "\-\-capath " +(TLS) Use the specified certificate directory to verify the peer. Multiple paths can +be provided by separated with colon (":") (e.g. "path1:path2:path3"). The +certificates must be in PEM format, and if curl is built against OpenSSL, the +directory must have been processed using the c_rehash utility supplied with +OpenSSL. Using \fI\-\-capath\fP can allow OpenSSL\-powered curl to make SSL\-connections +much more efficiently than using \fI\-\-cacert\fP if the \fI\-\-cacert\fP file contains many +CA certificates. + +If this option is set, the default capath value is ignored. + +If --capath is provided several times, the last set value is used. + +Example: +.nf + curl --capath /local/directory https://example.com +.fi + +See also \fI\-\-cacert\fP and \fI-k, \-\-insecure\fP. +.IP "\-E, \-\-cert " +(TLS) 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 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 \fI\-E, \-\-cert\fP and \fI\-\-key\fP to specify them +independently. + +In the portion of the argument, you must escape the character +\&":" as "\\:" so that it is not recognized as the password delimiter. Similarly, +you must escape the double quote character as \\" so that it is not recognized +as an escape character. + +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:" is interpreted as a +PKCS#11 URI. If a PKCS#11 URI is provided, then the \fI\-\-engine\fP option is set as +\&"pkcs11" if none was provided and the \fI\-\-cert\-type\fP 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 +system or user keychain, or the path to a PKCS#12\-encoded certificate and +private key. If you want to use a file from the current directory, please +precede it with "./" prefix, in order to avoid confusion with a nickname. + +(Schannel only) Client certificates must be specified by a path expression to +a certificate store. (Loading \fIPFX\fP is not supported; you can import it to a +store first). You can use "\\\\" +to refer to a certificate in the system certificates store, for example, +\fI"CurrentUser\\MY\\934a7ac6f8a5d579285a74fa61e19f23ddfe8d7a"\fP. Thumbprint is +usually a SHA\-1 hex string which you can see in certificate details. Following +store locations are supported: \fICurrentUser\fP, \fILocalMachine\fP, +\fICurrentService\fP, \fIServices\fP, \fICurrentUserGroupPolicy\fP, +\fILocalMachineGroupPolicy\fP and \fILocalMachineEnterprise\fP. + +If --cert is provided several times, the last set value is used. + +Example: +.nf + curl --cert certfile --key keyfile https://example.com +.fi + +See also \fI\-\-cert\-type\fP, \fI\-\-key\fP and \fI\-\-key\-type\fP. +.IP "\-\-cert\-status" +(TLS) Verify the status of the server certificate by using the Certificate Status +Request (aka. OCSP stapling) TLS extension. + +If this option is enabled and the server sends an invalid (e.g. expired) +response, if the response suggests that the server certificate has been +revoked, or no response at all is received, the verification fails. + +This support is currently only implemented in the OpenSSL and GnuTLS backends. + +Providing --cert-status multiple times has no extra effect. +Disable it again with \-\-no-cert-status. + +Example: +.nf + curl --cert-status https://example.com +.fi + +See also \fI\-\-pinnedpubkey\fP. +.IP "\-\-cert\-type " +(TLS) Set type of the provided client certificate. PEM, DER, ENG and P12 are +recognized types. + +The default type depends on the TLS backend and is usually PEM, however for +Secure Transport and Schannel it is P12. If \fI\-E, \-\-cert\fP is a pkcs11: URI then ENG is +the default type. + +If --cert-type is provided several times, the last set value is used. + +Example: +.nf + curl --cert-type PEM --cert file https://example.com +.fi + +See also \fI-E, \-\-cert\fP, \fI\-\-key\fP and \fI\-\-key\-type\fP. +.IP "\-\-ciphers " +(TLS) Specifies which ciphers to use in the connection. The list of ciphers must +specify valid ciphers. Read up on SSL cipher list details on this URL: + +https://curl.se/docs/ssl\-ciphers.html + +If --ciphers is provided several times, the last set value is used. + +Example: +.nf + curl --ciphers ECDHE-ECDSA-AES256-CCM8 https://example.com +.fi + +See also \fI\-\-tlsv1.3\fP, \fI\-\-tls13\-ciphers\fP and \fI\-\-proxy\-ciphers\fP. +.IP "\-\-compressed" +(HTTP) Request a compressed response using one of the algorithms curl supports, and +automatically decompress the content. + +Response headers are not modified when saved, so if they are "interpreted" +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 +reports an error. This is a request, not an order; the server may or may not +deliver data compressed. + +Providing --compressed multiple times has no extra effect. +Disable it again with \-\-no-compressed. + +Example: +.nf + curl --compressed https://example.com +.fi + +See also \fI\-\-compressed\-ssh\fP. +.IP "\-\-compressed\-ssh" +(SCP SFTP) Enables built\-in SSH compression. This is a request, not an order; the server +may or may not do it. + +Providing --compressed-ssh multiple times has no extra effect. +Disable it again with \-\-no-compressed-ssh. + +Example: +.nf + curl --compressed-ssh sftp://example.com/ +.fi + +See also \fI\-\-compressed\fP. Added in 7.56.0. +.IP "\-K, \-\-config " +Specify a text file to read curl arguments from. The command line arguments +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, +separated by whitespace, colon, or the equals sign. Long option names can +optionally be given in the config file without the initial double dashes and +if so, the colon or equals characters can be used as separators. If the option +is specified with one or two dashes, there can be no colon or equals character +between the option and its parameter. + +If the parameter contains whitespace or starts with a colon (:) or equals sign +(=), it must be specified enclosed within double quotes ("like this"). Within +double quotes the following escape sequences are available: \\\\, \\", \\t, \\n, \\r +and \\v. A backslash preceding any other letter is ignored. + +If the first non\-blank column of a config line is a \(aq#\(aq character, that line +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). + +Specify the filename to \fI\-K, \-\-config\fP as minus "\-" to make curl read the file from +stdin. + +Note that to be able to specify a URL in the config file, you need to specify +it using the \fI\-\-url\fP option, and not by simply writing the URL on its own +line. So, it could look similar to this: +.nf + +url = "https://curl.se/docs/" + +# \--\- Example file \--\- +# this is a comment +url = "example.com" +output = "curlhere.html" +user\-agent = "superagent/1.0" + +# and fetch another URL too +url = "example.com/docs/manpage.html" +-O +referer = "http://nowhereatall.example.com/" +# \--\- End of example file \--\- +.fi + +When curl is invoked, it (unless \fI\-q, \-\-disable\fP is used) checks for a default +config file and uses it if found, even when \fI\-K, \-\-config\fP is used. The default +config file is checked for in the following places in this order: + +1) \fB"$CURL_HOME/.curlrc"\fP + +2) \fB"$XDG_CONFIG_HOME/curlrc"\fP (Added in 7.73.0) + +3) \fB"$HOME/.curlrc"\fP + +4) Windows: \fB"%USERPROFILE%\\.curlrc"\fP + +5) Windows: \fB"%APPDATA%\\.curlrc"\fP + +6) Windows: \fB"%USERPROFILE%\\Application Data\\.curlrc"\fP + +7) Non\-Windows: use getpwuid to find the home directory + +8) On Windows, if it finds no \fI.curlrc\fP file in the sequence described above, it +checks for one in the same directory the curl executable is placed. + +On Windows two filenames are checked per location: \fI.curlrc\fP and \fI_curlrc\fP, +preferring the former. Older versions on Windows checked for \fI_curlrc\fP only. + +--config can be used several times in a command line + +Example: +.nf + curl --config file.txt https://example.com +.fi + +See also \fI-q, \-\-disable\fP. +.IP "\-\-connect\-timeout " +Maximum time in seconds that you allow curl\(aqs connection to take. This only +limits the connection phase, so if curl connects within the given period it +continues \- if not it exits. + +This option accepts decimal values. The decimal value needs +to be provided using a dot (.) as decimal separator \- not the local version +even if it might be using another separator. + +The connection phase is considered complete when the DNS lookup and requested +TCP, TLS or QUIC handshakes are done. + +If --connect-timeout is provided several times, the last set value is used. + +Examples: +.nf + curl --connect-timeout 20 https://example.com + curl --connect-timeout 3.14 https://example.com +.fi + +See also \fI-m, \-\-max\-time\fP. +.IP "\-\-connect\-to " +For a request intended for the "HOST1:PORT1" pair, connect to "HOST2:PORT2" +instead. This option is only used to establish the network connection. It does +NOT affect the hostname/port number that is used for TLS/SSL (e.g. SNI, +certificate verification) or for the application protocols. + +\&"HOST1" and "PORT1" may be empty strings, meaning any host or any port number. +\&"HOST2" and "PORT2" may also be empty strings, meaning use the request\(aqs +original hostname and port number. + +A hostname specified to this option is compared as a string, so it needs to +match the name used in request URL. It can be either numerical such as +\&"127.0.0.1" or the full host name such as "example.org". + +--connect-to can be used several times in a command line + +Example: +.nf + curl --connect-to example.com:443:example.net:8443 https://example.com +.fi + +See also \fI\-\-resolve\fP and \fI-H, \-\-header\fP. +.IP "\-C, \-\-continue\-at " +Resume a previous transfer from the given byte offset. The given offset 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 is not used by curl. + +Use "\-C \-" to instruct curl to automatically find out where/how to resume the +transfer. It then uses the given output/input files to figure that out. + +If --continue-at is provided several times, the last set value is used. + +Examples: +.nf + curl -C - https://example.com + curl -C 400 https://example.com +.fi + +See also \fI-r, \-\-range\fP. +.IP "\-b, \-\-cookie " +(HTTP) Pass the data to the HTTP server in the Cookie header. It is supposedly the +data previously received from the server in a "Set\-Cookie:" line. The data +should be in the format "NAME1=VALUE1; NAME2=VALUE2" or as a single filename. + +When given a set of specific cookies and not a filename, it 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 all get this cookie header 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 makes curl record incoming cookies, which may be handy if you are +using this in combination with the \fI\-L, \-\-location\fP option or do multiple URL +transfers on the same invoke. + +If the filename is a single minus ("\-"), curl reads the contents from stdin. +If the filename is an empty string ("") and is the only cookie input, curl +activates the cookie engine without any cookies. + +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 \fI\-b, \-\-cookie\fP is only used as input. No cookies are written +to that file. To store cookies, use the \fI\-c, \-\-cookie\-jar\fP option. + +If you use the Set\-Cookie file format and do not specify a domain then the +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 \fI\-b, \-\-cookie\fP and \fI\-c, \-\-cookie\-jar\fP in the same command +line is common. + +If curl is built with PSL (\fBPublic Suffix List\fP) support, it detects and +discards cookies that are specified for such suffix domains that should not be +allowed to have cookies. If curl is \fInot\fP built with PSL support, it has no +ability to stop super cookies. + +--cookie can be used several times in a command line + +Examples: +.nf + curl -b "" https://example.com + curl -b cookiefile https://example.com + curl -b cookiefile -c cookiefile https://example.com + curl -b name=Jane https://example.com +.fi + +See also \fI-c, \-\-cookie\-jar\fP and \fI-j, \-\-junk\-session\-cookies\fP. +.IP "\-c, \-\-cookie\-jar " +(HTTP) 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. Even if no cookies are known, a file is +created so that it removes any formerly existing cookies from the file. The +file uses the Netscape cookie file format. If you set the filename to a single +minus, "\-", the cookies are written to stdout. + +The file specified with \fI\-c, \-\-cookie\-jar\fP is only used for output. No cookies are +read from the file. To read cookies, use the \fI\-b, \-\-cookie\fP option. Both options +can specify the same file. + +This command line option activates the cookie engine that makes curl record +and use cookies. The \fI\-b, \-\-cookie\fP option also activates it. + +If the cookie jar cannot be created or written to, the whole curl operation +does not fail or even report an error clearly. Using \fI\-v, \-\-verbose\fP gets a warning +displayed, but that is the only visible feedback you get about this possibly +lethal situation. + +If --cookie-jar is provided several times, the last set value is used. + +Examples: +.nf + curl -c store-here.txt https://example.com + curl -c store-here.txt -b read-these https://example.com +.fi + +See also \fI-b, \-\-cookie\fP. +.IP "\-\-create\-dirs" +When used in conjunction with the \fI\-o, \-\-output\fP option, curl creates the necessary +local directory hierarchy as needed. This option creates the directories +mentioned with the \fI\-o, \-\-output\fP option combined with the path possibly set with +\fI\-\-output\-dir\fP. If the combined output filename 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. + +To create remote directories when using FTP or SFTP, try \fI\-\-ftp\-create\-dirs\fP. + +Providing --create-dirs multiple times has no extra effect. +Disable it again with \-\-no-create-dirs. + +Example: +.nf + curl --create-dirs --output local/dir/file https://example.com +.fi + +See also \fI\-\-ftp\-create\-dirs\fP and \fI\-\-output\-dir\fP. +.IP "\-\-create\-file\-mode " +(SFTP SCP FILE) When curl is used to create files remotely using one of the supported +protocols, this option allows the user to set which \(aqmode\(aq to set on the file +at creation time, instead of the default 0644. + +This option takes an octal number as argument. + +If --create-file-mode is provided several times, the last set value is used. + +Example: +.nf + curl --create-file-mode 0777 -T localfile sftp://example.com/new +.fi + +See also \fI\-\-ftp\-create\-dirs\fP. Added in 7.75.0. +.IP "\-\-crlf" +(FTP SMTP) Convert line feeds to carriage return plus line feeds in upload. Useful for +\fBMVS (OS/390)\fP. + +(SMTP added in 7.40.0) + +Providing --crlf multiple times has no extra effect. +Disable it again with \-\-no-crlf. + +Example: +.nf + curl --crlf -T file ftp://example.com/ +.fi + +See also \fI-B, \-\-use\-ascii\fP. +.IP "\-\-crlfile " +(TLS) Provide a file using PEM format with a Certificate Revocation List that may +specify peer certificates that are to be considered revoked. + +If --crlfile is provided several times, the last set value is used. + +Example: +.nf + curl --crlfile rejects.txt https://example.com +.fi + +See also \fI\-\-cacert\fP and \fI\-\-capath\fP. +.IP "\-\-curves " +(TLS) Set specific curves to use during SSL session establishment according to RFC +8422, 5.1. Multiple algorithms can be provided by separating them with ":" +(e.g. "X25519:P\-521"). The parameter is available identically in the OpenSSL +\&"s_client" and "s_server" utilities. + +\fI\-\-curves\fP allows a OpenSSL powered curl to make SSL\-connections with exactly +the (EC) curve requested by the client, avoiding nontransparent client/server +negotiations. + +If this option is set, the default curves list built into OpenSSL are ignored. + +If --curves is provided several times, the last set value is used. + +Example: +.nf + curl --curves X25519 https://example.com +.fi + +See also \fI\-\-ciphers\fP. Added in 7.73.0. +.IP "\-d, \-\-data " +(HTTP MQTT) 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 option makes curl pass the data to the server using the +content\-type application/x\-www\-form\-urlencoded. Compare to \fI\-F, \-\-form\fP. + +\fI\-\-data\-raw\fP is almost the same but does not have a special interpretation of +the @ character. To post data purely binary, you should instead use the +\fI\-\-data\-binary\fP option. To URL\-encode the value of a form field you may use +\fI\-\-data\-urlencode\fP. + +If any of these options is used more than once on the same command line, the +data pieces specified are merged with a separating &\-symbol. Thus, using +\(aq\-d name=daniel \-d skill=lousy\(aq would generate a post chunk that looks like +\(aqname=daniel&skill=lousy\(aq. + +If you start the data with the letter @, the rest should be a filename to read +the data from, or \- if you want curl to read the data from stdin. Posting data +from a file named \(aqfoobar\(aq would thus be done with \fI\-d, \-\-data\fP @foobar. When \fI\-d, \-\-data\fP +is told to read from a file like that, carriage returns, newlines and null +bytes are stripped out. If you do not want the @ character to have a special +interpretation use \fI\-\-data\-raw\fP instead. + +The data for this option is passed on to the server exactly as provided on the +command line. curl does not convert, change or improve it. It is up to the +user to provide the data in the correct form. + +--data can be used several times in a command line + +Examples: +.nf + curl -d "name=curl" https://example.com + curl -d "name=curl" -d "tool=cmdline" https://example.com + curl -d @filename https://example.com +.fi + +See also \fI\-\-data\-binary\fP, \fI\-\-data\-urlencode\fP and \fI\-\-data\-raw\fP. This option is mutually exclusive to \fI-F, \-\-form\fP and \fI-I, \-\-head\fP and \fI-T, \-\-upload\-file\fP. +.IP "\-\-data\-ascii " +(HTTP) This option is just an alias for \fI\-d, \-\-data\fP. + +--data-ascii can be used several times in a command line + +Example: +.nf + curl --data-ascii @file https://example.com +.fi + +See also \fI\-\-data\-binary\fP, \fI\-\-data\-raw\fP and \fI\-\-data\-urlencode\fP. +.IP "\-\-data\-binary " +(HTTP) Post data exactly as specified with no extra processing whatsoever. + +If you start the data with the letter @, the rest should be a filename. Data +is posted in a similar manner as \fI\-d, \-\-data\fP does, except that newlines and +carriage returns are preserved and conversions are never done. + +Like \fI\-d, \-\-data\fP the default content\-type sent to the server is +application/x\-www\-form\-urlencoded. If you want the data to be treated as +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 append +data as described in \fI\-d, \-\-data\fP. + +--data-binary can be used several times in a command line + +Example: +.nf + curl --data-binary @filename https://example.com +.fi + +See also \fI\-\-data\-ascii\fP. +.IP "\-\-data\-raw " +(HTTP) Post data similarly to \fI\-d, \-\-data\fP but without the special interpretation of the @ +character. + +--data-raw can be used several times in a command line + +Examples: +.nf + curl --data-raw "hello" https://example.com + curl --data-raw "@at@at@" https://example.com +.fi + +See also \fI-d, \-\-data\fP. +.IP "\-\-data\-urlencode " +(HTTP) Post data, similar to the other \fI\-d, \-\-data\fP options with the exception that this +performs URL\-encoding. + +To be CGI\-compliant, the part should begin with a \fIname\fP followed by +a separator and a content specification. The part can be passed to +curl using one of the following syntaxes: +.RS +.IP content +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 +URL\-encode the content and pass that on. The preceding "=" symbol is not +included in the data. +.IP name=content +URL\-encode the content part and pass that on. Note that the name part is +expected to be URL\-encoded already. +.IP @filename +load data from the given file (including any newlines), URL\-encode that data +and pass it on in the POST. +.IP name@filename +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 \fIname=urlencoded\-file\-content\fP. Note that the name is expected to +be URL\-encoded already. +.RE +.IP + +--data-urlencode can be used several times in a command line + +Examples: +.nf + curl --data-urlencode name=val https://example.com + curl --data-urlencode =encodethis https://example.com + curl --data-urlencode name@file https://example.com + curl --data-urlencode @fileonly https://example.com +.fi + +See also \fI-d, \-\-data\fP and \fI\-\-data\-raw\fP. +.IP "\-\-delegation " +(GSS/kerberos) Set LEVEL what curl is allowed to delegate when it comes to user credentials. +.RS +.IP none +Do not allow any delegation. +.IP policy +Delegates if and only if the OK\-AS\-DELEGATE flag is set in the Kerberos +service ticket, which is a matter of realm policy. +.IP always +Unconditionally allow the server to delegate. +.RE +.IP + +If --delegation is provided several times, the last set value is used. + +Example: +.nf + curl --delegation "none" https://example.com +.fi + +See also \fI-k, \-\-insecure\fP and \fI\-\-ssl\fP. +.IP "\-\-digest" +(HTTP) Enables HTTP Digest authentication. This authentication scheme avoids sending +the password over the wire in clear text. Use this in combination with the +normal \fI\-u, \-\-user\fP option to set username and password. + +Providing --digest multiple times has no extra effect. +Disable it again with \-\-no-digest. + +Example: +.nf + curl -u name:password --digest https://example.com +.fi + +See also \fI-u, \-\-user\fP, \fI\-\-proxy\-digest\fP and \fI\-\-anyauth\fP. This option is mutually exclusive to \fI\-\-basic\fP and \fI\-\-ntlm\fP and \fI\-\-negotiate\fP. +.IP "\-q, \-\-disable" +If used as the \fBfirst\fP parameter on the command line, the \fIcurlrc\fP config +file is not read or used. See the \fI\-K, \-\-config\fP for details on the default config +file search path. + +Prior to 7.50.0 curl supported the short option name \fIq\fP but not the long +option name \fIdisable\fP. + +Providing --disable multiple times has no extra effect. +Disable it again with \-\-no-disable. + +Example: +.nf + curl -q https://example.com +.fi + +See also \fI-K, \-\-config\fP. +.IP "\-\-disable\-eprt" +(FTP) Disable the use of the EPRT and LPRT commands when doing active 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. + +\fI\-\-eprt\fP can be used to explicitly enable EPRT again and \fI\-\-no\-eprt\fP is an alias +for \fI\-\-disable\-eprt\fP. + +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 \fI\-P, \-\-ftp\-port\fP or force it with \fI\-\-ftp\-pasv\fP. + +Providing --disable-eprt multiple times has no extra effect. +Disable it again with \-\-no-disable-eprt. + +Example: +.nf + curl --disable-eprt ftp://example.com/ +.fi + +See also \fI\-\-disable\-epsv\fP and \fI-P, \-\-ftp\-port\fP. +.IP "\-\-disable\-epsv" +(FTP) Disable the use of the EPSV command when doing passive FTP transfers. Curl +normally first attempts to use EPSV before PASV, but with this option, it does +not try EPSV. + +\fI\-\-epsv\fP can be used to explicitly enable EPSV again and \fI\-\-no\-epsv\fP is an alias +for \fI\-\-disable\-epsv\fP. + +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 \fI\-P, \-\-ftp\-port\fP. + +Providing --disable-epsv multiple times has no extra effect. +Disable it again with \-\-no-disable-epsv. + +Example: +.nf + curl --disable-epsv ftp://example.com/ +.fi + +See also \fI\-\-disable\-eprt\fP and \fI-P, \-\-ftp\-port\fP. +.IP "\-\-disallow\-username\-in\-url" +Exit with error if passed a URL containing a username. Probably most useful +when the URL is being provided at runtime or similar. + +Providing --disallow-username-in-url multiple times has no extra effect. +Disable it again with \-\-no-disallow-username-in-url. + +Example: +.nf + curl --disallow-username-in-url https://example.com +.fi + +See also \fI\-\-proto\fP. Added in 7.61.0. +.IP "\-\-dns\-interface " +(DNS) Send outgoing DNS requests through the given interface. This option is a +counterpart to \fI\-\-interface\fP (which does not affect DNS). The supplied string +must be an interface name (not an address). + +If --dns-interface is provided several times, the last set value is used. + +Example: +.nf + curl --dns-interface eth0 https://example.com +.fi + +See also \fI\-\-dns\-ipv4\-addr\fP and \fI\-\-dns\-ipv6\-addr\fP. \fI\-\-dns\-interface\fP requires that the underlying libcurl was built to support c-ares. +.IP "\-\-dns\-ipv4\-addr
" +(DNS) Bind to a specific IP address when making IPv4 DNS requests, so that the DNS +requests originate from this address. The argument should be a single IPv4 +address. + +If --dns-ipv4-addr is provided several times, the last set value is used. + +Example: +.nf + curl --dns-ipv4-addr 10.1.2.3 https://example.com +.fi + +See also \fI\-\-dns\-interface\fP and \fI\-\-dns\-ipv6\-addr\fP. \fI\-\-dns\-ipv4\-addr\fP requires that the underlying libcurl was built to support c-ares. +.IP "\-\-dns\-ipv6\-addr
" +(DNS) Bind to a specific IP address when making IPv6 DNS requests, so that the DNS +requests originate from this address. The argument should be a single IPv6 +address. + +If --dns-ipv6-addr is provided several times, the last set value is used. + +Example: +.nf + curl --dns-ipv6-addr 2a04:4e42::561 https://example.com +.fi + +See also \fI\-\-dns\-interface\fP and \fI\-\-dns\-ipv4\-addr\fP. \fI\-\-dns\-ipv6\-addr\fP requires that the underlying libcurl was built to support c-ares. +.IP "\-\-dns\-servers " +(DNS) Set the list of DNS servers to be used instead of the system default. The list +of IP addresses should be separated with commas. Port numbers may also +optionally be given, appended to the IP address separated with a colon. + +If --dns-servers is provided several times, the last set value is used. + +Examples: +.nf + curl --dns-servers 192.168.0.1,192.168.0.2 https://example.com + curl --dns-servers 10.0.0.1:53 https://example.com +.fi + +See also \fI\-\-dns\-interface\fP and \fI\-\-dns\-ipv4\-addr\fP. \fI\-\-dns\-servers\fP requires that the underlying libcurl was built to support c-ares. +.IP "\-\-doh\-cert\-status" +Same as \fI\-\-cert\-status\fP but used for DoH (DNS\-over\-HTTPS). + +Verifies the status of the DoH servers\(aq certificate by using the Certificate +Status Request (aka. OCSP stapling) TLS extension. + +If this option is enabled and the DoH server sends an invalid (e.g. expired) +response, if the response suggests that the server certificate has been +revoked, or no response at all is received, the verification fails. + +This support is currently only implemented in the OpenSSL and GnuTLS backends. + +Providing --doh-cert-status multiple times has no extra effect. +Disable it again with \-\-no-doh-cert-status. + +Example: +.nf + curl --doh-cert-status --doh-url https://doh.example https://example.com +.fi + +See also \fI\-\-doh\-insecure\fP. Added in 7.76.0. +.IP "\-\-doh\-insecure" +Same as \fI\-k, \-\-insecure\fP but used for DoH (DNS\-over\-HTTPS). + +Providing --doh-insecure multiple times has no extra effect. +Disable it again with \-\-no-doh-insecure. + +Example: +.nf + curl --doh-insecure --doh-url https://doh.example https://example.com +.fi + +See also \fI\-\-doh\-url\fP. Added in 7.76.0. +.IP "\-\-doh\-url " +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 also applies to DoH since the +name lookups take place over SSL. However, the certificate verification +settings are not inherited but are controlled separately via \fI\-\-doh\-insecure\fP +and \fI\-\-doh\-cert\-status\fP. + +This option is unset if an empty string "" is used as the URL. +(Added in 7.85.0) + +If --doh-url is provided several times, the last set value is used. + +Example: +.nf + curl --doh-url https://doh.example https://example.com +.fi + +See also \fI\-\-doh\-insecure\fP. Added in 7.62.0. +.IP "\-D, \-\-dump\-header " +(HTTP FTP) Write the received protocol headers to the specified file. If no headers are +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 +\fI\-:, \-\-next\fP clause), appends them to the same file, separated by a blank line. + +If --dump-header is provided several times, the last set value is used. + +Example: +.nf + curl --dump-header store.txt https://example.com +.fi + +See also \fI-o, \-\-output\fP. +.IP "\-\-ech " +(HTTPS) Specifies how to do ECH (Encrypted Client Hello). + +The values allowed for can be: +.RS +.IP false +Do not attempt ECH +.IP grease +Send a GREASE ECH extension +.IP true +Attempt ECH if possible, but do not fail if ECH is not attempted. +(The connection fails if ECH is attempted but fails.) +.IP hard +Attempt ECH and fail if that is not possible. +ECH only works with TLS 1.3 and also requires using +DoH or providing an ECHConfigList on the command line. +.IP ecl: +A base64 encoded ECHConfigList that is used for ECH. +.IP pn: +A name to use to over\-ride the "public_name" field of an ECHConfigList +(only available with OpenSSL TLS support) +.IP Errors +Most errors cause error +\fICURLE_ECH_REQUIRED\fP (101). +.RE +.IP + +If --ech is provided several times, the last set value is used. + +Example: +.nf + curl --ech true https://example.com +.fi + +See also \fI\-\-doh\-url\fP. Added in 8.8.0. +.IP "\-\-egd\-file " +(TLS) Deprecated option (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 the Entropy Gathering Daemon socket. The socket is +used to seed the random engine for SSL connections. + +If --egd-file is provided several times, the last set value is used. + +Example: +.nf + curl --egd-file /random/here https://example.com +.fi + +See also \fI\-\-random\-file\fP. +.IP "\-\-engine " +(TLS) Select the OpenSSL crypto engine to use for cipher operations. Use \fI\-\-engine\fP +list to print a list of build\-time supported engines. Note that not all (and +possibly none) of the engines may be available at runtime. + +If --engine is provided several times, the last set value is used. + +Example: +.nf + curl --engine flavor https://example.com +.fi + +See also \fI\-\-ciphers\fP and \fI\-\-curves\fP. +.IP "\-\-etag\-compare " +(HTTP) Make a conditional HTTP request for the specific ETag read from the given file +by sending a custom If\-None\-Match header using the stored ETag. + +For correct results, make sure that the specified file contains only a single +line with the desired ETag. An empty file is parsed as an empty ETag. + +Use the option \fI\-\-etag\-save\fP to first save the ETag from a response, and then +use this option to compare against the saved ETag in a subsequent request. + +If --etag-compare is provided several times, the last set value is used. + +Example: +.nf + curl --etag-compare etag.txt https://example.com +.fi + +See also \fI\-\-etag\-save\fP and \fI-z, \-\-time\-cond\fP. Added in 7.68.0. +.IP "\-\-etag\-save " +(HTTP) Save an HTTP ETag to the specified file. An ETag is a caching related header, +usually returned in a response. + +If no ETag is sent by the server, an empty file is created. + +If --etag-save is provided several times, the last set value is used. + +Example: +.nf + curl --etag-save storetag.txt https://example.com +.fi + +See also \fI\-\-etag\-compare\fP. Added in 7.68.0. +.IP "\-\-expect100\-timeout " +(HTTP) 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 waits one second. This option accepts decimal values. When curl +stops waiting, it continues as if a response was 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. + +If --expect100-timeout is provided several times, the last set value is used. + +Example: +.nf + curl --expect100-timeout 2.5 -T file https://example.com +.fi + +See also \fI\-\-connect\-timeout\fP. +.IP "\-f, \-\-fail" +(HTTP) 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 command line option +prevents curl from outputting that and return error 22. + +This method is not fail\-safe and there are occasions where non\-successful +response codes slip through, especially when authentication is involved +(response codes 401 and 407). + +Providing --fail multiple times has no extra effect. +Disable it again with \-\-no-fail. + +Example: +.nf + curl --fail https://example.com +.fi + +See also \fI\-\-fail\-with\-body\fP and \fI\-\-fail\-early\fP. This option is mutually exclusive to \fI\-\-fail\-with\-body\fP. +.IP "\-\-fail\-early" +Fail and exit on the first detected transfer error. + +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\(aqs success determines the error code curl +returns. Early failures are "hidden" by subsequent successful transfers. + +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 \fI\-f, \-\-fail\fP, which causes transfers to fail due to the +server\(aqs HTTP status code. You can combine the two options, however note \fI\-f, \-\-fail\fP +is not global and is therefore contained by \fI\-:, \-\-next\fP. + +This option is global and does not need to be specified for each use of --next. + +Providing --fail-early multiple times has no extra effect. +Disable it again with \-\-no-fail-early. + +Example: +.nf + curl --fail-early https://example.com https://two.example +.fi + +See also \fI-f, \-\-fail\fP and \fI\-\-fail\-with\-body\fP. Added in 7.52.0. +.IP "\-\-fail\-with\-body" +(HTTP) 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 option allows curl to output and save that content but also to return +error 22. + +This is an alternative option to \fI\-f, \-\-fail\fP which makes curl fail for the same +circumstances but without saving the content. + +Providing --fail-with-body multiple times has no extra effect. +Disable it again with \-\-no-fail-with-body. + +Example: +.nf + curl --fail-with-body https://example.com +.fi + +See also \fI-f, \-\-fail\fP and \fI\-\-fail\-early\fP. This option is mutually exclusive to \fI-f, \-\-fail\fP. Added in 7.76.0. +.IP "\-\-false\-start" +(TLS) Use false start during the TLS handshake. False start is a mode where a TLS +client starts sending application data before verifying the server\(aqs Finished +message, thus saving a round trip when performing a full handshake. + +This functionality is currently only implemented in the Secure Transport (on +iOS 7.0 or later, or OS X 10.9 or later) backend. + +Providing --false-start multiple times has no extra effect. +Disable it again with \-\-no-false-start. + +Example: +.nf + curl --false-start https://example.com +.fi + +See also \fI\-\-tcp\-fastopen\fP. +.IP "\-F, \-\-form " +(HTTP SMTP IMAP) For the HTTP protocol family, emulate a filled\-in form in which a user has +pressed the submit button. This makes curl POST data using the Content\-Type +multipart/form\-data according to RFC 2388. + +For SMTP and IMAP protocols, this composes a multipart mail message to +transmit. + +This enables uploading of binary files etc. To force the \(aqcontent\(aq part to be +a file, prefix the filename with an @ sign. To just get the content part from +a file, prefix the filename with the symbol <. The difference between @ and +< is then that @ makes a file get attached in the post as a file upload, +while the < makes a text field and just get the contents for that text field +from a file. + +Read content from stdin instead of a file by using a single "\-" 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\(aqs 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 \(aqprofile\(aq is the name of the +form\-field to which the file \fBportrait.jpg\fP is the input: +.nf + +curl \-F profile=@portrait.jpg https://example.com/upload.cgi +.fi + +Example: send your name and shoe size in two text fields to the server: +.nf + +curl \-F name=John \-F shoesize=11 https://example.com/ +.fi + +Example: send your essay in a text field to the server. Send it as a plain +text field, but get the contents for it from a local file: +.nf + +curl \-F "story=HTML message;type=text/html\(aq \\ + \-F \(aq=)\(aq \-F \(aq=@textfile.txt\(aq ... smtp://example.com +.fi + +Data can be encoded for transfer using encoder=. Available encodings are +\fIbinary\fP and \fI8bit\fP that do nothing else than adding the corresponding +Content\-Transfer\-Encoding header, \fI7bit\fP that only rejects 8\-bit characters +with a transfer error, \fIquoted\-printable\fP and \fIbase64\fP that encodes data +according to the corresponding schemes, limiting lines length to 76 +characters. + +Example: send multipart mail with a quoted\-printable text message and a +base64 attached file: +.nf + +curl \-F \(aq=text message;encoder=quoted\-printable\(aq \\ + \-F \(aq=@localfile;encoder=base64\(aq ... smtp://example.com +.fi + +See further examples and details in the MANUAL. + +--form can be used several times in a command line + +Example: +.nf + curl --form "name=curl" --form "file=@loadthis" https://example.com +.fi + +See also \fI-d, \-\-data\fP, \fI\-\-form\-string\fP and \fI\-\-form\-escape\fP. This option is mutually exclusive to \fI-d, \-\-data\fP and \fI-I, \-\-head\fP and \fI-T, \-\-upload\-file\fP. +.IP "\-\-form\-escape" +(HTTP) Pass on names of multipart form fields and files using backslash\-escaping +instead of percent\-encoding. + +If --form-escape is provided several times, the last set value is used. + +Example: +.nf + curl --form-escape -F 'field\\name=curl' -F 'file=@load"this' https://example.com +.fi + +See also \fI-F, \-\-form\fP. Added in 7.81.0. +.IP "\-\-form\-string " +(HTTP SMTP IMAP) Similar to \fI\-F, \-\-form\fP except that the value string for the named parameter is used +literally. Leading @ and < characters, and the ";type=" string in the value +have no special meaning. Use this in preference to \fI\-F, \-\-form\fP if there is any +possibility that the string value may accidentally trigger the @ or < +features of \fI\-F, \-\-form\fP. + +--form-string can be used several times in a command line + +Example: +.nf + curl --form-string "name=data" https://example.com +.fi + +See also \fI-F, \-\-form\fP. +.IP "\-\-ftp\-account " +(FTP) When an FTP server asks for "account data" after username and password has +been provided, this data is sent off using the ACCT command. + +If --ftp-account is provided several times, the last set value is used. + +Example: +.nf + curl --ftp-account "mr.robot" ftp://example.com/ +.fi + +See also \fI-u, \-\-user\fP. +.IP "\-\-ftp\-alternative\-to\-user " +(FTP) If authenticating with the USER and PASS commands fails, send this command. +When connecting to Tumbleweed\(aqs Secure Transport server over FTPS using a +client certificate, using "SITE AUTH" tells the server to retrieve the +username from the certificate. + +If --ftp-alternative-to-user is provided several times, the last set value is used. + +Example: +.nf + curl --ftp-alternative-to-user "U53r" ftp://example.com +.fi + +See also \fI\-\-ftp\-account\fP and \fI-u, \-\-user\fP. +.IP "\-\-ftp\-create\-dirs" +(FTP SFTP) 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 +instead attempts to create missing directories. + +Providing --ftp-create-dirs multiple times has no extra effect. +Disable it again with \-\-no-ftp-create-dirs. + +Example: +.nf + curl --ftp-create-dirs -T file ftp://example.com/remote/path/file +.fi + +See also \fI\-\-create\-dirs\fP. +.IP "\-\-ftp\-method " +(FTP) Control what method curl should use to reach a file on an FTP(S) +server. The method argument should be one of the following alternatives: +.RS +.IP multicwd +Do a single CWD operation for each path part in the given URL. For deep +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 +Do no CWD at all. curl does SIZE, RETR, STOR etc and gives the full path to +the server for each of these commands. This is the fastest behavior. +.IP singlecwd +Do one CWD with the full target directory and then operate on the file +\&"normally" (like in the multicwd case). This is somewhat more standards +compliant than "nocwd" but without the full penalty of "multicwd". +.RE +.IP + +If --ftp-method is provided several times, the last set value is used. + +Examples: +.nf + curl --ftp-method multicwd ftp://example.com/dir1/dir2/file + curl --ftp-method nocwd ftp://example.com/dir1/dir2/file + curl --ftp-method singlecwd ftp://example.com/dir1/dir2/file +.fi + +See also \fI-l, \-\-list\-only\fP. +.IP "\-\-ftp\-pasv" +(FTP) Use passive mode for the data connection. Passive is the internal default +behavior, but using this option can be used to override a previous \fI\-P, \-\-ftp\-port\fP +option. + +Reversing an enforced passive really is not doable but you must then instead +enforce the correct \fI\-P, \-\-ftp\-port\fP again. + +Passive mode means that curl tries the EPSV command first and then PASV, +unless \fI\-\-disable\-epsv\fP is used. + +Providing --ftp-pasv multiple times has no extra effect. +Disable it again with \-\-no-ftp-pasv. + +Example: +.nf + curl --ftp-pasv ftp://example.com/ +.fi + +See also \fI\-\-disable\-epsv\fP. +.IP "\-P, \-\-ftp\-port
" +(FTP) Reverses the default initiator/listener roles when connecting with FTP. This +option makes curl use active mode. curl then commands the server to connect +back to the client\(aqs specified address and port, while passive mode asks the +server to setup an IP address and port for it to connect to.
+should be one of: +.RS +.IP interface +e.g. \fBeth0\fP to specify which interface\(aqs IP address you want to use (Unix only) +.IP "IP address" +e.g. \fB192.168.10.1\fP to specify the exact IP address +.IP hostname +e.g. \fBmy.host.domain\fP to specify the machine +.IP - +make curl pick the same IP address that is already used for the control +connection. This is the recommended choice. +.RE +.IP +Disable the use of PORT with \fI\-\-ftp\-pasv\fP. Disable the attempt to use the EPRT +command instead of PORT by using \fI\-\-disable\-eprt\fP. EPRT is really PORT++. + +You can also append ":[start]\-[end]" to the right of the address, to tell +curl what TCP port range to use. That means you specify a port range, from a +lower to a higher number. A single number works as well, but do note that it +increases the risk of failure since the port may not be available. + + +If --ftp-port is provided several times, the last set value is used. + +Examples: +.nf + curl -P - ftp:/example.com + curl -P eth0 ftp:/example.com + curl -P 192.168.0.2 ftp:/example.com +.fi + +See also \fI\-\-ftp\-pasv\fP and \fI\-\-disable\-eprt\fP. +.IP "\-\-ftp\-pret" +(FTP) Send a PRET command before PASV (and EPSV). Certain FTP servers, mainly +drftpd, require this non\-standard command for directory listings as well as up +and downloads in PASV mode. + +Providing --ftp-pret multiple times has no extra effect. +Disable it again with \-\-no-ftp-pret. + +Example: +.nf + curl --ftp-pret ftp://example.com/ +.fi + +See also \fI-P, \-\-ftp\-port\fP and \fI\-\-ftp\-pasv\fP. +.IP "\-\-ftp\-skip\-pasv\-ip" +(FTP) Do not use the IP address the server suggests in its response to curl\(aqs 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). + +This option has no effect if PORT, EPRT or EPSV is used instead of PASV. + +Providing --ftp-skip-pasv-ip multiple times has no extra effect. +Disable it again with \-\-no-ftp-skip-pasv-ip. + +Example: +.nf + curl --ftp-skip-pasv-ip ftp://example.com/ +.fi + +See also \fI\-\-ftp\-pasv\fP. +.IP "\-\-ftp\-ssl\-ccc" +(FTP) Use CCC (Clear Command Channel) Shuts down the SSL/TLS layer after +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. + +Providing --ftp-ssl-ccc multiple times has no extra effect. +Disable it again with \-\-no-ftp-ssl-ccc. + +Example: +.nf + curl --ftp-ssl-ccc ftps://example.com/ +.fi + +See also \fI\-\-ssl\fP and \fI\-\-ftp\-ssl\-ccc\-mode\fP. +.IP "\-\-ftp\-ssl\-ccc\-mode " +(FTP) 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. + +Providing --ftp-ssl-ccc-mode multiple times has no extra effect. +Disable it again with \-\-no-ftp-ssl-ccc-mode. + +Example: +.nf + curl --ftp-ssl-ccc-mode active --ftp-ssl-ccc ftps://example.com/ +.fi + +See also \fI\-\-ftp\-ssl\-ccc\fP. +.IP "\-\-ftp\-ssl\-control" +(FTP) Require SSL/TLS for the FTP login, clear for transfer. Allows secure +authentication, but non\-encrypted data transfers for efficiency. Fails the +transfer if the server does not support SSL/TLS. + +Providing --ftp-ssl-control multiple times has no extra effect. +Disable it again with \-\-no-ftp-ssl-control. + +Example: +.nf + curl --ftp-ssl-control ftp://example.com +.fi + +See also \fI\-\-ssl\fP. +.IP "\-G, \-\-get" +(HTTP) When used, this option makes all data specified with \fI\-d, \-\-data\fP, \fI\-\-data\-binary\fP +or \fI\-\-data\-urlencode\fP to be used in an HTTP GET request instead of the POST +request that otherwise would be used. The data is appended to the URL +with a \(aq?\(aq separator. + +If used in combination with \fI\-I, \-\-head\fP, the POST data is instead appended to the +URL with a HEAD request. + +Providing --get multiple times has no extra effect. +Disable it again with \-\-no-get. + +Examples: +.nf + curl --get https://example.com + curl --get -d "tool=curl" -d "age=old" https://example.com + curl --get -I -d "tool=curl" https://example.com +.fi + +See also \fI-d, \-\-data\fP and \fI-X, \-\-request\fP. +.IP "\-g, \-\-globoff" +Switch off the URL globbing function. When you set this option, you can +specify URLs that contain the letters {}[] without having curl itself +interpret them. Note that these letters are not normal legal URL contents but +they should be encoded according to the URI standard. + +Providing --globoff multiple times has no extra effect. +Disable it again with \-\-no-globoff. + +Example: +.nf + curl -g "https://example.com/{[]}}}}" +.fi + +See also \fI-K, \-\-config\fP and \fI-q, \-\-disable\fP. +.IP "\-\-happy\-eyeballs\-timeout\-ms " +Happy Eyeballs is an algorithm that attempts to connect to both IPv4 and IPv6 +addresses for dual\-stack hosts, giving IPv6 a head\-start of the specified +number of milliseconds. If the IPv6 address cannot be connected to within that +time, then a connection attempt is made to the IPv4 address in parallel. The +first connection to be established is the one that is used. + +The range of suggested useful values is limited. Happy Eyeballs RFC 6555 says +\&"It is RECOMMENDED that connection attempts be paced 150\-250 ms apart to +balance human factors against network load." libcurl currently defaults to +200 ms. Firefox and Chrome currently default to 300 ms. + +If --happy-eyeballs-timeout-ms is provided several times, the last set value is used. + +Example: +.nf + curl --happy-eyeballs-timeout-ms 500 https://example.com +.fi + +See also \fI-m, \-\-max\-time\fP and \fI\-\-connect\-timeout\fP. Added in 7.59.0. +.IP "\-\-haproxy\-clientip " +(HTTP) Sets a client IP in HAProxy PROXY protocol v1 header at the beginning of the +connection. + +For valid requests, IPv4 addresses must be indicated as a series of exactly +4 integers in the range [0..255] inclusive written in decimal representation +separated by exactly one dot between each other. Heading zeroes are not +permitted in front of numbers in order to avoid any possible confusion +with octal numbers. IPv6 addresses must be indicated as series of 4 hexadecimal +digits (upper or lower case) delimited by colons between each other, with the +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 get sent. + +It replaces \fI\-\-haproxy\-protocol\fP if used, it is not necessary to specify both flags. + +If --haproxy-clientip is provided several times, the last set value is used. + +Example: +.nf + curl --haproxy-clientip $IP +.fi + +See also \fI-x, \-\-proxy\fP. Added in 8.2.0. +.IP "\-\-haproxy\-protocol" +(HTTP) Send a HAProxy PROXY protocol v1 header at the beginning of the connection. +This is used by some load balancers and reverse proxies to indicate the +client\(aqs true IP address and port. + +This option is primarily useful when sending test requests to a service that +expects this header. + +Providing --haproxy-protocol multiple times has no extra effect. +Disable it again with \-\-no-haproxy-protocol. + +Example: +.nf + curl --haproxy-protocol https://example.com +.fi + +See also \fI-x, \-\-proxy\fP. Added in 7.60.0. +.IP "\-I, \-\-head" +(HTTP FTP FILE) Fetch the headers only! HTTP\-servers feature the command HEAD which this uses +to get nothing but the header of a document. When used on an FTP or FILE file, +curl displays the file size and last modification time only. + +Providing --head multiple times has no extra effect. +Disable it again with \-\-no-head. + +Example: +.nf + curl -I https://example.com +.fi + +See also \fI-G, \-\-get\fP, \fI-v, \-\-verbose\fP and \fI\-\-trace\-ascii\fP. +.IP "\-H, \-\-header
" +(HTTP IMAP SMTP) Extra header to include in information sent. When used within an HTTP request, +it is added to the regular request headers. + +For an IMAP or SMTP MIME uploaded mail built with \fI\-F, \-\-form\fP options, it is +prepended to the resulting MIME document, effectively including it at the mail +global level. It does not affect raw uploaded mails (Added in 7.56.0). + +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 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 \fBnot\fP add that as a part of the header +content: do not add newlines or carriage returns, they only mess things up for +you. curl passes on the verbatim string you give it without any filter or +other safe guards. That includes white space and control characters. + +This option can take an argument in @filename style, which then adds a header +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:" +among others and should be added with this option. + +You need \fI\-\-proxy\-header\fP to send custom headers intended for an HTTP +proxy. Added in 7.37.0. + +Passing on a "Transfer\-Encoding: chunked" header when doing an HTTP request +with a request body, makes curl send the data using chunked encoding. + +\fBWARNING\fP: headers set with this option are set in all HTTP requests \- even +after redirects are followed, like when told with \fI\-L, \-\-location\fP. 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. + +--header can be used several times in a command line + +Examples: +.nf + curl -H "X-First-Name: Joe" https://example.com + curl -H "User-Agent: yes-please/2000" https://example.com + curl -H "Host:" https://example.com + curl -H @headers.txt https://example.com +.fi + +See also \fI-A, \-\-user\-agent\fP and \fI-e, \-\-referer\fP. +.IP "\-h, \-\-help " +Usage help. List all curl command line options within the given \fBcategory\fP. + +If no argument is provided, curl displays the most important command line +arguments. + +For category \fBall\fP, curl displays help for all options. + +If \fBcategory\fP is specified, curl displays all available help categories. + +Example: +.nf + curl --help all +.fi + +See also \fI-v, \-\-verbose\fP. +.IP "\-\-hostpubmd5 " +(SFTP SCP) Pass a string containing 32 hexadecimal digits. The string should be the 128 +bit \fBMD5\fP checksum of the remote host\(aqs public key, curl refuses the +connection with the host unless the checksums match. + +If --hostpubmd5 is provided several times, the last set value is used. + +Example: +.nf + curl --hostpubmd5 e5c1c49020640a5ab0f2034854c321a8 sftp://example.com/ +.fi + +See also \fI\-\-hostpubsha256\fP. +.IP "\-\-hostpubsha256 " +(SFTP SCP) Pass a string containing a Base64\-encoded SHA256 hash of the remote host\(aqs +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. + +If --hostpubsha256 is provided several times, the last set value is used. + +Example: +.nf + curl --hostpubsha256 NDVkMTQxMGQ1ODdmMjQ3MjczYjAyOTY5MmRkMjVmNDQ= sftp://example.com/ +.fi + +See also \fI\-\-hostpubmd5\fP. Added in 7.80.0. +.IP "\-\-hsts " +(HTTPS) Enable HSTS for the transfer. If the filename points to an existing HSTS cache +file, that is used. After a completed transfer, the cache is saved to the +filename again if it has been modified. + +If curl is told to use HTTP:// for a transfer involving a hostname that exists +in the HSTS cache, it upgrades the transfer to use HTTPS. Each HSTS cache +entry has an individual life time after which the upgrade is no longer +performed. + +Specify a "" filename (zero length) to avoid loading/saving and make curl just +handle HSTS in memory. + +If this option is used several times, curl loads contents from all the +files but the last one is used for saving. + +--hsts can be used several times in a command line + +Example: +.nf + curl --hsts cache.txt https://example.com +.fi + +See also \fI\-\-proto\fP. Added in 7.74.0. +.IP "\-\-http0.9" +(HTTP) Accept an 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 simply +transparently downgrades \- if allowed. + +HTTP/0.9 is disabled by default (added in 7.66.0) + +Providing --http0.9 multiple times has no extra effect. +Disable it again with \-\-no-http0.9. + +Example: +.nf + curl --http0.9 https://example.com +.fi + +See also \fI\-\-http1.1\fP, \fI\-\-http2\fP and \fI\-\-http3\fP. Added in 7.64.0. +.IP "\-0, \-\-http1.0" +(HTTP) Use HTTP version 1.0 instead of using its internally preferred HTTP version. + +Providing --http1.0 multiple times has no extra effect. + +Example: +.nf + curl --http1.0 https://example.com +.fi + +See also \fI\-\-http0.9\fP and \fI\-\-http1.1\fP. This option is mutually exclusive to \fI\-\-http1.1\fP and \fI\-\-http2\fP and \fI\-\-http2\-prior\-knowledge\fP and \fI\-\-http3\fP. +.IP "\-\-http1.1" +(HTTP) Use HTTP version 1.1. This is the default with HTTP:// URLs. + +Providing --http1.1 multiple times has no extra effect. + +Example: +.nf + curl --http1.1 https://example.com +.fi + +See also \fI\-\-http1.0\fP and \fI\-\-http0.9\fP. This option is mutually exclusive to \fI\-\-http1.0\fP and \fI\-\-http2\fP and \fI\-\-http2\-prior\-knowledge\fP and \fI\-\-http3\fP. +.IP "\-\-http2" +(HTTP) Use HTTP/2. + +For HTTPS, this means curl negotiates HTTP/2 in the TLS handshake. curl does +this by default. + +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 +version requirement with \fI\-\-tlsv1.2\fP. + +Providing --http2 multiple times has no extra effect. + +Example: +.nf + curl --http2 https://example.com +.fi + +See also \fI\-\-http1.1\fP, \fI\-\-http3\fP and \fI\-\-no\-alpn\fP. \fI\-\-http2\fP requires that the underlying libcurl was built to support HTTP/2. This option is mutually exclusive to \fI\-\-http1.1\fP and \fI\-\-http1.0\fP and \fI\-\-http2\-prior\-knowledge\fP and \fI\-\-http3\fP. +.IP "\-\-http2\-prior\-knowledge" +(HTTP) Issue a non\-TLS HTTP requests using HTTP/2 directly without HTTP/1.1 Upgrade. +It requires prior knowledge that the server supports HTTP/2 straight away. +HTTPS requests still do HTTP/2 the standard way with negotiated protocol +version in the TLS handshake. + +Providing --http2-prior-knowledge multiple times has no extra effect. +Disable it again with \-\-no-http2-prior-knowledge. + +Example: +.nf + curl --http2-prior-knowledge https://example.com +.fi + +See also \fI\-\-http2\fP and \fI\-\-http3\fP. \fI\-\-http2\-prior\-knowledge\fP requires that the underlying libcurl was built to support HTTP/2. This option is mutually exclusive to \fI\-\-http1.1\fP and \fI\-\-http1.0\fP and \fI\-\-http2\fP and \fI\-\-http3\fP. +.IP "\-\-http3" +(HTTP) Attempt HTTP/3 to the host in the URL, but fallback to earlier HTTP versions +if the HTTP/3 connection establishment fails. HTTP/3 is only available for +HTTPS and not for HTTP URLs. + +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 issues a separate attempt to use older HTTP +versions with a slight delay, so if the HTTP/3 transfer fails or is slow, curl +still tries to proceed with an older HTTP version. + +Use \fI\-\-http3\-only\fP for similar functionality \fIwithout\fP a fallback. + +Providing --http3 multiple times has no extra effect. + +Example: +.nf + curl --http3 https://example.com +.fi + +See also \fI\-\-http1.1\fP and \fI\-\-http2\fP. \fI\-\-http3\fP requires that the underlying libcurl was built to support HTTP/3. This option is mutually exclusive to \fI\-\-http1.1\fP and \fI\-\-http1.0\fP and \fI\-\-http2\fP and \fI\-\-http2\-prior\-knowledge\fP and \fI\-\-http3\-only\fP. Added in 7.66.0. +.IP "\-\-http3\-only" +(HTTP) 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 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 makes curl fail if a QUIC connection cannot be established, it +does not attempt any other HTTP versions on its own. Use \fI\-\-http3\fP for similar +functionality \fIwith\fP a fallback. + +Providing --http3-only multiple times has no extra effect. + +Example: +.nf + curl --http3-only https://example.com +.fi + +See also \fI\-\-http1.1\fP, \fI\-\-http2\fP and \fI\-\-http3\fP. \fI\-\-http3\-only\fP requires that the underlying libcurl was built to support HTTP/3. This option is mutually exclusive to \fI\-\-http1.1\fP and \fI\-\-http1.0\fP and \fI\-\-http2\fP and \fI\-\-http2\-prior\-knowledge\fP and \fI\-\-http3\fP. Added in 7.88.0. +.IP "\-\-ignore\-content\-length" +(FTP HTTP) For HTTP, Ignore the Content\-Length header. This is particularly useful 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 +downloading a file. + +This option does not work for HTTP if libcurl was built to use hyper. + +Providing --ignore-content-length multiple times has no extra effect. +Disable it again with \-\-no-ignore-content-length. + +Example: +.nf + curl --ignore-content-length https://example.com +.fi + +See also \fI\-\-ftp\-skip\-pasv\-ip\fP. +.IP "\-i, \-\-include" +(HTTP FTP) Include response headers in the output. HTTP response headers can include +things like server name, cookies, date of the document, HTTP version and +more... With non\-HTTP protocols, the "headers" are other server communication. + +To view the request headers, consider the \fI\-v, \-\-verbose\fP option. + +Prior to 7.75.0 curl did not print the headers if \fI\-f, \-\-fail\fP was used in +combination with this option and there was error reported by server. + +Providing --include multiple times has no extra effect. +Disable it again with \-\-no-include. + +Example: +.nf + curl -i https://example.com +.fi + +See also \fI-v, \-\-verbose\fP. +.IP "\-k, \-\-insecure" +(TLS SFTP SCP) By default, every secure connection curl makes is verified to be secure before +the transfer takes place. This option makes curl skip the verification step +and proceed without checking. + +When this option is not used for protocols using TLS, curl verifies the +server\(aqs TLS certificate before it continues: that the certificate contains +the right name which matches the hostname used in the URL and that the +certificate has been signed by a CA certificate present in the cert store. See +this online resource for further details: +\fBhttps://curl.se/docs/sslcerts.html\fP + +For SFTP and SCP, this option makes curl skip the \fIknown_hosts\fP verification. +\fIknown_hosts\fP is a file normally stored in the user\(aqs home directory in the +\&".ssh" subdirectory, which contains hostnames and their public keys. + +\fBWARNING\fP: using this option makes the transfer insecure. + +When curl uses secure protocols it trusts responses and allows for example +HSTS and Alt\-Svc information to be stored and used subsequently. Using +\fI\-k, \-\-insecure\fP can make curl trust and use such information from malicious +servers. + +Providing --insecure multiple times has no extra effect. +Disable it again with \-\-no-insecure. + +Example: +.nf + curl --insecure https://example.com +.fi + +See also \fI\-\-proxy\-insecure\fP, \fI\-\-cacert\fP and \fI\-\-capath\fP. +.IP "\-\-interface " +Perform an operation using a specified interface. You can enter interface +name, IP address or hostname. An example could look like: +.nf + +curl \--interface eth0:1 https://www.example.com/ +.fi + +On Linux it can be used to specify a \fBVRF\fP, but the binary needs to either +have \fBCAP_NET_RAW\fP or to be run as root. More information about Linux +\fBVRF\fP: https://www.kernel.org/doc/Documentation/networking/vrf.txt + +If --interface is provided several times, the last set value is used. + +Example: +.nf + curl --interface eth0 https://example.com +.fi + +See also \fI\-\-dns\-interface\fP. +.IP "\-\-ipfs\-gateway " +(IPFS) Specify which gateway to use for IPFS and IPNS URLs. Not specifying this +instead makes curl check if the IPFS_GATEWAY environment variable is set, or +if a "~/.ipfs/gateway" file holding the gateway URL exists. + +If you run a local IPFS node, this gateway is by default available under +\&"http://localhost:8080". A full example URL would look like: +.nf + +curl \--ipfs\-gateway http://localhost:8080 ipfs://bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi +.fi + +There are many public IPFS gateways. See for example: +https://ipfs.github.io/public\-gateway\-checker/ + +If you opt to go for a remote gateway you need to be aware that you completely +trust the gateway. This might be fine in local gateways that you host +yourself. With remote gateways there could potentially be malicious actors +returning you data that does not match the request you made, inspect or even +interfere with the request. You may not notice this when using curl. A +mitigation could be to go for a "trustless" gateway. This means you locally +verify that the data. Consult the docs page on trusted vs trustless: +https://docs.ipfs.tech/reference/http/gateway/#trusted\-vs\-trustless + +If --ipfs-gateway is provided several times, the last set value is used. + +Example: +.nf + curl --ipfs-gateway https://example.com ipfs:// +.fi + +See also \fI-h, \-\-help\fP and \fI-M, \-\-manual\fP. Added in 8.4.0. +.IP "\-4, \-\-ipv4" +Use IPv4 addresses only when resolving hostnames, and not for example try +IPv6. + +Providing --ipv4 multiple times has no extra effect. + +Example: +.nf + curl --ipv4 https://example.com +.fi + +See also \fI\-\-http1.1\fP and \fI\-\-http2\fP. This option is mutually exclusive to \fI-6, \-\-ipv6\fP. +.IP "\-6, \-\-ipv6" +Use IPv6 addresses only when resolving hostnames, and not for example try +IPv4. + +Your resolver may respond to an IPv6\-only resolve request by returning IPv6 +addresses that contain "mapped" IPv4 addresses for compatibility purposes. +macOS is known to do this. + +Providing --ipv6 multiple times has no extra effect. + +Example: +.nf + curl --ipv6 https://example.com +.fi + +See also \fI\-\-http1.1\fP and \fI\-\-http2\fP. This option is mutually exclusive to \fI-4, \-\-ipv4\fP. +.IP "\-\-json " +(HTTP) Sends the specified JSON data in a POST request to the HTTP server. \fI\-\-json\fP +works as a shortcut for passing on these three options: +.nf + +-\-data [arg] +-\-header "Content\-Type: application/json" +-\-header "Accept: application/json" +.fi + +There is \fBno verification\fP that the passed in data is actual JSON or that +the syntax is correct. + +If you start the data with the letter @, the rest should be a filename to read +the data from, or a single dash (\-) if you want curl to read the data from +stdin. Posting data from a file named \(aqfoobar\(aq would thus be done with \fI\-\-json\fP +@foobar and to instead read the data from stdin, use \fI\-\-json\fP @\-. + +If this option is used more than once on the same command line, the additional +data pieces are concatenated to the previous before sending. + +The headers this option sets can be overridden with \fI\-H, \-\-header\fP as usual. + +--json can be used several times in a command line + +Examples: +.nf + curl --json '{ "drink": "coffe" }' https://example.com + curl --json '{ "drink":' --json ' "coffe" }' https://example.com + curl --json @prepared https://example.com + curl --json @- https://example.com < json.txt +.fi + +See also \fI\-\-data\-binary\fP and \fI\-\-data\-raw\fP. This option is mutually exclusive to \fI-F, \-\-form\fP and \fI-I, \-\-head\fP and \fI-T, \-\-upload\-file\fP. Added in 7.82.0. +.IP "\-j, \-\-junk\-session\-cookies" +(HTTP) 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. + +Providing --junk-session-cookies multiple times has no extra effect. +Disable it again with \-\-no-junk-session-cookies. + +Example: +.nf + curl --junk-session-cookies -b cookies.txt https://example.com +.fi + +See also \fI-b, \-\-cookie\fP and \fI-c, \-\-cookie\-jar\fP. +.IP "\-\-keepalive\-time " +Set the time a connection needs to remain idle before sending keepalive probes +and the time between individual keepalive probes. It is currently effective on +operating systems offering the "TCP_KEEPIDLE" and "TCP_KEEPINTVL" socket +options (meaning Linux, recent AIX, HP\-UX and more). Keepalive is used by the +TCP stack to detect broken networks on idle connections. The number of missed +keepalive probes before declaring the connection down is OS dependent and is +commonly 9 or 10. This option has no effect if \fI\-\-no\-keepalive\fP is used. + +If unspecified, the option defaults to 60 seconds. + +If --keepalive-time is provided several times, the last set value is used. + +Example: +.nf + curl --keepalive-time 20 https://example.com +.fi + +See also \fI\-\-no\-keepalive\fP and \fI-m, \-\-max\-time\fP. +.IP "\-\-key " +(TLS SSH) Private key filename. Allows you to provide your private key in this separate +file. For SSH, if not specified, curl tries the following candidates in order: +\&"~/.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:" is interpreted as a +PKCS#11 URI. If a PKCS#11 URI is provided, then the \fI\-\-engine\fP option is set as +\&"pkcs11" if none was provided and the \fI\-\-key\-type\fP 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 +to be already present in the keychain or PKCS#12 file containing the +certificate. + +If --key is provided several times, the last set value is used. + +Example: +.nf + curl --cert certificate --key here https://example.com +.fi + +See also \fI\-\-key\-type\fP and \fI-E, \-\-cert\fP. +.IP "\-\-key\-type " +(TLS) Private key file type. Specify which type your \fI\-\-key\fP provided private key +is. DER, PEM, and ENG are supported. If not specified, PEM is assumed. + +If --key-type is provided several times, the last set value is used. + +Example: +.nf + curl --key-type DER --key here https://example.com +.fi + +See also \fI\-\-key\fP. +.IP "\-\-krb " +(FTP) Enable Kerberos authentication and use. The level must be entered and should +be one of \(aqclear\(aq, \(aqsafe\(aq, \(aqconfidential\(aq, or \(aqprivate\(aq. Should you use a +level that is not one of these, \(aqprivate\(aq is used. + +If --krb is provided several times, the last set value is used. + +Example: +.nf + curl --krb clear ftp://example.com/ +.fi + +See also \fI\-\-delegation\fP and \fI\-\-ssl\fP. \fI\-\-krb\fP requires that the underlying libcurl was built to support Kerberos. +.IP "\-\-libcurl " +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! + +This option is global and does not need to be specified for each use of --next. + +If --libcurl is provided several times, the last set value is used. + +Example: +.nf + curl --libcurl client.c https://example.com +.fi + +See also \fI-v, \-\-verbose\fP. +.IP "\-\-limit\-rate " +Specify the maximum transfer rate you want curl to use \- for both downloads +and uploads. This feature is useful if you have a limited pipe and you would +like your transfer not to use your entire bandwidth. To make it slower than it +otherwise would be. + +The given speed is measured in bytes/second, unless a suffix is appended. +Appending \(aqk\(aq or \(aqK\(aq counts the number as kilobytes, \(aqm\(aq or \(aqM\(aq makes it +megabytes, while \(aqg\(aq or \(aqG\(aq 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 \fI\-Y, \-\-speed\-limit\fP option, that option takes precedence and +might cripple the rate\-limiting slightly, to help keeping the speed\-limit +logic working. + +If --limit-rate is provided several times, the last set value is used. + +Examples: +.nf + curl --limit-rate 100K https://example.com + curl --limit-rate 1000 https://example.com + curl --limit-rate 10M https://example.com +.fi + +See also \fI\-\-rate\fP, \fI-Y, \-\-speed\-limit\fP and \fI-y, \-\-speed\-time\fP. +.IP "\-l, \-\-list\-only" +(FTP POP3 SFTP FILE) When listing an FTP directory, force a name\-only view. Maybe particularly +useful if the user wants to machine\-parse the contents of an FTP directory +since the normal directory view does not use a standard look or format. When +used like this, the option causes an NLST command to be sent to the server +instead of LIST. + +Note: Some FTP servers list only files in their response to NLST; they do not +include sub\-directories and symbolic links. + +When listing an SFTP directory, this switch forces a name\-only view, one per +line. This is especially useful if the user wants to machine\-parse the +contents of an SFTP directory since the normal directory view provides more +information than just filenames. + +When retrieving a specific email from POP3, this switch forces a LIST command +to be performed instead of RETR. This is particularly useful if the user wants +to see if a specific message\-id exists on the server and what size it is. + +For FILE, this option has no effect yet as directories are always listed in +this mode. + +Note: When combined with \fI\-X, \-\-request\fP, this option can be used to send a UIDL +command instead, so the user may use the email\(aqs unique identifier rather than +its message\-id to make the request. + +Providing --list-only multiple times has no extra effect. +Disable it again with \-\-no-list-only. + +Example: +.nf + curl --list-only ftp://example.com/dir/ +.fi + +See also \fI-Q, \-\-quote\fP and \fI-X, \-\-request\fP. +.IP "\-\-local\-port " +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 +so setting this range to something too narrow might cause unnecessary +connection setup failures. + +If --local-port is provided several times, the last set value is used. + +Example: +.nf + curl --local-port 1000-3000 https://example.com +.fi + +See also \fI-g, \-\-globoff\fP. +.IP "\-L, \-\-location" +(HTTP) 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 makes curl redo the request on the new place. If used together with +\fI\-i, \-\-include\fP or \fI\-I, \-\-head\fP, headers from all requested pages are shown. + +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 \fI\-\-location\-trusted\fP on how to change this. + +Limit the amount of redirects to follow by using the \fI\-\-max\-redirs\fP 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 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: \fI\-\-post301\fP, \fI\-\-post302\fP and \fI\-\-post303\fP. + +The method set with \fI\-X, \-\-request\fP overrides the method curl would otherwise select +to use. + +Providing --location multiple times has no extra effect. +Disable it again with \-\-no-location. + +Example: +.nf + curl -L https://example.com +.fi + +See also \fI\-\-resolve\fP and \fI\-\-alt\-svc\fP. +.IP "\-\-location\-trusted" +(HTTP) Like \fI\-L, \-\-location\fP, 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 clear\-text in the case of HTTP Basic authentication). + +Providing --location-trusted multiple times has no extra effect. +Disable it again with \-\-no-location-trusted. + +Example: +.nf + curl --location-trusted -u user:password https://example.com +.fi + +See also \fI-u, \-\-user\fP. +.IP "\-\-login\-options " +(IMAP LDAP POP3 SMTP) Specify the login options to use during server authentication. + +You can use login options to specify protocol specific options that may be +used during authentication. At present only IMAP, POP3 and SMTP support login +options. For more information about login options please see RFC 2384, +RFC 5092 and the IETF draft +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 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). + +If --login-options is provided several times, the last set value is used. + +Example: +.nf + curl --login-options 'AUTH=*' imap://example.com +.fi + +See also \fI-u, \-\-user\fP. +.IP "\-\-mail\-auth
" +(SMTP) Specify a single address. This is used to specify the authentication address +(identity) of a submitted message that is being relayed to another server. + +If --mail-auth is provided several times, the last set value is used. + +Example: +.nf + curl --mail-auth user@example.come -T mail smtp://example.com/ +.fi + +See also \fI\-\-mail\-rcpt\fP and \fI\-\-mail\-from\fP. +.IP "\-\-mail\-from
" +(SMTP) Specify a single address that the given mail should get sent from. + +If --mail-from is provided several times, the last set value is used. + +Example: +.nf + curl --mail-from user@example.com -T mail smtp://example.com/ +.fi + +See also \fI\-\-mail\-rcpt\fP and \fI\-\-mail\-auth\fP. +.IP "\-\-mail\-rcpt
" +(SMTP) Specify a single email address, username or mailing list name. Repeat this +option several times to send to multiple recipients. + +When performing an address verification (\fBVRFY\fP command), the recipient +should be specified as the username or username and domain (as per Section 3.5 +of RFC 5321). + +When performing a mailing list expand (EXPN command), the recipient should be +specified using the mailing list name, such as "Friends" or "London\-Office". + + +--mail-rcpt can be used several times in a command line + +Example: +.nf + curl --mail-rcpt user@example.net smtp://example.com +.fi + +See also \fI\-\-mail\-rcpt\-allowfails\fP. +.IP "\-\-mail\-rcpt\-allowfails" +(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 \fI\-\-mail\-rcpt\-allowfails\fP +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 +still aborts the SMTP conversation and returns the error received from to the +last RCPT TO command. + +Providing --mail-rcpt-allowfails multiple times has no extra effect. +Disable it again with \-\-no-mail-rcpt-allowfails. + +Example: +.nf + curl --mail-rcpt-allowfails --mail-rcpt dest@example.com smtp://example.com +.fi + +See also \fI\-\-mail\-rcpt\fP. Added in 7.69.0. +.IP "\-M, \-\-manual" +Manual. Display the huge help text. + +Example: +.nf + curl --manual +.fi + +See also \fI-v, \-\-verbose\fP, \fI\-\-libcurl\fP and \fI\-\-trace\fP. +.IP "\-\-max\-filesize " +(FTP HTTP MQTT) Specify the maximum size (in bytes) of a file to download. If the file +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 \(aqk\(aq or \(aqK\(aq counts the +number as kilobytes, \(aqm\(aq or \(aqM\(aq makes it megabytes, while \(aqg\(aq or \(aqG\(aq makes it +gigabytes. Examples: 200K, 3m and 1G. (Added in 7.58.0) + +\fBNOTE\fP: before curl 8.4.0, when the file size is not known prior to +download, for such files this option has no effect even if the file transfer +ends up being larger than this given limit. + +Starting with curl 8.4.0, this option aborts the transfer if it reaches the +threshold during transfer. + +If --max-filesize is provided several times, the last set value is used. + +Example: +.nf + curl --max-filesize 100K https://example.com +.fi + +See also \fI\-\-limit\-rate\fP. +.IP "\-\-max\-redirs " +(HTTP) Set maximum number of redirections to follow. When \fI\-L, \-\-location\fP is used, to +prevent curl from following too many redirects, by default, the limit is +set to 50 redirects. Set this option to \-1 to make it unlimited. + +If --max-redirs is provided several times, the last set value is used. + +Example: +.nf + curl --max-redirs 3 --location https://example.com +.fi + +See also \fI-L, \-\-location\fP. +.IP "\-m, \-\-max\-time " +Set maximum time in seconds that you allow each transfer to take. Prevents +your batch jobs from hanging for hours due to slow networks or links going +down. This option accepts decimal values. + +If you enable retrying the transfer (\fI\-\-retry\fP) then the maximum time counter is +reset each time the transfer is retried. You can use \fI\-\-retry\-max\-time\fP to limit +the retry time. + +The decimal value needs to provided using a dot (.) as decimal separator \- not +the local version even if it might be using another separator. + +If --max-time is provided several times, the last set value is used. + +Examples: +.nf + curl --max-time 10 https://example.com + curl --max-time 2.92 https://example.com +.fi + +See also \fI\-\-connect\-timeout\fP and \fI\-\-retry\-max\-time\fP. +.IP "\-\-metalink" +This option was previously used to specify a Metalink resource. Metalink +support is disabled in curl for security reasons (added in 7.78.0). + +If --metalink is provided several times, the last set value is used. + +Example: +.nf + curl --metalink file https://example.com +.fi + +See also \fI-Z, \-\-parallel\fP. +.IP "\-\-negotiate" +(HTTP) Enable Negotiate (SPNEGO) authentication. + +This option requires a library built with GSS\-API or SSPI support. Use +\fI\-V, \-\-version\fP to see if your curl supports GSS\-API/SSPI or SPNEGO. + +When using this option, you must also provide a fake \fI\-u, \-\-user\fP option to activate +the authentication code properly. Sending a \(aq\-u :\(aq is enough as the username +and password from the \fI\-u, \-\-user\fP option are not actually used. + +Providing --negotiate multiple times has no extra effect. + +Example: +.nf + curl --negotiate -u : https://example.com +.fi + +See also \fI\-\-basic\fP, \fI\-\-ntlm\fP, \fI\-\-anyauth\fP and \fI\-\-proxy\-negotiate\fP. +.IP "\-n, \-\-netrc" +Make curl scan the \fI.netrc\fP file in the user\(aqs home directory for login name +and password. This is typically used for FTP on Unix. If used with HTTP, curl +enables user authentication. See \fInetrc(5)\fP and \fIftp(1)\fP 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. + +On Windows two filenames in the home directory are checked: \fI.netrc\fP and +\fI_netrc\fP, preferring the former. Older versions on Windows checked for \fI_netrc\fP +only. + +A quick and simple example of how to setup a \fI.netrc\fP to allow curl to FTP to +the machine host.domain.com with username \(aqmyself\(aq and password \(aqsecret\(aq could +look similar to: +.nf + +machine host.domain.com +login myself +password secret + +Providing --netrc multiple times has no extra effect. +Disable it again with \-\-no-netrc. + +Example: +.nf + curl --netrc https://example.com +.fi + +See also \fI\-\-netrc\-file\fP, \fI-K, \-\-config\fP and \fI-u, \-\-user\fP. This option is mutually exclusive to \fI\-\-netrc\-file\fP and \fI\-\-netrc\-optional\fP. +.IP "\-\-netrc\-file " +Set the netrc file to use. Similar to \fI\-n, \-\-netrc\fP, except that you also provide +the path (absolute or relative). + +It abides by \fI\-\-netrc\-optional\fP if specified. + +If --netrc-file is provided several times, the last set value is used. + +Example: +.nf + curl --netrc-file netrc https://example.com +.fi + +See also \fI-n, \-\-netrc\fP, \fI-u, \-\-user\fP and \fI-K, \-\-config\fP. This option is mutually exclusive to \fI-n, \-\-netrc\fP. +.IP "\-\-netrc\-optional" +Similar to \fI\-n, \-\-netrc\fP, but this option makes the .netrc usage \fBoptional\fP +and not mandatory as the \fI\-n, \-\-netrc\fP option does. + +Providing --netrc-optional multiple times has no extra effect. +Disable it again with \-\-no-netrc-optional. + +Example: +.nf + curl --netrc-optional https://example.com +.fi + +See also \fI\-\-netrc\-file\fP. This option is mutually exclusive to \fI-n, \-\-netrc\fP. +.IP "\-:, \-\-next" +Use a separate operation for the following URL and associated options. This +allows you to send several URL requests, each with their own specific options, +for example, such as different usernames or custom requests for each. + +\fI\-:, \-\-next\fP resets all local options and only global ones have their values survive +over to the operation following the \fI\-:, \-\-next\fP instruction. Global options include +\fI\-v, \-\-verbose\fP, \fI\-\-trace\fP, \fI\-\-trace\-ascii\fP and \fI\-\-fail\-early\fP. + +For example, you can do both a GET and a POST in a single command line: +.nf + +curl www1.example.com \--next \-d postthis www2.example.com + +--next can be used several times in a command line + +Examples: +.nf + curl https://example.com --next -d postthis www2.example.com + curl -I https://example.com --next https://example.net/ +.fi + +See also \fI-Z, \-\-parallel\fP and \fI-K, \-\-config\fP. +.IP "\-\-no\-alpn" +(HTTPS) Disable the ALPN TLS extension. ALPN is enabled by default if libcurl was built +with an SSL library that supports ALPN. ALPN is used by a libcurl that supports +HTTP/2 to negotiate HTTP/2 support with the server during https sessions. + +Note that this is the negated option name documented. You can use \fI\-\-alpn\fP to +enable ALPN. + +Providing --no-alpn multiple times has no extra effect. +Disable it again with \-\-alpn. + +Example: +.nf + curl --no-alpn https://example.com +.fi + +See also \fI\-\-no\-npn\fP and \fI\-\-http2\fP. \fI\-\-no\-alpn\fP requires that the underlying libcurl was built to support TLS. +.IP "\-N, \-\-no\-buffer" +Disables the buffering of the output stream. In normal work situations, curl +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 \fI\-\-buffer\fP to +enable buffering again. + +Providing --no-buffer multiple times has no extra effect. +Disable it again with \-\-buffer. + +Example: +.nf + curl --no-buffer https://example.com +.fi + +See also \fI-#, \-\-progress\-bar\fP. +.IP "\-\-no\-clobber" +When used in conjunction with the \fI\-o, \-\-output\fP, \fI\-J, \-\-remote\-header\-name\fP, +\fI\-O, \-\-remote\-name\fP, or \fI\-\-remote\-name\-all\fP 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 does not +create any file. + +Note that this is the negated option name documented. You can thus use +\fI\-\-clobber\fP to enforce the clobbering, even if \fI\-J, \-\-remote\-header\-name\fP is +specified. + +Providing --no-clobber multiple times has no extra effect. +Disable it again with \-\-clobber. + +Example: +.nf + curl --no-clobber --output local/dir/file https://example.com +.fi + +See also \fI-o, \-\-output\fP and \fI-O, \-\-remote\-name\fP. Added in 7.83.0. +.IP "\-\-no\-keepalive" +Disables the use of keepalive messages on the TCP connection. curl otherwise +enables them by default. + +Note that this is the negated option name documented. You can thus use +\fI\-\-keepalive\fP to enforce keepalive. + +Providing --no-keepalive multiple times has no extra effect. +Disable it again with \-\-keepalive. + +Example: +.nf + curl --no-keepalive https://example.com +.fi + +See also \fI\-\-keepalive\-time\fP. +.IP "\-\-no\-npn" +(HTTPS) curl never uses NPN, this option has no effect (added in 7.86.0). + +Disable the NPN TLS extension. NPN is enabled by default if libcurl was built +with an SSL library that supports NPN. NPN is used by a libcurl that supports +HTTP/2 to negotiate HTTP/2 support with the server during https sessions. + +Providing --no-npn multiple times has no extra effect. +Disable it again with \-\-npn. + +Example: +.nf + curl --no-npn https://example.com +.fi + +See also \fI\-\-no\-alpn\fP and \fI\-\-http2\fP. \fI\-\-no\-npn\fP requires that the underlying libcurl was built to support TLS. +.IP "\-\-no\-progress\-meter" +Option to switch off the progress meter output without muting or otherwise +affecting warning and informational messages like \fI\-s, \-\-silent\fP does. + +Note that this is the negated option name documented. You can thus use +\fI\-\-progress\-meter\fP to enable the progress meter again. + +Providing --no-progress-meter multiple times has no extra effect. +Disable it again with \-\-progress-meter. + +Example: +.nf + curl --no-progress-meter -o store https://example.com +.fi + +See also \fI-v, \-\-verbose\fP and \fI-s, \-\-silent\fP. Added in 7.67.0. +.IP "\-\-no\-sessionid" +(TLS) Disable curl\(aqs use of SSL session\-ID caching. By default all transfers are +done using the cache. Note that while nothing should ever get hurt by +attempting to reuse SSL session\-IDs, there seem to be broken SSL +implementations in the wild that may require you to disable this in order for +you to succeed. + +Note that this is the negated option name documented. You can thus use +\fI\-\-sessionid\fP to enforce session\-ID caching. + +Providing --no-sessionid multiple times has no extra effect. +Disable it again with \-\-sessionid. + +Example: +.nf + curl --no-sessionid https://example.com +.fi + +See also \fI-k, \-\-insecure\fP. +.IP "\-\-noproxy " +Comma\-separated list of hosts for which not to use a proxy, if one is +specified. The only wildcard is a single "*" character, which matches all +hosts, and effectively disables the proxy. Each name in this list is matched +as either a domain which contains the hostname, or the hostname itself. For +example, "local.com" would match "local.com", "local.com:80", and +\&"www.local.com", but not "www.notlocal.com". + +This option overrides the environment variables that disable the proxy +("no_proxy" and "NO_PROXY") (added in 7.53.0). If there is an environment +variable disabling a proxy, you can set the no proxy list to "" to override +it. + +IP addresses specified to this option can be provided using CIDR notation +(added in 7.86.0): an appended slash and number specifies the number of +network bits out of the address to use in the comparison. For example +\&"192.168.0.0/16" would match all addresses starting with "192.168". + +If --noproxy is provided several times, the last set value is used. + +Example: +.nf + curl --noproxy "www.example" https://example.com +.fi + +See also \fI-x, \-\-proxy\fP. +.IP "\-\-ntlm" +(HTTP) Use NTLM authentication. The NTLM authentication method was designed by +Microsoft and is used by IIS web servers. It is a proprietary protocol, +reverse\-engineered by clever people and implemented in curl based on their +efforts. This kind of behavior should not be endorsed, you should encourage +everyone who uses NTLM to switch to a public and documented authentication +method instead, such as Digest. + +If you want to enable NTLM for your proxy authentication, then use +\fI\-\-proxy\-ntlm\fP. + +Providing --ntlm multiple times has no extra effect. + +Example: +.nf + curl --ntlm -u user:password https://example.com +.fi + +See also \fI\-\-proxy\-ntlm\fP. \fI\-\-ntlm\fP requires that the underlying libcurl was built to support TLS. This option is mutually exclusive to \fI\-\-basic\fP and \fI\-\-negotiate\fP and \fI\-\-digest\fP and \fI\-\-anyauth\fP. +.IP "\-\-ntlm\-wb" +(HTTP) Deprecated option (added in 8.8.0). + +Enabled NTLM much in the style \fI\-\-ntlm\fP does, but handed over the authentication +to a separate executable that was executed when needed. + +Providing --ntlm-wb multiple times has no extra effect. + +Example: +.nf + curl --ntlm-wb -u user:password https://example.com +.fi + +See also \fI\-\-ntlm\fP and \fI\-\-proxy\-ntlm\fP. +.IP "\-\-oauth2\-bearer " +(IMAP LDAP POP3 SMTP HTTP) Specify the Bearer Token for OAUTH 2.0 server authentication. The Bearer Token +is used in conjunction with the username which can be specified as part of the +\fI\-\-url\fP or \fI\-u, \-\-user\fP options. + +The Bearer Token and username are formatted according to RFC 6750. + +If --oauth2-bearer is provided several times, the last set value is used. + +Example: +.nf + curl --oauth2-bearer "mF_9.B5f-4.1JqM" https://example.com +.fi + +See also \fI\-\-basic\fP, \fI\-\-ntlm\fP and \fI\-\-digest\fP. +.IP "\-o, \-\-output " +Write output to the given file instead of stdout. If you are using globbing to +fetch multiple documents, you should quote the URL and you can use "#" +followed by a number in the filename. That variable is then replaced with the +current string for the URL being fetched. Like in: +.nf + +curl "http://{one,two}.example.com" \-o "file_#1.txt" +.fi + +or use several variables like: +.nf + +curl "http://{site,host}.host[1\-5].example" \-o "#1_#2" +.fi + +You may use this option as many times as the number of URLs you have. For +example, if you specify two URLs on the same command line, you can use it like +this: +.nf + +curl \-o aa example.com \-o bb example.net +.fi + +and the order of the \-o options and the URLs does not matter, just that the +first \-o is for the first URL and so on, so the above command line can also be +written as +.nf + +curl example.com example.net \-o aa \-o bb +.fi + +See also the \fI\-\-create\-dirs\fP option to create the local directories +dynamically. Specifying the output as \(aq\-\(aq (a single dash) passes the output to +stdout. + +To suppress response bodies, you can redirect output to /dev/null: +.nf + +curl example.com \-o /dev/null +.fi + +Or for Windows: +.nf + +curl example.com \-o nul +.fi + +Specify the filename as single minus to force the output to stdout, to +override curl\(aqs internal binary output in terminal prevention: +.nf + +curl https://example.com/jpeg \-o \- + +--output can be used several times in a command line + +Examples: +.nf + curl -o file https://example.com + curl "http://{one,two}.example.com" -o "file_#1.txt" + curl "http://{site,host}.host[1-5].example" -o "#1_#2" + curl -o file https://example.com -o file2 https://example.net +.fi + +See also \fI-O, \-\-remote\-name\fP, \fI\-\-remote\-name\-all\fP and \fI-J, \-\-remote\-header\-name\fP. +.IP "\-\-output\-dir " +Specify the directory in which files should be stored, when \fI\-O, \-\-remote\-name\fP or +\fI\-o, \-\-output\fP are used. + +The given output directory is used for all URLs and output options on the +command line, up until the first \fI\-:, \-\-next\fP. + +If the specified target directory does not exist, the operation fails unless +\fI\-\-create\-dirs\fP is also used. + +If --output-dir is provided several times, the last set value is used. + +Example: +.nf + curl --output-dir "tmp" -O https://example.com +.fi + +See also \fI-O, \-\-remote\-name\fP and \fI-J, \-\-remote\-header\-name\fP. Added in 7.73.0. +.IP "\-Z, \-\-parallel" +Makes curl perform its transfers in parallel as compared to the regular serial +manner. + +This option is global and does not need to be specified for each use of --next. + +Providing --parallel multiple times has no extra effect. +Disable it again with \-\-no-parallel. + +Example: +.nf + curl --parallel https://example.com -o file1 https://example.com -o file2 +.fi + +See also \fI-:, \-\-next\fP and \fI-v, \-\-verbose\fP. Added in 7.66.0. +.IP "\-\-parallel\-immediate" +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. + +This option is global and does not need to be specified for each use of --next. + +Providing --parallel-immediate multiple times has no extra effect. +Disable it again with \-\-no-parallel-immediate. + +Example: +.nf + curl --parallel-immediate -Z https://example.com -o file1 https://example.com -o file2 +.fi + +See also \fI-Z, \-\-parallel\fP and \fI\-\-parallel\-max\fP. Added in 7.68.0. +.IP "\-\-parallel\-max " +When asked to do parallel transfers, using \fI\-Z, \-\-parallel\fP, this option controls +the maximum amount of transfers to do simultaneously. + +This option is global and does not need to be specified for each use of +\fI\-:, \-\-next\fP. + +The default is 50. + +If --parallel-max is provided several times, the last set value is used. + +Example: +.nf + curl --parallel-max 100 -Z https://example.com ftp://example.com/ +.fi + +See also \fI-Z, \-\-parallel\fP. Added in 7.66.0. +.IP "\-\-pass " +(SSH TLS) Passphrase for the private key. + +If --pass is provided several times, the last set value is used. + +Example: +.nf + curl --pass secret --key file https://example.com +.fi + +See also \fI\-\-key\fP and \fI-u, \-\-user\fP. +.IP "\-\-path\-as\-is" +Do not handle sequences of /../ or /./ in the given URL path. Normally curl +squashes or merges them according to standards but with this option set you +tell it not to do that. + +Providing --path-as-is multiple times has no extra effect. +Disable it again with \-\-no-path-as-is. + +Example: +.nf + curl --path-as-is https://example.com/../../etc/passwd +.fi + +See also \fI\-\-request\-target\fP. +.IP "\-\-pinnedpubkey " +(TLS) Use the specified public key file (or hashes) to verify the peer. This can be +a path to a file which contains a single public key in PEM or DER format, or +any number of base64 encoded sha256 hashes preceded by \(aqsha256//\(aq and +separated by \(aq;\(aq. + +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 +aborts the connection before sending or receiving any data. + +This option is independent of option \fI\-k, \-\-insecure\fP. If you use both options +together then the peer is still verified by public key. + +PEM/DER support: + +OpenSSL and GnuTLS, wolfSSL (added in 7.43.0), mbedTLS +, Secure Transport macOS 10.7+/iOS 10+ (7.54.1), Schannel +(7.58.1) + +sha256 support: + +OpenSSL, GnuTLS and wolfSSL, mbedTLS (added in 7.47.0), +Secure Transport macOS 10.7+/iOS 10+ (7.54.1), Schannel (7.58.1) + +Other SSL backends not supported. + +If --pinnedpubkey is provided several times, the last set value is used. + +Examples: +.nf + curl --pinnedpubkey keyfile https://example.com + curl --pinnedpubkey 'sha256//ce118b51897f4452dc' https://example.com +.fi + +See also \fI\-\-hostpubsha256\fP. +.IP "\-\-post301" +(HTTP) Respect RFC 7231/6.4.2 and do not convert POST requests into GET requests when +following a 301 redirect. The non\-RFC behavior is ubiquitous in web browsers, +so curl does the conversion by default to maintain consistency. However, a +server may require a POST to remain a POST after such a redirection. This +option is meaningful only when using \fI\-L, \-\-location\fP. + +Providing --post301 multiple times has no extra effect. +Disable it again with \-\-no-post301. + +Example: +.nf + curl --post301 --location -d "data" https://example.com +.fi + +See also \fI\-\-post302\fP, \fI\-\-post303\fP and \fI-L, \-\-location\fP. +.IP "\-\-post302" +(HTTP) Respect RFC 7231/6.4.3 and do not convert POST requests into GET requests when +following a 302 redirect. The non\-RFC behavior is ubiquitous in web browsers, +so curl does the conversion by default to maintain consistency. However, a +server may require a POST to remain a POST after such a redirection. This +option is meaningful only when using \fI\-L, \-\-location\fP. + +Providing --post302 multiple times has no extra effect. +Disable it again with \-\-no-post302. + +Example: +.nf + curl --post302 --location -d "data" https://example.com +.fi + +See also \fI\-\-post301\fP, \fI\-\-post303\fP and \fI-L, \-\-location\fP. +.IP "\-\-post303" +(HTTP) Violate RFC 7231/6.4.4 and do not convert POST requests into GET requests when +following 303 redirect. A server may require a POST to remain a POST after a +303 redirection. This option is meaningful only when using \fI\-L, \-\-location\fP. + +Providing --post303 multiple times has no extra effect. +Disable it again with \-\-no-post303. + +Example: +.nf + curl --post303 --location -d "data" https://example.com +.fi + +See also \fI\-\-post302\fP, \fI\-\-post301\fP and \fI-L, \-\-location\fP. +.IP "\-\-preproxy [protocol://]host[:port]" +Use the specified SOCKS proxy before connecting to an HTTP or HTTPS \fI\-x, \-\-proxy\fP. In +such a case curl first connects to the SOCKS proxy and then connects (through +SOCKS) to the HTTP or HTTPS proxy. Hence pre proxy. + +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 makes curl default to SOCKS4. + +If the port number is not specified in the proxy string, it is assumed to be +1080. + +User and password that might be provided in the proxy string are URL decoded +by curl. This allows you to pass in special characters such as @ by using %40 +or pass in a colon with %3a. + +If --preproxy is provided several times, the last set value is used. + +Example: +.nf + curl --preproxy socks5://proxy.example -x http://http.example https://example.com +.fi + +See also \fI-x, \-\-proxy\fP and \fI\-\-socks5\fP. Added in 7.52.0. +.IP "\-#, \-\-progress\-bar" +Make curl display transfer progress as a simple progress bar instead of the +standard, more informational, meter. + +This progress bar draws a single line of \(aq#\(aq characters across the screen and +shows a percentage if the transfer size is known. For transfers without a +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. + +This option is global and does not need to be specified for each use of --next. + +Providing --progress-bar multiple times has no extra effect. +Disable it again with \-\-no-progress-bar. + +Example: +.nf + curl -# -O https://example.com +.fi + +See also \fI\-\-styled\-output\fP. +.IP "\-\-proto " +Limit what protocols to allow for transfers. Protocols are evaluated left to +right, are comma separated, and are each a protocol name or \(aqall\(aq, optionally +prefixed by zero or more modifiers. Available modifiers are: +.RS +.IP + +Permit this protocol in addition to protocols already permitted (this is +the default if no modifier is used). +.IP - +Deny this protocol, removing it from the list of protocols already permitted. +.IP = +Permit only this protocol (ignoring the list already permitted), though +subject to later modification by subsequent entries in the comma separated +list. +.RE +.IP +For example: \fI\-\-proto\fP \-ftps uses the default protocols, but disables ftps + +\fI\-\-proto\fP \-all,https,+http only enables http and https + +\fI\-\-proto\fP =http,https also only enables http and https + +Unknown and disabled protocols produce a warning. This allows scripts to +safely rely on being able to disable potentially dangerous protocols, without +relying upon support for that protocol being built into curl to avoid an error. + +This option can be used multiple times, in which case the effect is the same +as concatenating the protocols into one instance of the option. + +If --proto is provided several times, the last set value is used. + +Example: +.nf + curl --proto =http,https,sftp https://example.com +.fi + +See also \fI\-\-proto\-redir\fP and \fI\-\-proto\-default\fP. +.IP "\-\-proto\-default " +Use \fIprotocol\fP for any provided URL missing a scheme. + +An unknown or unsupported protocol causes error \fICURLE_UNSUPPORTED_PROTOCOL\fP. + +This option does not change the default proxy protocol (http). + +Without this option set, curl guesses protocol based on the hostname, see +\fI\-\-url\fP for details. + +If --proto-default is provided several times, the last set value is used. + +Example: +.nf + curl --proto-default https ftp.example.com +.fi + +See also \fI\-\-proto\fP and \fI\-\-proto\-redir\fP. +.IP "\-\-proto\-redir " +Limit what protocols to allow on redirects. Protocols denied by \fI\-\-proto\fP are +not overridden by this option. See \fI\-\-proto\fP for how protocols are represented. + +Example, allow only HTTP and HTTPS on redirect: +.nf + +curl \--proto\-redir \-all,http,https http://example.com +.fi + +By default curl only allows HTTP, HTTPS, FTP and FTPS on redirects (added in +7.65.2). Specifying \fIall\fP or \fI+all\fP enables all protocols on redirects, which +is not good for security. + +If --proto-redir is provided several times, the last set value is used. + +Example: +.nf + curl --proto-redir =http,https https://example.com +.fi + +See also \fI\-\-proto\fP. +.IP "\-x, \-\-proxy [protocol://]host[:port]" +Use the specified proxy. + +The proxy string can be specified with a protocol:// prefix. No protocol +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. + +Unix domain sockets are supported for socks proxy. Set localhost for the host +part. e.g. socks5h://localhost/path/to/socket.sock + +HTTPS proxy support works set with the https:// protocol prefix for OpenSSL +and GnuTLS (added in 7.52.0). It also works for BearSSL, mbedTLS, rustls, +Schannel, Secure Transport and wolfSSL (added in 7.87.0). + +Unrecognized and unsupported proxy protocols cause an error (added in 7.52.0). +Ancient curl versions ignored unknown schemes and used http:// instead. + +If the port number is not specified in the proxy string, it is assumed to be +1080. + +This option overrides existing environment variables that set the proxy to +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 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 \fI\-p, \-\-proxytunnel\fP option. + +User and password that might be provided in the proxy string are URL decoded +by curl. This allows you to pass in special characters such as @ by using %40 +or pass in a colon with %3a. + +The proxy host can be specified the same way as the proxy environment +variables, including the protocol prefix (http://) and the embedded user + +password. + +When a proxy is used, the active FTP mode as set with \fI\-P, \-\-ftp\-port\fP, cannot be +used. + +If --proxy is provided several times, the last set value is used. + +Example: +.nf + curl --proxy http://proxy.example https://example.com +.fi + +See also \fI\-\-socks5\fP and \fI\-\-proxy\-basic\fP. +.IP "\-\-proxy\-anyauth" +Automatically pick a suitable authentication method when communicating with +the given HTTP proxy. This might cause an extra request/response round\-trip. + +Providing --proxy-anyauth multiple times has no extra effect. + +Example: +.nf + curl --proxy-anyauth --proxy-user user:passwd -x proxy https://example.com +.fi + +See also \fI-x, \-\-proxy\fP, \fI\-\-proxy\-basic\fP and \fI\-\-proxy\-digest\fP. +.IP "\-\-proxy\-basic" +Use HTTP Basic authentication when communicating with the given proxy. Use +\fI\-\-basic\fP for enabling HTTP Basic with a remote host. Basic is the default +authentication method curl uses with proxies. + +Providing --proxy-basic multiple times has no extra effect. + +Example: +.nf + curl --proxy-basic --proxy-user user:passwd -x proxy https://example.com +.fi + +See also \fI-x, \-\-proxy\fP, \fI\-\-proxy\-anyauth\fP and \fI\-\-proxy\-digest\fP. +.IP "\-\-proxy\-ca\-native" +(TLS) Use the CA store from the native operating system to verify the 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\(aqs own vault. + +This option works for curl on Windows when built to use OpenSSL, wolfSSL +(added in 8.3.0) or GnuTLS (added in 8.5.0). When curl on Windows is built to +use Schannel, this feature is implied and curl then only uses the native CA +store. + +Providing --proxy-ca-native multiple times has no extra effect. +Disable it again with \-\-no-proxy-ca-native. + +Example: +.nf + curl --ca-native https://example.com +.fi + +See also \fI\-\-cacert\fP, \fI\-\-capath\fP and \fI-k, \-\-insecure\fP. Added in 8.2.0. +.IP "\-\-proxy\-cacert " +Same as \fI\-\-cacert\fP but used in HTTPS proxy context. + +If --proxy-cacert is provided several times, the last set value is used. + +Example: +.nf + curl --proxy-cacert CA-file.txt -x https://proxy https://example.com +.fi + +See also \fI\-\-proxy\-capath\fP, \fI\-\-cacert\fP, \fI\-\-capath\fP and \fI-x, \-\-proxy\fP. Added in 7.52.0. +.IP "\-\-proxy\-capath " +Same as \fI\-\-capath\fP but used in HTTPS proxy context. + +Use the specified certificate directory to verify the proxy. Multiple paths +can be provided by separated with colon (":") (e.g. "path1:path2:path3"). The +certificates must be in PEM format, and if curl is built against OpenSSL, the +directory must have been processed using the c_rehash utility supplied with +OpenSSL. Using \fI\-\-proxy\-capath\fP can allow OpenSSL\-powered curl to make +SSL\-connections much more efficiently than using \fI\-\-proxy\-cacert\fP if the +\fI\-\-proxy\-cacert\fP file contains many CA certificates. + +If this option is set, the default capath value is ignored. + +If --proxy-capath is provided several times, the last set value is used. + +Example: +.nf + curl --proxy-capath /local/directory -x https://proxy https://example.com +.fi + +See also \fI\-\-proxy\-cacert\fP, \fI-x, \-\-proxy\fP and \fI\-\-capath\fP. Added in 7.52.0. +.IP "\-\-proxy\-cert " +Same as \fI\-E, \-\-cert\fP but used in HTTPS proxy context. + +If --proxy-cert is provided several times, the last set value is used. + +Example: +.nf + curl --proxy-cert file -x https://proxy https://example.com +.fi + +See also \fI\-\-proxy\-cert\-type\fP. Added in 7.52.0. +.IP "\-\-proxy\-cert\-type " +Same as \fI\-\-cert\-type\fP but used in HTTPS proxy context. + +If --proxy-cert-type is provided several times, the last set value is used. + +Example: +.nf + curl --proxy-cert-type PEM --proxy-cert file -x https://proxy https://example.com +.fi + +See also \fI\-\-proxy\-cert\fP. Added in 7.52.0. +.IP "\-\-proxy\-ciphers " +Same as \fI\-\-ciphers\fP but used in HTTPS proxy context. + +Specifies which ciphers to use in the connection to the HTTPS proxy. The list +of ciphers must specify valid ciphers. Read up on SSL cipher list details on +this URL: + +https://curl.se/docs/ssl\-ciphers.html + +If --proxy-ciphers is provided several times, the last set value is used. + +Example: +.nf + curl --proxy-ciphers ECDHE-ECDSA-AES256-CCM8 -x https://proxy https://example.com +.fi + +See also \fI\-\-ciphers\fP, \fI\-\-curves\fP and \fI-x, \-\-proxy\fP. Added in 7.52.0. +.IP "\-\-proxy\-crlfile " +Same as \fI\-\-crlfile\fP but used in HTTPS proxy context. + +If --proxy-crlfile is provided several times, the last set value is used. + +Example: +.nf + curl --proxy-crlfile rejects.txt -x https://proxy https://example.com +.fi + +See also \fI\-\-crlfile\fP and \fI-x, \-\-proxy\fP. Added in 7.52.0. +.IP "\-\-proxy\-digest" +Use HTTP Digest authentication when communicating with the given proxy. Use +\fI\-\-digest\fP for enabling HTTP Digest with a remote host. + +Providing --proxy-digest multiple times has no extra effect. + +Example: +.nf + curl --proxy-digest --proxy-user user:passwd -x proxy https://example.com +.fi + +See also \fI-x, \-\-proxy\fP, \fI\-\-proxy\-anyauth\fP and \fI\-\-proxy\-basic\fP. +.IP "\-\-proxy\-header
" +(HTTP) Extra header to include in the request when sending HTTP to a proxy. You may +specify any number of extra headers. This is the equivalent option to \fI\-H, \-\-header\fP +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 makes sure that each header you add/replace is sent with the proper +end\-of\-line marker, you should thus \fBnot\fP add that as a part of the header +content: do not add newlines or carriage returns, they only mess things up for +you. + +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 @\- makes curl read +the headers from stdin. + +This option can be used multiple times to add/replace/remove multiple headers. + +--proxy-header can be used several times in a command line + +Examples: +.nf + curl --proxy-header "X-First-Name: Joe" -x http://proxy https://example.com + curl --proxy-header "User-Agent: surprise" -x http://proxy https://example.com + curl --proxy-header "Host:" -x http://proxy https://example.com +.fi + +See also \fI-x, \-\-proxy\fP. +.IP "\-\-proxy\-http2" +(HTTP) Negotiate HTTP/2 with an HTTPS proxy. The proxy might still only offer HTTP/1 +and then curl sticks to using that version. + +This has no effect for any other kinds of proxies. + +Providing --proxy-http2 multiple times has no extra effect. +Disable it again with \-\-no-proxy-http2. + +Example: +.nf + curl --proxy-http2 -x proxy https://example.com +.fi + +See also \fI-x, \-\-proxy\fP. \fI\-\-proxy\-http2\fP requires that the underlying libcurl was built to support HTTP/2. Added in 8.1.0. +.IP "\-\-proxy\-insecure" +Same as \fI\-k, \-\-insecure\fP but used in HTTPS proxy context. + +Every secure connection curl makes is verified to be secure before the +transfer takes place. This option makes curl skip the verification step with a +proxy and proceed without checking. + +When this option is not used for a proxy using HTTPS, curl verifies the +proxy\(aqs TLS certificate before it continues: that the certificate contains the +right name which matches the hostname and that the certificate has been signed +by a CA certificate present in the cert store. See this online resource for +further details: \fBhttps://curl.se/docs/sslcerts.html\fP + +\fBWARNING\fP: using this option makes the transfer to the proxy insecure. + +Providing --proxy-insecure multiple times has no extra effect. +Disable it again with \-\-no-proxy-insecure. + +Example: +.nf + curl --proxy-insecure -x https://proxy https://example.com +.fi + +See also \fI-x, \-\-proxy\fP and \fI-k, \-\-insecure\fP. Added in 7.52.0. +.IP "\-\-proxy\-key " +Same as \fI\-\-key\fP but used in HTTPS proxy context. + +If --proxy-key is provided several times, the last set value is used. + +Example: +.nf + curl --proxy-key here -x https://proxy https://example.com +.fi + +See also \fI\-\-proxy\-key\-type\fP and \fI-x, \-\-proxy\fP. Added in 7.52.0. +.IP "\-\-proxy\-key\-type " +Same as \fI\-\-key\-type\fP but used in HTTPS proxy context. + +If --proxy-key-type is provided several times, the last set value is used. + +Example: +.nf + curl --proxy-key-type DER --proxy-key here -x https://proxy https://example.com +.fi + +See also \fI\-\-proxy\-key\fP and \fI-x, \-\-proxy\fP. Added in 7.52.0. +.IP "\-\-proxy\-negotiate" +Use HTTP Negotiate (SPNEGO) authentication when communicating with the given +proxy. Use \fI\-\-negotiate\fP for enabling HTTP Negotiate (SPNEGO) with a remote +host. + +Providing --proxy-negotiate multiple times has no extra effect. + +Example: +.nf + curl --proxy-negotiate --proxy-user user:passwd -x proxy https://example.com +.fi + +See also \fI\-\-proxy\-anyauth\fP and \fI\-\-proxy\-basic\fP. +.IP "\-\-proxy\-ntlm" +Use HTTP NTLM authentication when communicating with the given proxy. Use +\fI\-\-ntlm\fP for enabling NTLM with a remote host. + +Providing --proxy-ntlm multiple times has no extra effect. + +Example: +.nf + curl --proxy-ntlm --proxy-user user:passwd -x http://proxy https://example.com +.fi + +See also \fI\-\-proxy\-negotiate\fP and \fI\-\-proxy\-anyauth\fP. +.IP "\-\-proxy\-pass " +Same as \fI\-\-pass\fP but used in HTTPS proxy context. + +If --proxy-pass is provided several times, the last set value is used. + +Example: +.nf + curl --proxy-pass secret --proxy-key here -x https://proxy https://example.com +.fi + +See also \fI-x, \-\-proxy\fP and \fI\-\-proxy\-key\fP. Added in 7.52.0. +.IP "\-\-proxy\-pinnedpubkey " +(TLS) Use the specified public key file (or hashes) to verify the proxy. This can be +a path to a file which contains a single public key in PEM or DER format, or +any number of base64 encoded sha256 hashes preceded by \(aqsha256//\(aq and +separated by \(aq;\(aq. + +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 +aborts the connection before sending or receiving any data. + +If --proxy-pinnedpubkey is provided several times, the last set value is used. + +Examples: +.nf + curl --proxy-pinnedpubkey keyfile https://example.com + curl --proxy-pinnedpubkey 'sha256//ce118b51897f4452dc' https://example.com +.fi + +See also \fI\-\-pinnedpubkey\fP and \fI-x, \-\-proxy\fP. Added in 7.59.0. +.IP "\-\-proxy\-service\-name " +Set the service name for proxy negotiation. + +If --proxy-service-name is provided several times, the last set value is used. + +Example: +.nf + curl --proxy-service-name "shrubbery" -x proxy https://example.com +.fi + +See also \fI\-\-service\-name\fP and \fI-x, \-\-proxy\fP. +.IP "\-\-proxy\-ssl\-allow\-beast" +Same as \fI\-\-ssl\-allow\-beast\fP but used in HTTPS proxy context. + +Providing --proxy-ssl-allow-beast multiple times has no extra effect. +Disable it again with \-\-no-proxy-ssl-allow-beast. + +Example: +.nf + curl --proxy-ssl-allow-beast -x https://proxy https://example.com +.fi + +See also \fI\-\-ssl\-allow\-beast\fP and \fI-x, \-\-proxy\fP. Added in 7.52.0. +.IP "\-\-proxy\-ssl\-auto\-client\-cert" +Same as \fI\-\-ssl\-auto\-client\-cert\fP but used in HTTPS proxy context. + +This is only supported by Schannel. + +Providing --proxy-ssl-auto-client-cert multiple times has no extra effect. +Disable it again with \-\-no-proxy-ssl-auto-client-cert. + +Example: +.nf + curl --proxy-ssl-auto-client-cert -x https://proxy https://example.com +.fi + +See also \fI\-\-ssl\-auto\-client\-cert\fP and \fI-x, \-\-proxy\fP. Added in 7.77.0. +.IP "\-\-proxy\-tls13\-ciphers " +(TLS) Specify which cipher suites to use in the connection to your HTTPS proxy when +it negotiates TLS 1.3. The list of ciphers suites must specify valid ciphers. +Read up on TLS 1.3 cipher suite details on this URL: + +https://curl.se/docs/ssl\-ciphers.html + +This option is currently used only when curl is built to use OpenSSL 1.1.1 or +later. If you are using a different SSL backend you can try setting TLS 1.3 +cipher suites by using the \fI\-\-proxy\-ciphers\fP option. + +If --proxy-tls13-ciphers is provided several times, the last set value is used. + +Example: +.nf + curl --proxy-tls13-ciphers TLS_AES_128_GCM_SHA256 -x proxy https://example.com +.fi + +See also \fI\-\-tls13\-ciphers\fP, \fI\-\-curves\fP and \fI\-\-proxy\-ciphers\fP. Added in 7.61.0. +.IP "\-\-proxy\-tlsauthtype " +Same as \fI\-\-tlsauthtype\fP but used in HTTPS proxy context. + +If --proxy-tlsauthtype is provided several times, the last set value is used. + +Example: +.nf + curl --proxy-tlsauthtype SRP -x https://proxy https://example.com +.fi + +See also \fI-x, \-\-proxy\fP and \fI\-\-proxy\-tlsuser\fP. Added in 7.52.0. +.IP "\-\-proxy\-tlspassword " +Same as \fI\-\-tlspassword\fP but used in HTTPS proxy context. + +If --proxy-tlspassword is provided several times, the last set value is used. + +Example: +.nf + curl --proxy-tlspassword passwd -x https://proxy https://example.com +.fi + +See also \fI-x, \-\-proxy\fP and \fI\-\-proxy\-tlsuser\fP. Added in 7.52.0. +.IP "\-\-proxy\-tlsuser " +Same as \fI\-\-tlsuser\fP but used in HTTPS proxy context. + +If --proxy-tlsuser is provided several times, the last set value is used. + +Example: +.nf + curl --proxy-tlsuser smith -x https://proxy https://example.com +.fi + +See also \fI-x, \-\-proxy\fP and \fI\-\-proxy\-tlspassword\fP. Added in 7.52.0. +.IP "\-\-proxy\-tlsv1" +Same as \fI\-1, \-\-tlsv1\fP but used in HTTPS proxy context. + +Providing --proxy-tlsv1 multiple times has no extra effect. + +Example: +.nf + curl --proxy-tlsv1 -x https://proxy https://example.com +.fi + +See also \fI-x, \-\-proxy\fP. Added in 7.52.0. +.IP "\-U, \-\-proxy\-user " +Specify the username and password to use for proxy authentication. + +If you use a Windows SSPI\-enabled curl binary and do either Negotiate or NTLM +authentication then you can tell curl to select the username and password from +your environment by specifying a single colon with this option: "\-U :". + +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. + +If --proxy-user is provided several times, the last set value is used. + +Example: +.nf + curl --proxy-user smith:secret -x proxy https://example.com +.fi + +See also \fI\-\-proxy\-pass\fP. +.IP "\-\-proxy1.0 " +Use the specified HTTP 1.0 proxy. If the port number is not specified, it is +assumed at port 1080. + +The only difference between this and the HTTP proxy option \fI\-x, \-\-proxy\fP, is that +attempts to use CONNECT through the proxy specifies an HTTP 1.0 protocol +instead of the default HTTP 1.1. + +Providing --proxy1.0 multiple times has no extra effect. + +Example: +.nf + curl --proxy1.0 http://proxy https://example.com +.fi + +See also \fI-x, \-\-proxy\fP, \fI\-\-socks5\fP and \fI\-\-preproxy\fP. +.IP "\-p, \-\-proxytunnel" +When an HTTP proxy is used \fI\-x, \-\-proxy\fP, 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 \fI\-\-suppress\-connect\-headers\fP. + +Providing --proxytunnel multiple times has no extra effect. +Disable it again with \-\-no-proxytunnel. + +Example: +.nf + curl --proxytunnel -x http://proxy https://example.com +.fi + +See also \fI-x, \-\-proxy\fP. +.IP "\-\-pubkey " +(SFTP SCP) Public key filename. Allows you to provide your public key in this separate +file. + +curl attempts to automatically extract the public key from the private key +file, so passing this option is generally not required. Note that this public +key extraction requires libcurl to be linked against a copy of libssh2 1.2.8 +or higher that is itself linked against OpenSSL. + +If --pubkey is provided several times, the last set value is used. + +Example: +.nf + curl --pubkey file.pub sftp://example.com/ +.fi + +See also \fI\-\-pass\fP. +.IP "\-Q, \-\-quote " +(FTP SFTP) Send an arbitrary command to the remote FTP or SFTP server. Quote commands are +sent BEFORE the transfer takes place (just after the initial \fBPWD\fP command +in an FTP transfer, to be exact). To make commands take place after a +successful transfer, prefix them with a dash \(aq\-\(aq. + +(FTP only) To make commands be sent after curl has changed the working +directory, just before the file transfer command(s), prefix the command with a +\(aq+\(aq. This is not performed when a directory listing is performed. + +You may specify any number of commands. + +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 is +aborted. + +You must send syntactically correct FTP commands as RFC 959 defines to FTP +servers, or one of the commands listed below to SFTP servers. + +SFTP is a binary protocol. Unlike for FTP, curl interprets SFTP quote commands +itself before sending them to the server. Filenames may be quoted shell\-style +to embed spaces or special characters. Following is the list of all supported +SFTP quote commands: +.RS +.IP "atime date file" +The atime command sets the last access time of the file named by the file +operand. The date expression can be all sorts of date strings, see the +\fIcurl_getdate(3)\fP man page for date expression details. (Added in 7.73.0) +.IP "chgrp group file" +The chgrp command sets the group ID of the file named by the file operand to +the group ID specified by the group operand. The group operand is a decimal +integer group ID. +.IP "chmod mode file" +The chmod command modifies the file mode bits of the specified file. The +mode operand is an octal integer mode number. +.IP "chown user file" +The chown command sets the owner of the file named by the file operand to the +user ID specified by the user operand. The user operand is a decimal +integer user ID. +.IP "ln source_file target_file" +The ln and symlink commands create a symbolic link at the target_file location +pointing to the source_file location. +.IP "mkdir directory_name" +The mkdir command creates the directory named by the directory_name operand. +.IP "mtime date file" +The mtime command sets the last modification time of the file named by the +file operand. The date expression can be all sorts of date strings, see the +\fIcurl_getdate(3)\fP man page for date expression details. (Added in 7.73.0) +.IP pwd +The pwd command returns the absolute path name of the current working directory. +.IP "rename source target" +The rename command renames the file or directory named by the source +operand to the destination path named by the target operand. +.IP "rm file" +The rm command removes the file specified by the file operand. +.IP "rmdir directory" +The rmdir command removes the directory entry specified by the directory +operand, provided it is empty. +.IP "symlink source_file target_file" +See ln. +.RE +.IP + +--quote can be used several times in a command line + +Example: +.nf + curl --quote "DELE file" ftp://example.com/foo +.fi + +See also \fI-X, \-\-request\fP. +.IP "\-\-random\-file " +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 random data. The data may be used to +seed the random engine for SSL connections. + +If --random-file is provided several times, the last set value is used. + +Example: +.nf + curl --random-file rubbish https://example.com +.fi + +See also \fI\-\-egd\-file\fP. +.IP "\-r, \-\-range " +(HTTP FTP SFTP FILE) Retrieve a byte range (i.e. a partial document) from an HTTP/1.1, FTP or SFTP +server or a local FILE. Ranges can be specified in a number of ways. +.RS +.IP 0-499 +specifies the first 500 bytes +.IP 500-999 +specifies the second 500 bytes +.IP -500 +specifies the last 500 bytes +.IP 9500- +specifies the bytes from offset 9500 and forward +.IP 0-0,-1 +specifies the first and last byte only(*)(HTTP) +.IP 100-199,500-599 +specifies two separate 100\-byte ranges(*) (HTTP) +.RE +.IP +(*) = NOTE that these make the server 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 \(aqstart\(aq and \(aqstop\(aq fields of the +\(aqstart\-stop\(aq range syntax. If a non\-digit character is given in the range, the +server\(aqs response is unspecified, depending on the server\(aqs configuration. + +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 \(aqstart\-stop\(aq syntax +(optionally with one of the numbers omitted). FTP use depends on the extended +FTP command SIZE. + +If --range is provided several times, the last set value is used. + +Example: +.nf + curl --range 22-44 https://example.com +.fi + +See also \fI-C, \-\-continue\-at\fP and \fI-a, \-\-append\fP. +.IP "\-\-rate " +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 starts the next transfer as fast as possible. + +If given several URLs and a transfer completes faster than the allowed rate, +curl waits until the next transfer is started to maintain the requested +rate. This option has no effect when \fI\-Z, \-\-parallel\fP is used. + +The request rate is provided as "N/U" where N is an integer number and U is a +time unit. Supported units are \(aqs\(aq (second), \(aqm\(aq (minute), \(aqh\(aq (hour) and \(aqd\(aq +/(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 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 instead runs unrestricted. + +When retrying transfers, enabled with \fI\-\-retry\fP, the separate retry delay logic +is used and not this setting. + +This option is global and does not need to be specified for each use of --next. + +If --rate is provided several times, the last set value is used. + +Examples: +.nf + curl --rate 2/s https://example.com ... + curl --rate 3/h https://example.com ... + curl --rate 14/m https://example.com ... +.fi + +See also \fI\-\-limit\-rate\fP and \fI\-\-retry\-delay\fP. Added in 7.84.0. +.IP "\-\-raw" +(HTTP) When used, it disables all internal HTTP decoding of content or transfer +encodings and instead makes them passed on unaltered, raw. + +Providing --raw multiple times has no extra effect. +Disable it again with \-\-no-raw. + +Example: +.nf + curl --raw https://example.com +.fi + +See also \fI\-\-tr\-encoding\fP. +.IP "\-e, \-\-referer " +(HTTP) Set the referrer URL in the HTTP request. This can also be set with the +\fI\-H, \-\-header\fP flag of course. When used with \fI\-L, \-\-location\fP you can append ";auto"" to +the \fI\-e, \-\-referer\fP URL to make curl automatically set the previous URL when it +follows a Location: header. The ";auto" string can be used alone, even if you +do not set an initial \fI\-e, \-\-referer\fP. + +If --referer is provided several times, the last set value is used. + +Examples: +.nf + curl --referer "https://fake.example" https://example.com + curl --referer "https://fake.example;auto" -L https://example.com + curl --referer ";auto" -L https://example.com +.fi + +See also \fI-A, \-\-user\-agent\fP and \fI-H, \-\-header\fP. +.IP "\-J, \-\-remote\-header\-name" +(HTTP) Tell the \fI\-O, \-\-remote\-name\fP option to use the server\-specified Content\-Disposition +filename instead of extracting a filename from the URL. If the server\-provided +filename contains a path, that is stripped off before the filename is used. + +The file is saved in the current directory, or in the directory specified with +\fI\-\-output\-dir\fP. + +If the server specifies a filename and a file with that name already exists in +the destination directory, it is not overwritten and an error occurs \- unless +you allow it by using the \fI\-\-clobber\fP option. If the server does not specify a +filename then this option has no effect. + +There is no attempt to decode %\-sequences (yet) in the provided filename, so +this option may provide you with rather unexpected filenames. + +This feature uses the name from the "filename" field, it does not yet support +the "filename*" field (filenames with explicit character sets). + +\fBWARNING\fP: Exercise judicious use of this option, especially on Windows. A +rogue server could send you the name of a DLL or other file that could be +loaded automatically by Windows or some third party software. + +Providing --remote-header-name multiple times has no extra effect. +Disable it again with \-\-no-remote-header-name. + +Example: +.nf + curl -OJ https://example.com/file +.fi + +See also \fI-O, \-\-remote\-name\fP. +.IP "\-O, \-\-remote\-name" +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 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 \fI\-\-output\-dir\fP. + +The remote filename to use for saving is extracted from the given URL, nothing +else, and if it already exists it is overwritten. If you want the server to be +able to choose the filename refer to \fI\-J, \-\-remote\-header\-name\fP which can be used in +addition to this option. If the server chooses a filename and that name +already exists it is not overwritten. + +There is no URL decoding done on the filename. If it has %20 or other URL +encoded parts of the name, they end up as\-is as filename. + +You may use this option as many times as the number of URLs you have. + +--remote-name can be used several times in a command line + +Example: +.nf + curl -O https://example.com/filename +.fi + +See also \fI\-\-remote\-name\-all\fP, \fI\-\-output\-dir\fP and \fI-J, \-\-remote\-header\-name\fP. +.IP "\-\-remote\-name\-all" +Change the default action for all given URLs to be dealt with as if +\fI\-O, \-\-remote\-name\fP were used for each one. If you want to disable that for a +specific URL after \fI\-\-remote\-name\-all\fP has been used, you must use "\-o \-" or +\fI\-\-no\-remote\-name\fP. + +Providing --remote-name-all multiple times has no extra effect. +Disable it again with \-\-no-remote-name-all. + +Example: +.nf + curl --remote-name-all ftp://example.com/file1 ftp://example.com/file2 +.fi + +See also \fI-O, \-\-remote\-name\fP. +.IP "\-R, \-\-remote\-time" +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. + +Providing --remote-time multiple times has no extra effect. +Disable it again with \-\-no-remote-time. + +Example: +.nf + curl --remote-time -o foo https://example.com +.fi + +See also \fI-O, \-\-remote\-name\fP and \fI-z, \-\-time\-cond\fP. +.IP "\-\-remove\-on\-error" +Remove output file if an error occurs. If curl returns an error when told to +save output in a local file. This prevents curl from leaving a partial file in +the case of an error during transfer. + +If the output is not a regular file, this option has no effect. + +Providing --remove-on-error multiple times has no extra effect. +Disable it again with \-\-no-remove-on-error. + +Example: +.nf + curl --remove-on-error -o output https://example.com +.fi + +See also \fI-f, \-\-fail\fP. Added in 7.83.0. +.IP "\-X, \-\-request " +Change the method to use when starting the transfer. + +curl passes on the verbatim string you give it its the request without any +filter or other safe guards. That includes white space and control characters. +.RS +.IP HTTP +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 \fIGET\fP). Read the HTTP 1.1 specification for details +and explanations. Common additional HTTP requests include \fIPUT\fP and \fIDELETE\fP, +while related technologies like WebDAV offers \fIPROPFIND\fP, \fICOPY\fP, \fIMOVE\fP and +more. + +Normally you do not need this option. All sorts of \fIGET\fP, \fIHEAD\fP, \fIPOST\fP and +\fIPUT\fP 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. For example if you want to make a proper HEAD +request, using \-X HEAD does not suffice. You need to use the \fI\-I, \-\-head\fP option. + +The method string you set with \fI\-X, \-\-request\fP is used for all requests, which +if you for example use \fI\-L, \-\-location\fP may cause unintended side\-effects when curl +does not change request method according to the HTTP 30x response codes \- and +similar. +.IP FTP +Specifies a custom FTP command to use instead of \fILIST\fP when doing file lists +with FTP. +.IP POP3 +Specifies a custom POP3 command to use instead of \fILIST\fP or \fIRETR\fP. + +.IP IMAP +Specifies a custom IMAP command to use instead of \fILIST\fP. +.IP SMTP +Specifies a custom SMTP command to use instead of \fIHELP\fP or \fBVRFY\fP. +.RE +.IP + +If --request is provided several times, the last set value is used. + +Examples: +.nf + curl -X "DELETE" https://example.com + curl -X NLST ftp://example.com/ +.fi + +See also \fI\-\-request\-target\fP. +.IP "\-\-request\-target " +(HTTP) Use an alternative target (path) instead of using the path as provided in the +URL. Particularly useful when wanting to issue HTTP requests without leading +slash or other data that does not follow the regular URL pattern, like +\&"OPTIONS *". + +curl passes on the verbatim string you give it its the request without any +filter or other safe guards. That includes white space and control characters. + +If --request-target is provided several times, the last set value is used. + +Example: +.nf + curl --request-target "*" -X OPTIONS https://example.com +.fi + +See also \fI-X, \-\-request\fP. Added in 7.55.0. +.IP "\-\-resolve <[+]host:port:addr[,addr]...>" +Provide a custom address for a specific host and port pair. Using this, you +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 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 \fI\-\-resolve\fP +with a specific host and port is used first. + +The provided address set by this option is used even if \fI\-4, \-\-ipv4\fP or \fI\-6, \-\-ipv6\fP is +set to make curl use another IP version. + +By prefixing the host with a \(aq+\(aq you can make the entry time out after curl\(aqs +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. + +Support for providing multiple IP addresses per entry was added in 7.59.0. + +Support for resolving with wildcard was added in 7.64.0. + +Support for the \(aq+\(aq prefix was added in 7.75.0. + +--resolve can be used several times in a command line + +Example: +.nf + curl --resolve example.com:443:127.0.0.1 https://example.com +.fi + +See also \fI\-\-connect\-to\fP and \fI\-\-alt\-svc\fP. +.IP "\-\-retry " +If a transient error is returned when curl tries to perform a transfer, it +retries this number of times before giving up. Setting the number to 0 +makes curl do no retries (which is the default). Transient error means either: +a timeout, an FTP 4xx response code or an HTTP 408, 429, 500, 502, 503 or 504 +response code. + +When curl is about to retry a transfer, it first waits one second and then for +all forthcoming retries it doubles the waiting time until it reaches 10 +minutes which then remains delay between the rest of the retries. By using +\fI\-\-retry\-delay\fP you disable this exponential backoff algorithm. See also +\fI\-\-retry\-max\-time\fP to limit the total time allowed for retries. + +curl complies with the Retry\-After: response header if one was present to know +when to issue the next retry (added in 7.66.0). + +If --retry is provided several times, the last set value is used. + +Example: +.nf + curl --retry 7 https://example.com +.fi + +See also \fI\-\-retry\-max\-time\fP. +.IP "\-\-retry\-all\-errors" +Retry on any error. This option is used together with \fI\-\-retry\fP. + +This option is the "sledgehammer" of retrying. Do not use this option by +default (for example in your \fBcurlrc\fP), there may be unintended consequences +such as sending or receiving duplicate data. Do not use with redirected input +or output. You might be better off handling your unique problems in a shell +script. Please read the example below. + +\fBWARNING\fP: For server compatibility curl attempts to retry failed flaky +transfers as close as possible to how they were started, but this is not +possible with redirected input or output. For example, before retrying it +removes output data from a failed partial transfer that was written to an +output file. However this is not true of data redirected to a | pipe or > +file, which are not reset. We strongly suggest you do not parse or record +output via redirect in combination with this option, since you may receive +duplicate data. + +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 \fI\-\-retry\fP 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 \fI\-f, \-\-fail\fP. + +Providing --retry-all-errors multiple times has no extra effect. +Disable it again with \-\-no-retry-all-errors. + +Example: +.nf + curl --retry 5 --retry-all-errors https://example.com +.fi + +See also \fI\-\-retry\fP. Added in 7.71.0. +.IP "\-\-retry\-connrefused" +In addition to the other conditions, consider ECONNREFUSED as a transient +error too for \fI\-\-retry\fP. This option is used together with \fI\-\-retry\fP. + +Providing --retry-connrefused multiple times has no extra effect. +Disable it again with \-\-no-retry-connrefused. + +Example: +.nf + curl --retry-connrefused --retry 7 https://example.com +.fi + +See also \fI\-\-retry\fP and \fI\-\-retry\-all\-errors\fP. Added in 7.52.0. +.IP "\-\-retry\-delay " +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 \fI\-\-retry\fP is also +used. Setting this delay to zero makes curl use the default backoff time. + +If --retry-delay is provided several times, the last set value is used. + +Example: +.nf + curl --retry-delay 5 --retry 7 https://example.com +.fi + +See also \fI\-\-retry\fP. +.IP "\-\-retry\-max\-time " +The retry timer is reset before the first transfer attempt. Retries are done +as usual (see \fI\-\-retry\fP) 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\(aqs maximum time, use \fI\-m, \-\-max\-time\fP. Set this option to zero +to not timeout retries. + +If --retry-max-time is provided several times, the last set value is used. + +Example: +.nf + curl --retry-max-time 30 --retry 10 https://example.com +.fi + +See also \fI\-\-retry\fP. +.IP "\-\-sasl\-authzid " +Use this authorization identity (\fBauthzid\fP), during SASL PLAIN +authentication, in addition to the authentication identity (\fBauthcid\fP) as +specified by \fI\-u, \-\-user\fP. + +If the option is not specified, the server derives the \fBauthzid\fP from the +\fBauthcid\fP, but if specified, and depending on the server implementation, it +may be used to access another user\(aqs inbox, that the user has been granted +access to, or a shared mailbox for example. + +If --sasl-authzid is provided several times, the last set value is used. + +Example: +.nf + curl --sasl-authzid zid imap://example.com/ +.fi + +See also \fI\-\-login\-options\fP. Added in 7.66.0. +.IP "\-\-sasl\-ir" +Enable initial response in SASL authentication. + +Providing --sasl-ir multiple times has no extra effect. +Disable it again with \-\-no-sasl-ir. + +Example: +.nf + curl --sasl-ir imap://example.com/ +.fi + +See also \fI\-\-sasl\-authzid\fP. +.IP "\-\-service\-name " +Set the service name for SPNEGO. + +If --service-name is provided several times, the last set value is used. + +Example: +.nf + curl --service-name sockd/server https://example.com +.fi + +See also \fI\-\-negotiate\fP and \fI\-\-proxy\-service\-name\fP. +.IP "\-S, \-\-show\-error" +When used with \fI\-s, \-\-silent\fP, it makes curl show an error message if it fails. + +This option is global and does not need to be specified for each use of --next. + +Providing --show-error multiple times has no extra effect. +Disable it again with \-\-no-show-error. + +Example: +.nf + curl --show-error --silent https://example.com +.fi + +See also \fI\-\-no\-progress\-meter\fP. +.IP "\-s, \-\-silent" +Silent or quiet mode. Do not show progress meter or error messages. Makes Curl +mute. It still outputs the data you ask for, potentially even to the +terminal/stdout unless you redirect it. + +Use \fI\-S, \-\-show\-error\fP in addition to this option to disable progress meter but +still show error messages. + +Providing --silent multiple times has no extra effect. +Disable it again with \-\-no-silent. + +Example: +.nf + curl -s https://example.com +.fi + +See also \fI-v, \-\-verbose\fP, \fI\-\-stderr\fP and \fI\-\-no\-progress\-meter\fP. +.IP "\-\-socks4 " +Use the specified SOCKS4 proxy. If the port number is not specified, it is +assumed at port 1080. Using this socket type make curl resolve the hostname +and passing the address on to the proxy. + +To specify proxy on a unix domain socket, use localhost for host, e.g. +\&"socks4://localhost/path/to/socket.sock" + +This option overrides any previous use of \fI\-x, \-\-proxy\fP, as they are mutually +exclusive. + +This option is superfluous since you can specify a socks4 proxy with \fI\-x, \-\-proxy\fP +using a socks4:// protocol prefix. + +\fI\-\-preproxy\fP can be used to specify a SOCKS proxy at the same time proxy is used +with an HTTP/HTTPS proxy (added in 7.52.0). In such a case, curl first +connects to the SOCKS proxy and then connects (through SOCKS) to the HTTP or +HTTPS proxy. + +If --socks4 is provided several times, the last set value is used. + +Example: +.nf + curl --socks4 hostname:4096 https://example.com +.fi + +See also \fI\-\-socks4a\fP, \fI\-\-socks5\fP and \fI\-\-socks5\-hostname\fP. +.IP "\-\-socks4a " +Use the specified SOCKS4a proxy. If the port number is not specified, it is +assumed at port 1080. This asks the proxy to resolve the hostname. + +To specify proxy on a unix domain socket, use localhost for host, e.g. +\&"socks4a://localhost/path/to/socket.sock" + +This option overrides any previous use of \fI\-x, \-\-proxy\fP, as they are mutually +exclusive. + +This option is superfluous since you can specify a socks4a proxy with \fI\-x, \-\-proxy\fP +using a socks4a:// protocol prefix. + +\fI\-\-preproxy\fP can be used to specify a SOCKS proxy at the same time \fI\-x, \-\-proxy\fP is +used with an HTTP/HTTPS proxy (added in 7.52.0). In such a case, curl first +connects to the SOCKS proxy and then connects (through SOCKS) to the HTTP or +HTTPS proxy. + +If --socks4a is provided several times, the last set value is used. + +Example: +.nf + curl --socks4a hostname:4096 https://example.com +.fi + +See also \fI\-\-socks4\fP, \fI\-\-socks5\fP and \fI\-\-socks5\-hostname\fP. +.IP "\-\-socks5 " +Use the specified SOCKS5 proxy \- but resolve the hostname locally. If the +port number is not specified, it is assumed at port 1080. + +To specify proxy on a unix domain socket, use localhost for host, e.g. +\&"socks5://localhost/path/to/socket.sock" + +This option overrides any previous use of \fI\-x, \-\-proxy\fP, as they are mutually +exclusive. + +This option is superfluous since you can specify a socks5 proxy with \fI\-x, \-\-proxy\fP +using a socks5:// protocol prefix. + +\fI\-\-preproxy\fP can be used to specify a SOCKS proxy at the same time \fI\-x, \-\-proxy\fP is +used with an HTTP/HTTPS proxy (added in 7.52.0). In such a case, curl first +connects to the SOCKS proxy and then connects (through SOCKS) to the HTTP or +HTTPS proxy. + +This option (as well as \fI\-\-socks4\fP) does not work with IPV6, FTPS or LDAP. + +If --socks5 is provided several times, the last set value is used. + +Example: +.nf + curl --socks5 proxy.example:7000 https://example.com +.fi + +See also \fI\-\-socks5\-hostname\fP and \fI\-\-socks4a\fP. +.IP "\-\-socks5\-basic" +Use username/password authentication when connecting to a SOCKS5 proxy. The +username/password authentication is enabled by default. Use \fI\-\-socks5\-gssapi\fP to +force GSS\-API authentication to SOCKS5 proxies. + +Providing --socks5-basic multiple times has no extra effect. + +Example: +.nf + curl --socks5-basic --socks5 hostname:4096 https://example.com +.fi + +See also \fI\-\-socks5\fP. Added in 7.55.0. +.IP "\-\-socks5\-gssapi" +Use GSS\-API authentication when connecting to a SOCKS5 proxy. The GSS\-API +authentication is enabled by default (if curl is compiled with GSS\-API +support). Use \fI\-\-socks5\-basic\fP to force username/password authentication to +SOCKS5 proxies. + +Providing --socks5-gssapi multiple times has no extra effect. +Disable it again with \-\-no-socks5-gssapi. + +Example: +.nf + curl --socks5-gssapi --socks5 hostname:4096 https://example.com +.fi + +See also \fI\-\-socks5\fP. Added in 7.55.0. +.IP "\-\-socks5\-gssapi\-nec" +As part of the GSS\-API negotiation a protection mode is negotiated. RFC 1961 +says in section 4.3/4.4 it should be protected, but the NEC reference +implementation does not. The option \fI\-\-socks5\-gssapi\-nec\fP allows the +unprotected exchange of the protection mode negotiation. + +Providing --socks5-gssapi-nec multiple times has no extra effect. +Disable it again with \-\-no-socks5-gssapi-nec. + +Example: +.nf + curl --socks5-gssapi-nec --socks5 hostname:4096 https://example.com +.fi + +See also \fI\-\-socks5\fP. +.IP "\-\-socks5\-gssapi\-service " +Set the service name for a socks server. Default is \fBrcmd/server\-fqdn\fP. + +If --socks5-gssapi-service is provided several times, the last set value is used. + +Example: +.nf + curl --socks5-gssapi-service sockd --socks5 hostname:4096 https://example.com +.fi + +See also \fI\-\-socks5\fP. +.IP "\-\-socks5\-hostname " +Use the specified SOCKS5 proxy (and let the proxy resolve the hostname). If +the port number is not specified, it is assumed at port 1080. + +To specify proxy on a unix domain socket, use localhost for host, e.g. +\&"socks5h://localhost/path/to/socket.sock" + +This option overrides any previous use of \fI\-x, \-\-proxy\fP, as they are mutually +exclusive. + +This option is superfluous since you can specify a socks5 hostname proxy with +\fI\-x, \-\-proxy\fP using a socks5h:// protocol prefix. + +\fI\-\-preproxy\fP can be used to specify a SOCKS proxy at the same time \fI\-x, \-\-proxy\fP is +used with an HTTP/HTTPS proxy (added in 7.52.0). In such a case, curl first +connects to the SOCKS proxy and then connects (through SOCKS) to the HTTP or +HTTPS proxy. + +If --socks5-hostname is provided several times, the last set value is used. + +Example: +.nf + curl --socks5-hostname proxy.example:7000 https://example.com +.fi + +See also \fI\-\-socks5\fP and \fI\-\-socks4a\fP. +.IP "\-Y, \-\-speed\-limit " +If a transfer is slower than this set speed (in bytes per second) for a given +number of seconds, it gets aborted. The time period is set with \fI\-y, \-\-speed\-time\fP +and is 30 seconds by default. + +If --speed-limit is provided several times, the last set value is used. + +Example: +.nf + curl --speed-limit 300 --speed-time 10 https://example.com +.fi + +See also \fI-y, \-\-speed\-time\fP, \fI\-\-limit\-rate\fP and \fI-m, \-\-max\-time\fP. +.IP "\-y, \-\-speed\-time " +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 \fI\-Y, \-\-speed\-limit\fP. + +This option controls transfers (in both directions) but does not affect slow +connects etc. If this is a concern for you, try the \fI\-\-connect\-timeout\fP option. + +If --speed-time is provided several times, the last set value is used. + +Example: +.nf + curl --speed-limit 300 --speed-time 10 https://example.com +.fi + +See also \fI-Y, \-\-speed\-limit\fP and \fI\-\-limit\-rate\fP. +.IP "\-\-ssl" +(FTP IMAP POP3 SMTP LDAP) Warning: this is considered an insecure option. Consider using \fI\-\-ssl\-reqd\fP +instead to be sure curl upgrades to a secure connection. + +Try to use SSL/TLS for the connection \- often referred to as STARTTLS or STLS +because of the involved commands. Reverts to a non\-secure connection if the +server does not support SSL/TLS. See also \fI\-\-ftp\-ssl\-control\fP and \fI\-\-ssl\-reqd\fP for +different levels of encryption required. + +This option is handled in LDAP (added in 7.81.0). It is fully supported by the +OpenLDAP backend and ignored by the generic ldap backend. + +Please note that a server may close the connection if the negotiation does +not succeed. + +This option was formerly known as \fI\-\-ftp\-ssl\fP. That option +name can still be used but might be removed in a future version. + +Providing --ssl multiple times has no extra effect. +Disable it again with \-\-no-ssl. + +Example: +.nf + curl --ssl pop3://example.com/ +.fi + +See also \fI\-\-ssl\-reqd\fP, \fI-k, \-\-insecure\fP and \fI\-\-ciphers\fP. +.IP "\-\-ssl\-allow\-beast" +(TLS) Do not work around a security flaw in the SSL3 and TLS1.0 protocols known as +BEAST. If this option is not used, the SSL layer may use workarounds known to +cause interoperability problems with some older SSL implementations. + +\fBWARNING\fP: this option loosens the SSL security, and by using this flag you +ask for exactly that. + +Providing --ssl-allow-beast multiple times has no extra effect. +Disable it again with \-\-no-ssl-allow-beast. + +Example: +.nf + curl --ssl-allow-beast https://example.com +.fi + +See also \fI\-\-proxy\-ssl\-allow\-beast\fP and \fI-k, \-\-insecure\fP. +.IP "\-\-ssl\-auto\-client\-cert" +(TLS) (Schannel) Automatically locate and use a client certificate for +authentication, when requested by the server. Since the server can request any +certificate that supports client authentication in the OS certificate store it +could be a privacy violation and unexpected. + +Providing --ssl-auto-client-cert multiple times has no extra effect. +Disable it again with \-\-no-ssl-auto-client-cert. + +Example: +.nf + curl --ssl-auto-client-cert https://example.com +.fi + +See also \fI\-\-proxy\-ssl\-auto\-client\-cert\fP. Added in 7.77.0. +.IP "\-\-ssl\-no\-revoke" +(TLS) (Schannel) Disable certificate revocation checks. WARNING: this option loosens +the SSL security, and by using this flag you ask for exactly that. + +Providing --ssl-no-revoke multiple times has no extra effect. +Disable it again with \-\-no-ssl-no-revoke. + +Example: +.nf + curl --ssl-no-revoke https://example.com +.fi + +See also \fI\-\-crlfile\fP. +.IP "\-\-ssl\-reqd" +(FTP IMAP POP3 SMTP LDAP) Require SSL/TLS for the connection \- often referred to as STARTTLS or STLS +because of the involved commands. Terminates the connection if the transfer +cannot be upgraded to use SSL/TLS. + +This option is handled in LDAP (added in 7.81.0). It is fully supported by the +OpenLDAP backend and rejected by the generic ldap backend if explicit TLS is +required. + +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 a transfer always fails if the TLS handshake does not work. + +This option was formerly known as \fI\-\-ftp\-ssl\-reqd\fP. + +Providing --ssl-reqd multiple times has no extra effect. +Disable it again with \-\-no-ssl-reqd. + +Example: +.nf + curl --ssl-reqd ftp://example.com +.fi + +See also \fI\-\-ssl\fP and \fI-k, \-\-insecure\fP. +.IP "\-\-ssl\-revoke\-best\-effort" +(TLS) (Schannel) Ignore certificate revocation checks when they failed due to +missing/offline distribution points for the revocation check lists. + +Providing --ssl-revoke-best-effort multiple times has no extra effect. +Disable it again with \-\-no-ssl-revoke-best-effort. + +Example: +.nf + curl --ssl-revoke-best-effort https://example.com +.fi + +See also \fI\-\-crlfile\fP and \fI-k, \-\-insecure\fP. Added in 7.70.0. +.IP "\-2, \-\-sslv2" +(SSL) This option previously asked curl to use SSLv2, but is now ignored +(added in 7.77.0). SSLv2 is widely considered insecure (see RFC 6176). + +Providing --sslv2 multiple times has no extra effect. + +Example: +.nf + curl --sslv2 https://example.com +.fi + +See also \fI\-\-http1.1\fP and \fI\-\-http2\fP. \fI-2, \-\-sslv2\fP requires that the underlying libcurl was built to support TLS. This option is mutually exclusive to \fI-3, \-\-sslv3\fP and \fI-1, \-\-tlsv1\fP and \fI\-\-tlsv1.1\fP and \fI\-\-tlsv1.2\fP. +.IP "\-3, \-\-sslv3" +(SSL) 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). + +Providing --sslv3 multiple times has no extra effect. + +Example: +.nf + curl --sslv3 https://example.com +.fi + +See also \fI\-\-http1.1\fP and \fI\-\-http2\fP. \fI-3, \-\-sslv3\fP requires that the underlying libcurl was built to support TLS. This option is mutually exclusive to \fI-2, \-\-sslv2\fP and \fI-1, \-\-tlsv1\fP and \fI\-\-tlsv1.1\fP and \fI\-\-tlsv1.2\fP. +.IP "\-\-stderr " +Redirect all writes to stderr to the specified file instead. If the filename +is a plain \(aq\-\(aq, it is instead written to stdout. + +This option is global and does not need to be specified for each use of --next. + +If --stderr is provided several times, the last set value is used. + +Example: +.nf + curl --stderr output.txt https://example.com +.fi + +See also \fI-v, \-\-verbose\fP and \fI-s, \-\-silent\fP. +.IP "\-\-styled\-output" +Enable automatic use of bold font styles when writing HTTP headers to the +terminal. Use \fI\-\-no\-styled\-output\fP to switch them off. + +Styled output requires a terminal that supports bold fonts. This feature is +not present on curl for Windows due to lack of this capability. + +This option is global and does not need to be specified for each use of --next. + +Providing --styled-output multiple times has no extra effect. +Disable it again with \-\-no-styled-output. + +Example: +.nf + curl --styled-output -I https://example.com +.fi + +See also \fI-I, \-\-head\fP and \fI-v, \-\-verbose\fP. Added in 7.61.0. +.IP "\-\-suppress\-connect\-headers" +When \fI\-p, \-\-proxytunnel\fP is used and a CONNECT request is made do not output proxy +CONNECT response headers. This option is meant to be used with \fI\-D, \-\-dump\-header\fP or +\fI\-i, \-\-include\fP which are used to show protocol headers in the output. It has no +effect on debug options such as \fI\-v, \-\-verbose\fP or \fI\-\-trace\fP, or any statistics. + +Providing --suppress-connect-headers multiple times has no extra effect. +Disable it again with \-\-no-suppress-connect-headers. + +Example: +.nf + curl --suppress-connect-headers --include -x proxy https://example.com +.fi + +See also \fI-D, \-\-dump\-header\fP, \fI-i, \-\-include\fP and \fI-p, \-\-proxytunnel\fP. Added in 7.54.0. +.IP "\-\-tcp\-fastopen" +Enable use of TCP Fast Open (RFC 7413). TCP Fast Open is a TCP extension that +allows data to get sent earlier over the connection (before the final +handshake ACK) if the client and server have been connected previously. + +Providing --tcp-fastopen multiple times has no extra effect. +Disable it again with \-\-no-tcp-fastopen. + +Example: +.nf + curl --tcp-fastopen https://example.com +.fi + +See also \fI\-\-false\-start\fP. +.IP "\-\-tcp\-nodelay" +Turn on the TCP_NODELAY option. See the \fIcurl_easy_setopt(3)\fP man page for +details about this option. + +curl sets this option by default and you need to explicitly switch it off if +you do not want it on (added in 7.50.2). + +Providing --tcp-nodelay multiple times has no extra effect. +Disable it again with \-\-no-tcp-nodelay. + +Example: +.nf + curl --tcp-nodelay https://example.com +.fi + +See also \fI-N, \-\-no\-buffer\fP. +.IP "\-t, \-\-telnet\-option " +Pass options to the telnet protocol. Supported options are: +.RS +.IP `TTYPE=` +Sets the terminal type. +.IP "`XDISPLOC=`" +Sets the X display location. +.IP `NEW_ENV=` +Sets an environment variable. +.RE +.IP + +--telnet-option can be used several times in a command line + +Example: +.nf + curl -t TTYPE=vt100 telnet://example.com/ +.fi + +See also \fI-K, \-\-config\fP. +.IP "\-\-tftp\-blksize " +(TFTP) Set the TFTP \fBBLKSIZE\fP option (must be 512 or larger). This is the block +size that curl tries to use when transferring data to or from a TFTP +server. By default 512 bytes are used. + +If --tftp-blksize is provided several times, the last set value is used. + +Example: +.nf + curl --tftp-blksize 1024 tftp://example.com/file +.fi + +See also \fI\-\-tftp\-no\-options\fP. +.IP "\-\-tftp\-no\-options" +(TFTP) Do not to send TFTP options requests. This improves interop with some legacy +servers that do not acknowledge or properly implement TFTP options. When this +option is used \fI\-\-tftp\-blksize\fP is ignored. + +Providing --tftp-no-options multiple times has no extra effect. +Disable it again with \-\-no-tftp-no-options. + +Example: +.nf + curl --tftp-no-options tftp://192.168.0.1/ +.fi + +See also \fI\-\-tftp\-blksize\fP. +.IP "\-z, \-\-time\-cond