diff options
Diffstat (limited to 'docs/gnurl.1')
| -rw-r--r-- | docs/gnurl.1 | 3747 |
1 files changed, 3747 insertions, 0 deletions
diff --git a/docs/gnurl.1 b/docs/gnurl.1 new file mode 100644 index 000000000..3404d11c3 --- /dev/null +++ b/docs/gnurl.1 @@ -0,0 +1,3747 @@ +.\" +.\" _ _ ____ _ +.\" Project ___| | | | _ \| | +.\" / __| | | | |_) | | +.\" | (__| |_| | _ <| |___ +.\" \___|\___/|_| \_\_____| +.\" +.\" Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, 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.haxx.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. +.\" +.Dd May 22, 2019 +.Dt GNURL 1 +.Os +.Sh NAME +.Nm gnurl +.Nd transfer a URL +.Sh SYNOPSIS +.Nm +.Op Fl -abstract-unix-socket Ar <path> +.Op Fl -alt-svc Ar <file name> +.Op Fl -anyauth +.Op Fl a | -append +.Op Fl -basic +.Op Fl -cacert Ar <file> +.Op Fl -capath Ar <dir> +.Op Fl -cert-status +.Op Fl -cert-type Ar <type> +.Op Fl E Ar <certificate[:password]> | Fl -cert Ar <certificate[:password]> +.Op Fl -ciphers Ar <list of ciphers> +.Op Fl -compressed-ssh +.Op Fl -compressed +.Op Fl K Ar <file> | -config <file> +.Op Fl -connect-timeout Ar <seconds> +.Op Fl -connect-to Ar <HOST1:PORT1:HOST2:PORT2> +.Op Fl C Ar <offset> | Fl -continue-at Ar <offset> +.Op Fl c Ar <filename> | Fl -cookie-jar Ar <filename> +.Op Fl b Ar <data|filename> | Fl -cookie Ar <data|filename> +.Op Fl -create-dirs +.Op Fl -crlf +.Op Fl -crlfile Ar <file> +.Op Fl -data-binary Ar <data> +.Op Fl -data-raw Ar <data> +.Op Fl -data-urlencode Ar <data> +.Op Fl d Ar data | Fl -data Ar data +.Op Fl -delegation Ar LEVEL +.Op Fl -digest +.Op Fl -disable-eprt +.Op Fl -disable-epsv +.Op Fl q | -disable +.Op Fl -dns-interface Ar <interface> +.Op Fl -dns-ipv4-addr Ar <address> +.Op Fl -dns-ipv6-addr Ar <address> +.Op Fl -dns-servers Ar <addresses> +.Op Fl -doh-url <URL> +.Op Fl D Ar <filename> | Fl -dump-header Ar <filename> +.Op Fl -egd-file Ar <file> +.Op Fl -engine Ar <name> +.Op Fl -expect100-timeout Ar <seconds> +.Op Fl -fail-early +.Op Fl f | -fail +.Op Fl -false-start +.Op Fl -form-string Ar <name=string> +.Op Fl F Ar <name=content> | -form Ar <name=content> +.Op Fl -ftp-account Ar <data> +.Op Fl -ftp-alternative-to-user Ar <command> +.Op Fl -ftp-create-dirs +.Op Fl -ftp-method Ar <method> +.Op Fl -ftp-pasv +.Op Fl P Ar <address> | -ftp-port Ar <address> +.Op Fl -ftp-pret +.Op Fl -ftp-skip-pasv-ip +.Op Fl -ftp-ssl-ccc-mode Ar <active/passive> +.Op Fl -ftp-ssl-ccc +.Op Fl -ftp-ssl-control +.Op Fl G | -get +.Op Fl g | -globoff +.Op Fl -happy-eyeballs-timeout-ms Ar milliseconds +.Op Fl -haproxy-protocol +.Op Fl I | -head +.Op Fl h | -help +.Op Fl -hostpubmd5 Ar <md5> +.Op Fl -http0.9 +.Op Fl 0 | -http1.0 +.Op Fl -http1.1 +.Op Fl -http2-prior-knowledge +.Op Fl -http2 +.Op Fl -ignore-content-length +.Op Fl i | -include +.Op Fl k | -insecure +.Op Fl -interface Ar <name> +.Op Fl 4 | -ipv4 +.Op Fl 6 | -ipv6 +.Op Fl j | -junk-session-cookies +.Op Fl -key-type Ar <type> +.Op Fl -key Ar <key> +.Op Fl -krb Ar <level> +.Op Fl -libcurl Ar <file> +.Op Fl -limit-rate Ar <speed> +.Op Fl l | -list-only +.Op Fl -location-trusted +.Op Fl L | -location +.Op Fl -login-options Ar <options> +.Op Fl -mail-auth Ar <address> +.Op Fl -mail-from Ar <address> +.Op Fl -mail-rcpt Ar <address> +.Op Fl M | -manual +.Op Fl -max-filesize Ar <bytes> +.Op Fl -max-redirs Ar <num> +.Op Fl -metalink +.Op Fl -negotiate +.Op Fl -netrc-file Ar filename +.Op Fl -netrc-optional +.Op Fl n | -netrc +.Op Fl : | -next +.Op Fl -no-alpn +.Op Fl N | -no-buffer +.Op Fl -no-keepalive +.Op Fl -no-npn +.Op Fl -no-sessionid +.Op Fl -noproxy Ar no-proxy-list +.Op Fl -ntlm-wb +.Op Fl -ntlm +.Op Fl -oauth2-bearer Ar token +.Op Fl o Ar FILE | Fl -output Ar FILE +.Op Fl -pass Ar phrase +.Op Fl -path-as-is +.Op Fl -pinnedpubkey Ar <hashes> +.Op Fl -post301 +.Op Fl -post302 +.Op Fl -post303 +.Op Fl -preproxy Ar [protocol://]host[:port] +.Op Fl # | -progress-bar +.Op Fl -proto-default Ar <protocol> +.Op Fl -proto-redir Ar <protocols> +.Op Fl -proto Ar <protocols> +.Op Fl -proxy-anyauth +.Op Fl -proxy-basic +.Op Fl -proxy-cacert Ar <file> +.Op Fl -proxy-capath Ar <dir> +.Op Fl -proxy-cert-type Ar <type> +.Op Fl -proxy-cert Ar <cert[:passwd]> +.Op Fl -proxy-ciphers Ar <list> +.Op Fl -proxy-crlfile Ar <file> +.Op Fl -proxy-digest +.Op Fl -proxy-header Ar <header/@file> +.Op Fl -proxy-insecure +.Op Fl -proxy-key-type Ar <type> +.Op Fl -proxy-key Ar <key> +.Op Fl -proxy-negotiate +.Op Fl -proxy-ntlm +.Op Fl -proxy-pass Ar <phrase> +.Op Fl -proxy-pinnedpubkey Ar <hashes> +.Op Fl -proxy-service-name Ar <name> +.Op Fl -proxy-ssl-allow-beast +.Op Fl -proxy-tls13-ciphers Ar <ciphersuite list> +.Op Fl -proxy-tlsauthtype Ar <type> +.Op Fl -proxy-tlspassword Ar <string> +.Op Fl -proxy-tlsuser Ar <name> +.Op Fl -proxy-tlsv1 +.Op Fl U Ar <user:password> | Fl -proxy-user Ar <user:password> +.Op Fl x Ar [protocol://]host[:port] | -proxy Ar [protocol://]host[:port] +.Op Fl -proxy1.0 Ar <host[:port]> +.Op Fl p | -proxytunnel +.Op Fl -pubkey Ar <key> +.Op Fl Q | -quote +.Op Fl -random-file Ar <file> +.Op Fl r Ar <range> | Fl -range Ar <range> +.Op Fl -raw +.Op Fl e | -referer Ar <URL> +.Op Fl J | -remote-header-name +.Op Fl -remote-name-all +.Op Fl O | -remote-name +.Op Fl R | -remote-time +.Op Fl -request-target +.Op Fl X Ar command | -request Ar <command> +.Op Fl -resolve Ar <host:port:address[,address]...> +.Op Fl -retry-connrefused +.Op Fl -retry-delay Ar <seconds> +.Op Fl -retry-max-time Ar <seconds> +.Op Fl -retry Ar <num> +.Op Fl -sasl-ir +.Op Fl -service-name Ar <name> +.Op Fl S | -show-error +.Op Fl s | -silent +.Op Fl -socks4 Ar <host[:port]> +.Op Fl -socks4a Ar <host[:port]> +.Op Fl -socks5-basic +.Op Fl -socks5-gssapi-nec +.Op Fl -socks5-gssapi-service Ar <name> +.Op Fl -socks5-gssapi +.Op Fl -socks5-hostname Ar <host[:port]> +.Op Fl -socks5 Ar <host[:port]> +.Op Fl Y Ar speed | Fl -speed-limit Ar <speed> +.Op Fl Fl y Ar seconds | -speed-time Ar <seconds> +.Op Fl -ssl-allow-beast +.Op Fl -ssl-no-revoke +.Op Fl -ssl-reqd +.Op Fl -ssl +.Op Fl 2 | -sslv2 +.Op Fl 3 | -sslv3 +.Op Fl -stderr +.Op Fl -styled-output +.Op Fl -suppress-connect-headers +.Op Fl -tcp-fastopen +.Op Fl -tcp-nodelay +.Op Fl t Ar opt=val | Fl -telnet-option Ar <opt=val> +.Op Fl -tftp-blksize Ar <value> +.Op Fl -tftp-no-options +.Op Fl z time | -time-cond Ar <time> +.Op Fl -tls-max Ar <VERSION> +.Op Fl -tls13-ciphers Ar <list of TLS 1.3 ciphersuites> +.Op Fl -tlsauthtype Ar <type> +.Op Fl -tlspassword +.Op Fl -tlsuser Ar <name> +.Op Fl -tlsv1.0 +.Op Fl -tlsv1.1 +.Op Fl -tlsv1.2 +.Op Fl -tlsv1.3 +.Op Fl 1 | -tlsv1 +.Op Fl -tr-encoding +.Op Fl -trace-ascii Ar <file> +.Op Fl -trace-time +.Op Fl -trace Ar <file> +.Op Fl T Ar file | Fl -upload-file Ar <file> +.Op Fl -url Ar <url> +.Op Fl B | -use-ascii +.Op Fl A Ar <name> | Fl -user-agent Ar <name> +.Op Fl u Ar <user:password> | Fl -user Ar <user:password> +.Op Fl v | -verbose +.Op Fl V | -version +.Op Fl w Ar <format> | Fl -write-out Ar <format> +.Op Fl -xattr +.Ao Ar URLs Ac +.Sh DESCRIPTION +.Nm +is a tool to transfer data from or to a server, using one of the supported +protocols (DICT, FILE, FTP, FTPS, GOPHER, HTTP, HTTPS, IMAP, IMAPS, LDAP, +LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET +and TFTP). The command is designed to work without user interaction. +.Pp +gnurl offers a busload of useful tricks like proxy support, user +authentication, FTP upload, HTTP post, SSL connections, cookies, file +transfer resume, Metalink, and more. As you will see below, the number +of features will make your head spin! +.Pp +gnurl is powered by libgnurl for all transfer-related features. See +.Xr libcurl 3 +for details. +.Ss URL +The URL syntax is protocol-dependent. You'll find a detailed +description in RFC 3986. +.Pp +You can specify multiple URLs or parts of URLs by writing part sets +within braces as in: +.Pp +.Dl http://site.{one,two,three}.com +.Pp +or you can get sequences of alphanumeric series by using [] as in: +.Pp +.Dl ftp://ftp.example.com/file[1-100].txt +.Pp +.Dl ftp://ftp.example.com/file[001-100].txt (with leading zeros) +.Pp +.Dl ftp://ftp.example.com/file[a-z].txt +.Pp +Nested sequences are not supported, but you can use several ones next +to each other: +.Pp +.Dl http://example.com/archive[1996-1999]/vol[1-4]/part{a,b,c}.html +.Pp +You can specify any amount of URLs on the command line. They will be +fetched in a sequential manner in the specified order. You can specify +command line options and URLs mixed and in any order on the command +line. +.Pp +You can specify a step counter for the ranges to get every Nth number +or letter: +.Pp +.Dl http://example.com/file[1-100:10].txt +.Pp +.Dl http://example.com/file[a-z:2].txt +.Pp +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 '&', '?' and '*'. +.Pp +Provide the IPv6 zone index in the URL with an escaped percentage sign +and the interface name. Like in +.Pp +.Dl http://[fe80::3%25eth0]/ +.Pp +If you specify URL without protocol:// prefix, curl will attempt to +guess what protocol you might want. It will then default to HTTP but +try other protocols based on often-used host name prefixes. For +example, for host names starting with "ftp." curl will assume you want +to speak FTP. +.Pp +curl will do its best to use what you pass to it as a URL. It is not +trying to validate it as a syntactically correct URL by any means but +is instead \fBvery\fP liberal with what it accepts. +.Pp +curl will attempt to re-use connections for multiple file transfers, +so that getting many files from the same server will not do multiple +connects / handshakes. This improves speed. Of course this is only +done on files specified on a single command line and cannot be used +between separate curl invokes. +.Ss PROGRESS METER +gnurl normally displays a progress meter during operations, indicating +the amount of transferred data, transfer speeds and estimated time +left, etc. The progress meter displays number of bytes and the speeds +are in bytes per second. The suffixes (k, M, G, T, P) are 1024 +based. For example 1k is 1024 bytes. 1M is 1048576 bytes. +.Pp +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. +.Pp +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 (>), +.Fl o | -output +or similar. +.Pp +It is not the same case for FTP upload as that operation does not spit +out any response data to the terminal. +.Pp +If you prefer a progress "bar" instead of the regular meter, +.Fl # | -progress-bar +is your friend. +You can also disable the progress meter completely with the +.Fl s | -silent +option. +.Ss OPTIONS +Options start with one or two dashes. Many of the options require an +additional value next to them. +.Pp +The short "single-dash" form of the options, +.Fl 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, +.Fl d | -data +for example, requires a space between it and its value. +.Pp +Short version options that don't need any additional values can be used +immediately next to each other, like for example you can specify all the +options +.Fl O , +.Fl L +and +.Fl v +at once as +.Fl OLv . +.Pp +In general, all boolean options are enabled with +.Fl -option +and yet again disabled with +.Fl -no-option . +That is, you use the exact same option name but prefix it with "no-". +However, in this list we mostly only list and show the +.Fl -option +version of them. (This concept with +.Fl -no +options was added in 7.19.0. Previously most options were toggled +on/off on repeated use of the same command line option.) +.Bl -tag -width indent +.It Fl -abstract-unix-socket Ar <path> +(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 <path> argument should not have this leading character. +.Pp +Added in 7.53.0. +.It Fl -alt-svc Ar <file name> +(HTTPS) WARNING: this option is experimental. Do not use in production. +.Pp +This option enables the alt-svc parser in curl. If the file name points to an +existing alt-svc cache file, that will be used. After a completed transfer, +the cache will be saved to the file name again if it has been modified. +.Pp +Specify a "" file name (zero length) to avoid loading/saving and make curl +just handle the cache in memory. +.Pp +If this option is used several times, curl will load contents from all the +files but the the last one will be used for saving. +.Pp +Added in 7.64.1. +.It Fl -anyauth +(HTTP) Tells curl to figure out authentication method by itself, 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 is used instead of setting a specific authentication +method, which you can do with +.Fl -basic , +.Fl -digest , +.Fl -ntlm , +and +.Fl -negotiate . +.Pp +Using +.Fl -anyauth +is not recommended if you do uploads from stdin, since it may +require data to be sent twice and then the client must be able to rewind. If +the need should arise when uploading from stdin, the upload operation will +fail. +.Pp +Used together with +.Fl u | -user . +.Pp +See also +.Fl -proxy-anyauth , +.Fl -basic +and +.Fl -digest . +.It Fl a | -append +(FTP SFTP) When used in an upload, this makes curl append to the target file +instead of overwriting it. +If the remote file doesn't exist, it will be created. +Note that this flag is ignored by some SFTP servers (including OpenSSH). +.It Fl -basic +(HTTP) Tells curl to use HTTP Basic authentication with the remote host. This 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 +.Fl -ntlm , +.Fl -digest , +or +.Fl -negotiate Ns ). +.Pp +Used together with +.Fl u | -user . +.Pp +See also +.Fl -proxy-basic . +.It Fl -cacert Ar <file> +(TLS) Tells curl to 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. +.Pp +curl recognizes the environment variable named 'CURL_CA_BUNDLE' if it is +set, and uses the given path as a path to a CA cert bundle. This option +overrides that variable. +.Pp +The windows version of curl will automatically look for a CA certs file named +.Pa curl-ca-bundle.crt , +either in the same directory as curl.exe, or in the +Current Working Directory, or in any folder along your PATH. +.Pp +If curl is built against the NSS SSL library, the NSS PEM PKCS#11 module +(libnsspem.so) needs to be available for this option to work properly. +.Pp +(iOS and macOS only) If curl is built against Secure Transport, then this +option is supported for backward compatibility with other SSL engines, but it +should not be set. If the option is not set, then curl will use the +certificates in the system and user Keychain to verify the peer, which is the +preferred method of verifying the peer's certificate chain. +.Pp +(Schannel only) This option is supported for Schannel in Windows 7 or later with +libcurl 7.60 or later. This option is supported for backward compatibility +with other SSL engines; instead it is recommended to use Windows' store of +root certificates (the default for Schannel). +.Pp +If this option is used several times, the last one will be used. +.It Fl -capath Ar <dir> +(TLS) Tells curl to use the specified certificate directory to verify the +peer. Multiple paths can be provided by separating them with ":" (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 +.Fl -capath +can allow OpenSSL-powered curl to make SSL-connections much more +efficiently than using +.Fl -cacert +if the +.Fl -cacert +file contains many CA certificates. +.Pp +If this option is set, the default capath value will be ignored, and if it is +used several times, the last one will be used. +.It Fl -cert-status +(TLS) Tells curl to verify the status of the server certificate by using the +Certificate Status Request (aka. OCSP stapling) TLS extension. +.Pp +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. +.Pp +This is currently only implemented in the OpenSSL, GnuTLS and NSS backends. +.Pp +Added in 7.41.0. +.It Fl -cert-type Ar <type> +(TLS) Tells curl what type the provided client certificate is +using. PEM, DER, ENG and P12 are recognized types. If not specified, +PEM is assumed. +.Pp +If this option is used several times, the last one will be used. +.Pp +See also +.Fl E | -cert +and +.Fl -key +and +.Fl -key-type . +.It Fl E Ar <certificate[:password]> | Fl -cert Ar <certificate[:password]> +(TLS) Tells curl to use the specified client certificate file when getting a file +with HTTPS, FTPS or another SSL-based protocol. The certificate must be in +PKCS#12 format if using Secure Transport, or PEM format if using any other +engine. If the optional password isn't specified, it will be 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. +.Pp +If curl is built against the NSS SSL library then this option can tell +curl the nickname of the certificate to use within the NSS database defined +by the environment variable SSL_DIR (or by default /etc/pki/nssdb). If the +NSS PEM PKCS#11 module (libnsspem.so) is available then PEM files may be +loaded. If you want to use a file from the current directory, please precede +it with "./" prefix, in order to avoid confusion with a nickname. If the +nickname contains ":", it needs to be preceded by "\\" so that it is not +recognized as password delimiter. If the nickname contains "\\", it needs to +be escaped as "\\\\" so that it is not recognized as an escape character. +.Pp +If curl is built against OpenSSL library, and the engine pkcs11 is available, +then a PKCS#11 URI (RFC 7512) can be used to specify a certificate located in +a PKCS#11 device. A string beginning with "pkcs11:" will be interpreted as a +PKCS#11 URI. If a PKCS#11 URI is provided, then the \fI--engine\fP option will be set +as "pkcs11" if none was provided and the \fI--cert-type\fP option will be set as +"ENG" if none was provided. +.Pp +(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. +.Pp +(Schannel only) Client certificates must be specified by a path +expression to a certificate store. (Loading PFX is not supported; you can +import it to a store first). You can use +"<store location>\\<store name>\\<thumbprint>" to refer to a certificate +in the system certificates store, for example, +"CurrentUser\\MY\\934a7ac6f8a5d579285a74fa61e19f23ddfe8d7a". Thumbprint is +usually a SHA-1 hex string which you can see in certificate details. Following +store locations are supported: CurrentUser, LocalMachine, CurrentService, +Services, CurrentUserGroupPolicy, LocalMachineGroupPolicy, +LocalMachineEnterprise. +.Pp +If this option is used several times, the last one will be used. +.Pp +See also \fI--cert-type\fP and \fI--key\fP and \fI--key-type\fP. +.It Fl -ciphers Ar <list of 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: +.Pp +.Dl https://curl.haxx.se/docs/ssl-ciphers.html +.Pp +If this option is used several times, the last one will be used. +.It Fl -compressed-ssh +(SCP SFTP) Enables built-in SSH compression. +This is a request, not an order; the server may or may not do it. +.Pp +Added in 7.56.0. +.It Fl -compressed +(HTTP) Request a compressed response using one of the algorithms curl supports, and +save the uncompressed document. If this option is used and the server sends +an unsupported encoding, curl will report an error. +.It Fl K Ar <file> | -config <file> +Specify a text file to read curl arguments from. The command line +arguments found in the text file will be used as if they were provided +on the command line. +.Pp +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. +.Pp +If the parameter contains whitespace (or starts with : or =), the parameter +must be enclosed within quotes. 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 column of a config line is +a '#' character, the rest of the line will be treated as a comment. Only write +one option per physical line in the config file. +.Pp +Specify the filename to +.Fl K |-config +as '-' to make curl read the file from stdin. +.Pp +Note that to be able to specify a URL in the config file, you need to specify +it using the +.Fl -url +option, and not by simply writing the URL on its own line. +So, it could look similar to this: +.Pp +.Dl url = "https://curl.haxx.se/docs/" +.Pp +When curl is invoked, it (unless +.Fl q | -disable +is used) checks for a default config file and uses it if found. +The default config file is checked for in the following places in this order: +.Pp +1) curl tries to find the "home dir": It first checks for the CURL_HOME and +then the HOME environment variables. Failing that, it uses +.Fn getpwuid +on Unix-like systems (which returns the home directory given the +current user in your system). On Windows, it then checks for the +.Ev APPDATA +variable, or as a last resort the '%USERPROFILE%\\Application Data'. +.Pp +2) On windows, if there is no _curlrc file in the home dir, it checks for one +in the same dir the curl executable is placed. On Unix-like systems, it will +simply try to load .curlrc from the determined home dir. +.Bd -literal -offset indent -compact +# --- 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 --- +.Ed +This option can be used multiple times to load multiple config files. +.It Fl -connect-timeout Ar <seconds> +Maximum time in seconds that you allow curl's connection to take. +This only limits the connection phase, so if curl connects within the +given period it will continue - if not it will exit. Since version +7.32.0, this option accepts decimal values. +.Pp +If this option is used several times, the last one will be used. +.Pp +See also +.Fl m | -max-time . +.It Fl -connect-to Ar <HOST1:PORT1:HOST2:PORT2> +For a request to the given HOST1:PORT1 pair, connect to HOST2:PORT2 +instead. This option is suitable to direct requests at a specific +server, e.g. at a specific cluster node in a cluster of servers. This +option is only used to establish the network connection. It does NOT +affect the hostname/port that is used for TLS/SSL (e.g. SNI, +certificate verification) or for the application protocols. "HOST1" +and "PORT1" may be the empty string, meaning "any host/port". "HOST2" +and "PORT2" may also be the empty string, meaning "use the request's +original host/port". +.Pp +A "host" 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". +.Pp +This option can be used many times to add many connect rules. +.Pp +See also +.Fl -resolve +and +.Fl H | -header . +Added in 7.49.0. +.It Fl C Ar <offset> | Fl -continue-at Ar <offset> +Continue/Resume a previous file transfer at the given offset. The +given offset is the exact number of bytes that will be skipped, +counting from the beginning of the source file before it is +transferred to the destination. If used with uploads, the FTP server +command SIZE will not be used by curl. +.Pp +Use "-C -" to tell curl to automatically find out where/how to resume the +transfer. It then uses the given output/input files to figure that out. +.Pp +If this option is used several times, the last one will be used. +.Pp +See also +.Fl r | -range . +.It Fl c Ar <filename> | Fl -cookie-jar Ar <filename> +(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. If no +cookies are known, no data will be written. The file will be written +using the Netscape cookie file format. If you set the file name to a +single dash, "-", the cookies will be written to stdout. +.Pp +This command line option will activate the cookie engine that makes +curl record and use cookies. Another way to activate it is to use the +.Fl b | -cookie +option. +.Pp +If the cookie jar can't be created or written to, the whole curl +operation won't fail or even report an error clearly. Using +.Fl v | -verbose +will get a warning displayed, but that is the only +visible feedback you get about this possibly lethal situation. +.Pp +If this option is used several times, the last specified file name +will be used. +.It Fl b Ar <data|filename> | Fl -cookie Ar <data|filename> +(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". +.Pp +If no '=' symbol is used in the argument, it is instead treated as a +filename to read previously stored cookie from. This option also +activates the cookie engine which will make curl record incoming +cookies, which may be handy if you're using this in combination with +the +.Fl L | -location +option or do multiple URL transfers on the +same invoke. If the file name is exactly a minus ("-"), curl will +instead the contents from stdin. +.Pp +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. +.Pp +The file specified with +.Fl b | -cookie +is only used as input. No cookies will be written to the file. To +store cookies, use the +.Fl c | -cookie-jar +option. +.Pp +Exercise caution if you are using this option and multiple transfers +may occur. If you use the NAME1=VALUE1; format, or in a file use the +Set-Cookie format and don't specify a domain, then the cookie is sent +for any domain (even after redirects are followed) and cannot be +modified by a server-set cookie. If the cookie engine is enabled and a +server sets a cookie of the same name then both will be sent on a +future transfer to that server, likely not what you intended. To +address these issues set a domain in Set-Cookie (doing that will +include sub domains) or use the Netscape format. +.Pp +If this option is used several times, the last one will be used. +.Pp +Users very often want to both read cookies from a file and write updated +cookies back to a file, so using both +.Fl b | -cookie +and +.Fl c | -cookie-jar +in the same command line is common. +.It Fl -create-dirs +When used in conjunction with the +.Fl o | -output +option, curl will create the necessary local directory hierarchy as +needed. This option creates the dirs mentioned with the +.Fl o | -output +option, nothing else. If the +.Fl -output +file name uses no dir or if the dirs it mentions already exist, no dir +will be created. +.Pp +To create remote directories when using FTP or SFTP, try +.Fl -ftp-create-dirs . +.It Fl -crlf +(FTP SMTP) Convert LF to CRLF in upload. Useful for MVS (OS/390). +.Pp +(SMTP added in 7.40.0) +.It Fl -crlfile Ar <file> +(TLS) Provide a file using PEM format with a Certificate Revocation +List that may specify peer certificates that are to be considered +revoked. +.Pp +If this option is used several times, the last one will be used. +.Pp +Added in 7.19.7. +.It Fl -data-ascii Ar <data> +(HTTP) This is just an alias for +.Fl d | -data . +.It Fl -data-binary Ar <data> +(HTTP) This posts data exactly as specified with no extra processing +whatsoever. +.Pp +If you start the data with the letter @, the rest should be a +filename. Data is posted in a similar manner as +.Fl d | -data +does, except that newlines and carriage returns are preserved and +conversions are never done. +.Pp +Like +.Fl d | -data +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: +.Pp +.Dl -H "Content-Type: application/octet-stream". +.Pp +If this option is used several times, the ones following the first +will append data as described in +.Fl d | -data . +.It Fl -data-raw Ar <data> +(HTTP) This posts data similarly to +.Fl d | -data +but without the special interpretation of the @ character. +.Pp +See also \fI-d, --data\fP. Added in 7.43.0. +.It Fl -data-urlencode Ar <data> +(HTTP) This posts data, similar to the other \fI-d, --data\fP options +with the exception that this performs URL-encoding. +.Pp +To be CGI-compliant, the <data> part should begin with a \fIname\fP +followed by a separator and a content specification. The <data> part +can be passed to curl using one of the following syntaxes: +.Bl -tag -width indent +.It content +This will make curl URL-encode the content and pass that on. Just be +careful so that the content doesn't contain any = or @ symbols, as +that will then make the syntax match one of the other cases below! +.It =content +This will make curl URL-encode the content and pass that on. The +preceding = symbol is not included in the data. +.It name=content +This will make curl URL-encode the content part and pass that on. Note +that the name part is expected to be URL-encoded already. +.It @filename +This will make curl load data from the given file (including any +newlines), URL-encode that data and pass it on in the POST. +.It name@filename +This will make curl load data from the given file (including any +newlines), URL-encode that data and pass it on in the POST. The name +part gets an equal sign appended, resulting in +\fIname=urlencoded-file-content\fP. Note that the name is expected to +be URL-encoded already. +.El +See also \fI-d, --data\fP and \fI--data-raw\fP. Added in 7.18.0. +.It Fl d Ar data | Fl -data Ar data +(HTTP) Sends the specified data in a POST request to the HTTP server, +in the same way that a browser does when a user has filled in an HTML +form and presses the submit button. This will cause curl to pass the +data to the server using the content-type +application/x-www-form-urlencoded. Compare to \fI-F, --form\fP. +.Pp +\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. +.Pp +If any of these options is used more than once on the same command +line, the data pieces specified will be merged together with a +separating &-symbol. Thus, using '-d name=daniel -d skill=lousy' would +generate a post chunk that looks like \&'name=daniel&skill=lousy'. +.Pp +If you start the data with the letter @, the rest should be a file +name to read the data from, or - if you want curl to read the data +from stdin. Multiple files can also be specified. Posting data from a +file named 'foobar' would thus be done with +.Fl d , -data Ar @foobar . +When +.Fl -data +is told to read from a file like that, carriage returns and newlines +will be stripped out. If you don't want the @ character to have a +special interpretation use \fI--data-raw\fP instead. +.Pp +See also \fI--data-binary\fP and \fI--data-urlencode\fP and +\fI--data-raw\fP. This option overrides \fI-F, --form\fP and \fI-I, +--head\fP and \fI-T, --upload-file\fP. +.It Fl -delegation Ar LEVEL +(GSS/kerberos) Set LEVEL to tell the server what it is allowed to +delegate when it comes to user credentials. +.Bl -tag -width indent +.It none +Don't allow any delegation. +.It 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. +.It always +Unconditionally allow the server to delegate. +.El +.It Fl -digest +(HTTP) Enables HTTP Digest authentication. This is an authentication +scheme that prevents the password from being sent over the wire in +clear text. Use this in combination with the normal \fI-u, --user\fP +option to set user name and password. +.Pp +If this option is used several times, only the first one is used. +.Pp +See also \fI-u, --user\fP and \fI--proxy-digest\fP and +\fI--anyauth\fP. This option overrides \fI--basic\fP and \fI--ntlm\fP +and \fI--negotiate\fP. +.It Fl -disable-eprt +(FTP) Tell curl to disable the use of the EPRT and LPRT commands when +doing active FTP transfers. Curl will normally always first attempt to +use EPRT, then LPRT before using PORT, but with this option, it will +use PORT right away. EPRT and LPRT are extensions to the original FTP +protocol, and may not work on all servers, but they enable more +functionality in a better way than the traditional PORT command. +.Pp +.Fl -eprt +can be used to explicitly enable EPRT again and +.Fl -no-eprt +is an alias for +.Fl -disable-eprt . +.Pp +If the server is accessed using IPv6, this option will have no effect +as EPRT is necessary then. +.Pp +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. +.It Fl -disable-epsv +(FTP) (FTP) Tell curl to disable the use of the EPSV command when +doing passive FTP transfers. Curl will normally always first attempt +to use EPSV before PASV, but with this option, it will not try using +EPSV. +.Pp +--epsv can be used to explicitly enable EPSV again and --no-epsv is an +alias for \fI--disable-epsv\fP. +.Pp +If the server is an IPv6 host, this option will have no effect as EPSV +is necessary then. +.Pp +Disabling EPSV only changes the passive behavior. If you want to +switch to active mode you need to use \fI-P, --ftp-port\fP. +.It Fl q | -disable +If used as the first parameter on the command line, the \fIcurlrc\fP +config file will not be read and used. See the \fI-K, --config\fP for +details on the default config file search path. +.It Fl -disallow-username-in-url +(HTTP) This tells curl to exit if passed a url containing a username. +.Pp +See also +.Fl -proto . +Added in 7.61.0. +.It Fl -dns-interface Ar <interface> +(DNS) Tell curl to send outgoing DNS requests through +.Ar <interface> . +This option is a counterpart to +.Fl -interface +(which does not affect DNS). The supplied string must be an interface +name (not an address). +.Pp +See also +.Fl -dns-ipv4-addr +and +.Fl -dns-ipv6-addr . +.Fl -dns-interface +requires that the underlying libgnurl was built to support c-ares. +Added in 7.33.0. +.It Fl -dns-ipv4-addr Ar <address> +(DNS) Tell curl to bind to +.Ar <ip-address> +when making IPv4 DNS requests, so that the DNS requests originate from +this address. The argument should be a single IPv4 address. +.Pp +See also +.Fl -dns-interface +and +.Fl -dns-ipv6-addr . +.Fl -dns-ipv4-addr +requires that the underlying libgnurl was built to support c-ares. +Added in 7.33.0. +.It Fl -dns-ipv6-addr Ar <address> +(DNS) Tell curl to bind to +.Ar <ip-address> +when making IPv6 DNS requests, so that the DNS requests originate from +this address. The argument should be a single IPv6 address. +.Pp +See also \fI--dns-interface\fP and +\fI--dns-ipv4-addr\fP. \fI--dns-ipv6-addr\fP requires that the +underlying libgnurl was built to support c-ares. Added in 7.33.0. +.It Fl -dns-servers Ar <addresses> +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 as \fI:<port-number>\fP after each IP +address. +.Pp +.Fl -dns-servers +requires that the underlying libgnurl was built to support c-ares. +Added in 7.33.0. +.It Fl -doh-url <URL> +(all) 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. +.Pp +If this option is used several times, the last one will be used. +.It Fl D Ar <filename> | Fl -dump-header Ar <filename> +(HTTP FTP) Write the received protocol headers to the specified file. +.Pp +This option is handy to use when you want to store the headers that an +HTTP site sends to you. Cookies from the headers could then be read in +a second curl invocation by using the +.Fl b | -cookie +option! The +.Fl c | -cookie-jar +option is a better way to store cookies. +.Pp +If no headers are received, the use of this option will create an empty file. +.Pp +When used in FTP, the FTP server response lines are considered being +"headers" and thus are saved there. +.Pp +If this option is used several times, the last one will be used. +.Pp +See also +.Fl o | -output . +.It Fl -egd-file Ar <file> +(TLS) Specify the path name to the Entropy Gathering Daemon +socket. The socket is used to seed the random engine for SSL +connections. +.Pp +See also +.Fl -random-file . +.It Fl -engine Ar <name> +(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 (or +none) of the engines may be available at run-time. +.It Fl -expect100-timeout Ar <seconds> +(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 will wait one second. This option +accepts decimal values! When curl stops waiting, it will continue as +if the response has been received. +.Pp +See also +.Fl -connect-timeout . +Added in 7.47.0. +.It Fl -fail-early +Fail and exit on the first detected transfer error. +.Pp +When curl is used to do multiple transfers on the command line, it +will attempt to operate on each given URL, one by one. By default, it +will ignore errors if there are more URLs given and the last URL's +success will determine the error code curl returns. So early failures +will be "hidden" by subsequent successful transfers. +.Pp +Using this option, curl will instead return an error on the first +transfer that fails, independent of the amount of URLs that are given +on the command line. This way, no transfer failures go undetected by +scripts and similar. +.Pp +This option is global and does not need to be specified for each use +of +.Fl : | -next . +.Pp +This option does not imply +.Fl f | -fail , +which causes transfers to fail due to the server's HTTP status +code. You can combine the two options, however note +.Fl f | -fail +is not global and is therefore contained by +.Fl : | -next . +.Pp +Added in 7.52.0. +.It Fl f | -fail +(HTTP) Fail silently (no output at all) on server errors. This is +mostly done to better enable scripts etc to better deal with failed +attempts. In normal cases when an HTTP server fails to deliver a +document, it returns an HTML document stating so (which often also +describes why and more). This flag will prevent curl from outputting +that and return error 22. +.Pp +This method is not fail-safe and there are occasions where +non-successful response codes will slip through, especially when +authentication is involved (response codes 401 and 407). +.It Fl -false-start +(TLS) Tells curl to use false start during the TLS handshake. False +start is a mode where a TLS client will start sending application data +before verifying the server's Finished message, thus saving a round +trip when performing a full handshake. +.Pp +This is currently only implemented in the NSS and Secure Transport (on +iOS 7.0 or later, or OS X 10.9 or later) backends. +.Pp +Added in 7.42.0. +.It Fl -form-string Ar <name=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 +.Fl F | -form +if there's any possibility that the string value may accidentally +trigger the \&'@' or \&'<' features of +.Fl F | -form . +.Pp +See also +.Fl F | -form . +.It Fl F Ar <name=content> | -form Ar <name=content> +(HTTP SMTP IMAP) For HTTP protocol family, this lets curl emulate a +filled-in form in which a user has pressed the submit button. This +causes curl to POST data using the Content-Type multipart/form-data +according to RFC 2388. +.Pp +For SMTP and IMAP protocols, this is the mean to compose a multipart +mail message to transmit. +.Pp +This enables uploading of binary files etc. To force the 'content' +part to be a file, prefix the file name with an @ sign. To just get +the content part from a file, prefix the file name 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. +.Pp +Tell curl to read content from stdin instead of a file by using - as +filename. This goes for both @ and < constructs. When stdin is used, +the contents is buffered in memory first by curl to determine its size +and allow a possible resend. Defining a part's data from a named +non-regular file (such as a named pipe or similar) is unfortunately +not subject to buffering and will be effectively read at transmission +time; since the full size is unknown before the transfer starts, such +data is sent as chunks by HTTP and rejected by IMAP. +.Pp +Example: send an image to an HTTP server, where \&'profile' is the +name of the form-field to which the file portrait.jpg will be the +input: +.Pp +.Dl curl -F profile=@portrait.jpg https://example.com/upload.cgi +.Pp +Example: send a your name and shoe size in two text fields to the server: +.Pp +.Dl curl -F name=John -F shoesize=11 https://example.com/ +.Pp +Example: send a 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: +.Pp +.Dl curl -F \(dqstory=<hugefile.txt\(dq https://example.com/ +.Pp +You can also tell curl what Content-Type to use by using 'type=', in a +manner similar to: +.Pp +.Dl curl -F \(dqweb=@index.html;type=text/html\(dq example.com +.Pp +or +.Pp +.Dl curl -F \(dqname=daniel;type=text/foo\(dq example.com +.Pp +You can also explicitly change the name field of a file upload part by +setting filename=, like this: +.Pp +.Dl curl -F \(dqfile=@localfile;filename=nameinpost\(dq example.com +.Pp +If filename/path contains ',' or ';', it must be quoted by double-quotes like: +.Pp +.\" We want this to render: +.\" curl -F "file=@\"localfile\";filename=\"nameinpost\"" example.com +.\" might be useful for reference: cc.1 +.Dl curl -F \(dqfile=@\e\(dqlocalfile\e\(dq\&;filename=\e\(dqnameinpost\e\(dq\(dq example.com +.Pp +or +.Pp +.Dl curl -F 'file=@"localfile";filename="nameinpost"' example.com +.Pp +Note that if a filename/path is quoted by double-quotes, any +double-quote or backslash within the filename must be escaped by +backslash. +.Pp +Quoting must also be applied to non-file data if it contains semicolons, +leading/trailing spaces or leading double quotes: +.Pp +.Dl curl -F 'colors="red; green; blue";type=text/x-myapp' example.com +.Pp +You can add custom headers to the field by setting headers=, like +.Pp +.Dl curl -F \(dqsubmit=OK;headers=\e\(dqX-submit-type: OK\e\(dq\(dq example.com +.Pp +or +.Pp +.Dl curl -F \(dqsubmit=OK;headers=@headerfile\(dq example.com +.Pp +The headers= keyword may appear more that once and above notes about +quoting apply. When headers are read from a file, Empty lines and +lines starting with '#' are comments and ignored; each header can be +folded by splitting between two words and starting the continuation +line with a space; embedded carriage-returns and trailing spaces are +stripped. Here is an example of a header file contents: +.Bd -literal -offset indent -compact + # This file contain two headers. + X-header-1: this is a header + + # The following header is folded. + X-header-2: this is + another header +.Ed +To support sending multipart mail messages, the syntax is extended as +follows: +.Bl -bullet -offset indent -compact +.It +name can be omitted: the equal sign is the first character of the argument, +.It +if data starts with '(', this signals to start a new multipart: it can +be followed by a content type specification. +.It +a multipart can be terminated with a '=)' argument. +.El +Example: the following command sends an SMTP mime e-mail consisting in +an inline part in two alternative formats: plain text and HTML. It +attaches a text file: +.Bd -literal -offset indent -compact + curl -F '=(;type=multipart/alternative' \\ + -F '=plain text message' \\ + -F '= <body>HTML message</body>;type=text/html' \\ + -F '=)' -F '=@textfile.txt' ... smtp://example.com +.Ed +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. +.Pp +Example: send multipart mail with a quoted-printable text message and +a base64 attached file: +.Bd -literal -offset indent -compact + curl -F '=text message;encoder=quoted-printable' \\ + -F '=@localfile;encoder=base64' ... smtp://example.com +.Ed +See further examples and details in the MANUAL. +.Pp +This option can be used multiple times. +.Pp +This option overrides +.Fl d | -data +and +.Fl I | -head +and +.Fl T | -upload-file . +.It Fl -ftp-account Ar <data> +(FTP) When an FTP server asks for "account data" after user name and +password has been provided, this data is sent off using the ACCT +command. +.Pp +If this option is used several times, the last one will be used. +.Pp +Added in 7.13.0. +.It Fl -ftp-alternative-to-user Ar <command> +(FTP) If authenticating with the USER and PASS commands fails, send +this command. When connecting to Tumbleweed's Secure Transport server +over FTPS using a client certificate, using "SITE AUTH" will tell the +server to retrieve the username from the certificate. +.Pp +Added in 7.15.5. +.It Fl -ftp-create-dirs +(FTP SFTP) When an FTP or SFTP URL/operation uses a path that doesn't +currently exist on the server, the standard behavior of curl is to +fail. Using this option, curl will instead attempt to create missing +directories. +.Pp +See also +.Fl -create-dirs . +.It Fl -ftp-method Ar <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: +.Bl -tag -width indent +.It multicwd +curl does a single CWD operation for each path part in the given +URL. For deep hierarchies this means very many commands. This is how +RFC 1738 says it should be done. This is the default but the slowest +behavior. +.It nocwd +curl does no CWD at all. curl will do SIZE, RETR, STOR etc and give a +full path to the server for all these commands. This is the fastest +behavior. +.It singlecwd +curl does one CWD with the full target directory and then operates on +the file \&"normally" (like in the multicwd case). This is somewhat +more standards compliant than 'nocwd' but without the full penalty +of 'multicwd'. +.El +Added in 7.15.1. +.It Fl -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 +.Fl P | -ftp-port +option. +.Pp +If this option is used several times, only the first one is +used. Undoing an enforced passive really isn't doable but you must +then instead enforce the correct +.Fl P | -ftp-port +again. +.Pp +Passive mode means that curl will try the EPSV command first and then +PASV, unless +.Fl -disable-epsv +is used. +.Pp +See also +.Fl -disable-epsv . +Added in 7.11.0. +.It Fl P Ar <address> | -ftp-port Ar <address> +(FTP) Reverses the default initiator/listener roles when connecting +with FTP. This option makes curl use active mode. curl then tells the +server to connect back to the client's specified address and port, +while passive mode asks the server to setup an IP address and port for +it to connect to. +.Ar <address> +should be one of: +.Bl -tag -width indent +.It interface +e.g. "eth0" to specify which interface's IP address you want to use (Unix only) +.It IP address +e.g. "192.168.10.1" to specify the exact IP address +.It host name +e.g. "my.host.domain" to specify the machine +.It "-" +make curl pick the same IP address that is already used for the +control connection +.El +If this option is used several times, the last one will be +used. Disable the use of PORT with +.Fl -ftp-pasv . +Disable the attempt to use the EPRT command instead of PORT by using +.Fl -disable-eprt . +EPRT is really PORT++. +.Pp +Since 7.19.5, you can 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. +.Pp +See also +.Fl -ftp-pasv +and +.Fl -disable-eprt . +.It Fl -ftp-pret +(FTP) Tell curl to 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. +.Pp +Added in 7.20.0. +.It Fl -ftp-skip-pasv-ip +(FTP) Tell curl to not use the IP address the server suggests in its +response to curl's PASV command when curl connects the data +connection. Instead curl will re-use the same IP address it already +uses for the control connection. +.Pp +This option has no effect if PORT, EPRT or EPSV is used instead of PASV. +.Pp +See also +.Fl -ftp-pasv . +Added in 7.14.2. +.It Fl -ftp-ssl-ccc-mode Ar <active/passive> +(FTP) Sets the CCC mode. The passive mode will not initiate the +shutdown, but instead wait for the server to do it, and will not reply +to the shutdown from the server. The active mode initiates the +shutdown and waits for a reply from the server. +.Pp +See also +.Fl -ftp-ssl-ccc . +Added in 7.16.2. +.It Fl -ftp-ssl-ccc +(FTP) Use CCC (Clear Command Channel) Shuts down the SSL/TLS layer +after authenticating. The rest of the control channel communication +will be unencrypted. This allows NAT routers to follow the FTP +transaction. The default mode is passive. +.Pp +See also +.Fl -ssl +and +.Fl -ftp-ssl-ccc-mode . +Added in 7.16.1. +.It Fl -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 doesn't support SSL/TLS. +.Pp +Added in 7.16.0. +.It Fl G | -get +When used, this option will make all data specified with +.Fl d , +.Fl -data , +.Fl -data-binary +or +.Fl -data-urlencode +to be used in an HTTP GET request instead of the POST request that +otherwise would be used. The data will be appended to the URL with +a '?' separator. +.Pp +If used in combination with +.Fl I | -head , +the POST data will instead be appended to the URL with a HEAD request. +.Pp +If this option is used several times, only the first one is used. This +is because undoing a GET doesn't make sense, but you should then +instead enforce the alternative method you prefer. +.It Fl g | -globoff +This option switches off the "URL globbing parser". When you set this option, +you can specify URLs that contain the letters {}[] without having them being +interpreted by curl itself. Note that these letters are not normal legal URL +contents but they should be encoded according to the URI standard. +.It Fl -happy-eyeballs-timeout-ms Ar milliseconds +Happy eyeballs is an algorithm that attempts to connect to both IPv4 +and IPv6 addresses for dual-stack hosts, preferring IPv6 first for the +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. +.Pp +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. +.Pp +If this option is used several times, the last one will be used. +.Pp +Added in 7.59.0. +.It Fl -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's true IP address and port. +.Pp +This option is primarily useful when sending test requests to a +service that expects this header. +.Pp +Added in 7.60.0. +.It Fl 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. +.It Fl H Ar <header/@file> | -header Ar <header/@file> +(HTTP) Extra header to include in the request when sending HTTP to a +server. You may specify any number of extra headers. Note that if you +should add a custom header that has the same name as one of the +internal ones curl would use, your externally set header will be used +instead of the internal one. This allows you to make even trickier +stuff than curl would normally do. You should not replace internally +set headers without knowing perfectly well what you're 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 +.Fl H +\&"X-Custom-Header;" to send "X-Custom-Header:". +.Pp +curl will make 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 will only mess things up for you. +.Pp +Starting in 7.55.0, this option can take an argument in @filename +style, which then adds a header for each line in the input file. Using +@- will make curl read the header file from stdin. +.Pp +See also the +.Fl A , +.Fl -user-agent +and +.Fl e , +.Fl -referer +options. +.Pp +Starting in 7.37.0, you need +.Fl -proxy-header +to send custom headers intended for a proxy. +.Pp +Example: +.Pp +.Dl curl -H "X-First-Name: Joe" http://example.com/ +.Pp +\fBWARNING\fP: headers set with this option will be set in all +requests - even after redirects are followed, like when told with +.Fl L | -location . +This can lead to the header being sent to other hosts than the +original host, so sensitive headers should be used with caution +combined with following redirects. +.Pp +This option can be used multiple times to add/replace/remove multiple +headers. +.It Fl h | -help +Usage help. This lists all current command line options with a short +description. +.It Fl -hostpubmd5 Ar <md5> +(SFTP SCP) Pass a string containing 32 hexadecimal digits. The string +should be the 128 bit MD5 checksum of the remote host's public key, +curl will refuse the connection with the host unless the md5sums +match. +.Pp +Added in 7.17.1. +.It Fl -http0.9 +(HTTP) Tells curl to be fine with HTTP version 0.9 response. +.Pp +HTTP/0.9 is a completely headerless response and therefore you can +also connect with this to non-HTTP servers and still get a response +since curl will simply transparently downgrade - if allowed. +.Pp +A future curl version will deny continuing if the response isn't at +least HTTP/1.0 unless this option is used. +.It Fl 0 | -http1.0 +(HTTP) Tells curl to use HTTP version 1.0 instead of using its +internally preferred HTTP version. +.Pp +This option overrides +.Fl -http1.1 +and +.Fl -http2 . +.It Fl -http1.1 +(HTTP) Tells curl to use HTTP version 1.1. +.Pp +This option overrides +.Fl 0 | --http1.0 +and +.Fl -http2 . +Added in 7.33.0. +.It Fl -http2-prior-knowledge +(HTTP) Tells curl to issue its non-TLS HTTP requests using HTTP/2 +without HTTP/1.1 Upgrade. It requires prior knowledge that the server +supports HTTP/2 straight away. HTTPS requests will still do HTTP/2 the +standard way with negotiated protocol version in the TLS handshake. +.Pp +.Fl -http2-prior-knowledge +requires that the underlying libgnurl was built to support +HTTP/2. This option overrides +.Fl -http1.1 +and +.Fl 0 | -http1.0 +and +.Fl -http2 . +Added in 7.49.0. +.It Fl -http2 +(HTTP) Tells curl to use HTTP version 2. +.Pp +See also \fI--no-alpn\fP. \fI--http2\fP requires that the underlying libgnurl was built to support HTTP/2. This option overrides \fI--http1.1\fP and \fI-0, --http1.0\fP and \fI--http2-prior-knowledge\fP. Added in 7.33.0. +.It Fl -ignore-content-length +(FTP HTTP) For HTTP, Ignore the Content-Length header. This is particularly useful for +servers running Apache 1.x, which will report incorrect Content-Length for +files larger than 2 gigabytes. +.Pp +For FTP (since 7.46.0), skip the RETR command to figure out the size before +downloading a file. +.It Fl i | -include +Include the HTTP response headers in the output. The HTTP response +headers can include things like server name, cookies, date of the +document, HTTP version and more... +.Pp +To view the request headers, consider the \fI-v, --verbose\fP option. +.Pp +See also \fI-v, --verbose\fP. +.It Fl k | -insecure +(TLS) By default, every SSL connection curl makes is verified to be +secure. This option allows curl to proceed and operate even for server +connections otherwise considered insecure. +.Pp +The server connection is verified by making sure the server's +certificate contains the right name and verifies successfully using +the cert store. +.Pp +See this online resource for further details: +.Lk https://curl.haxx.se/docs/sslcerts.html +.Pp +See also \fI--proxy-insecure\fP and \fI--cacert\fP. +.It Fl -interface Ar <name> +Perform an operation using a specified interface. You can enter +interface name, IP address or host name. An example could look like: +.Pp +.Dl curl --interface eth0:1 https://www.example.com/ +.Pp +If this option is used several times, the last one will be used. +.Pp +On Linux it can be used to specify a VRF, but the binary needs to +either have CAP_NET_RAW or to be run as root. More information about +Linux VRF: +.Lk https://www.kernel.org/doc/Documentation/networking/vrf.txt +.Pp +See also \fI--dns-interface\fP. +.It Fl 4 | -ipv4 +This option tells curl to resolve names to IPv4 addresses only, and +not for example try IPv6. +.Pp +See also \fI--http1.1\fP and \fI--http2\fP. This option overrides +\fI-6, --ipv6\fP. +.It Fl 6 | -ipv6 +This option tells curl to resolve names to IPv6 addresses only, and +not for example try IPv4. +.Pp +See also \fI--http1.1\fP and \fI--http2\fP. This option overrides +\fI-4, --ipv4\fP. +.It Fl j | -junk-session-cookies +(HTTP) When curl is told to read cookies from a given file, this +option will make it discard all "session cookies". This will basically +have the same effect as if a new session is started. Typical browsers +always discard session cookies when they're closed down. +.Pp +See also \fI-b, --cookie\fP and \fI-c, --cookie-jar\fP. +.It Fl -keepalive-time Ar <seconds> +This option sets 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). This option has no effect if +\fI--no-keepalive\fP is used. +.Pp +If this option is used several times, the last one will be used. If +unspecified, the option defaults to 60 seconds. +.Pp +Added in 7.18.0. +.It Fl -key-type Ar <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. +.Pp +If this option is used several times, the last one will be used. +.It Fl -key Ar <key> +(TLS SSH) Private key file name. Allows you to provide your private +key in this separate file. For SSH, if not specified, curl tries the +following candidates in order: +.Pa ~/.ssh/id_rsa , +.Pa ~/.ssh/id_dsa , +.Pa ./id_rsa , +.Pa ./id_dsa . +.Pp +If curl is built against OpenSSL library, and the engine pkcs11 is +available, then a PKCS#11 URI (RFC 7512) can be used to specify a +private key located in a PKCS#11 device. A string beginning with +"pkcs11:" will be interpreted as a PKCS#11 URI. If a PKCS#11 URI is +provided, then the \fI--engine\fP option will be set as "pkcs11" if +none was provided and the \fI--key-type\fP option will be set as "ENG" +if none was provided. +.Pp +If this option is used several times, the last one will be used. +.It Fl -krb Ar <level> +(FTP) Enable Kerberos authentication and use. The level must be +entered and should be one of 'clear', 'safe', 'confidential', +or 'private'. Should you use a level that is not one of +these, 'private' will instead be used. +.Pp +If this option is used several times, the last one will be used. +.Pp +\fI--krb\fP requires that the underlying libgnurl was built to support +Kerberos. +.It Fl -libcurl Ar <file> +Append this option to any ordinary curl command line, and you will get +a libcurl-using C source code written to the file that does the +equivalent of what your command-line operation does! +.Pp +If this option is used several times, the last given file name will be +used. +.Pp +Added in 7.16.1. +.It Fl -limit-rate Ar <speed> +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'd like your transfer not to use your entire bandwidth. To +make it slower than it otherwise would be. +.Pp +The given speed is measured in bytes/second, unless a suffix is +appended. Appending 'k' or 'K' will count the number as +kilobytes, 'm' or 'M' makes it megabytes, while 'g' or 'G' makes it +gigabytes. Examples: 200K, 3m and 1G. +.Pp +If you also use the \fI-Y, --speed-limit\fP option, that option will +take precedence and might cripple the rate-limiting slightly, to help +keeping the speed-limit logic working. +.Pp +If this option is used several times, the last one will be used. +.It Fl l | -list-only +(FTP POP3) (FTP) When listing an FTP directory, this switch forces a +name-only view. This is especially useful if the user wants to +machine-parse the contents of an FTP directory since the normal +directory view doesn't use a standard look or format. When used like +this, the option causes a NLST command to be sent to the server +instead of LIST. +.Pp +Note: Some FTP servers list only files in their response to NLST; they +do not include sub-directories and symbolic links. +.Pp +(POP3) 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. +.Pp +Note: When combined with +.Fl X , +.Fl -request , +this option can be used to send an UIDL command instead, so the user +may use the email's unique identifier rather than it's message id to +make the request. +.Pp +Added in 7.21.5. +.It Fl -local-port Ar <num/range> +Set a preferred single number or range (FROM-TO) of local port numbers +to use for the connection(s). Note that port numbers by nature are a +scarce resource that will be busy at times so setting this range to +something too narrow might cause unnecessary connection setup +failures. +.Pp +Added in 7.15.2. +.It Fl -location-trusted +(HTTP) Like \fI-L, --location\fP, but will allow sending the name + +password to all hosts that the site may redirect to. This may or may +not introduce a security breach if the site redirects you to a site to +which you'll send your authentication info (which is plaintext in the +case of HTTP Basic authentication). +.Pp +See also \fI-u, --user\fP. +.It Fl 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 will make 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 will be shown. When authentication is +used, curl only sends its credentials to the initial host. If a +redirect takes curl to a different host, it won't be able to intercept +the user+password. See also \fI--location-trusted\fP on how to change +this. You can limit the amount of redirects to follow by using the +\fI--max-redirs\fP option. +.Pp +When curl follows a redirect and the request is not a plain GET (for +example POST or PUT), it will do the following request with a GET if +the HTTP response was 301, 302, or 303. If the response code was any +other 3xx code, curl will re-send the following request using the same +unmodified method. +.Pp +You can tell curl to not change the non-GET request method to GET +after a 30x response by using the dedicated options for that: +\fI--post301\fP, \fI--post302\fP and \fI--post303\fP. +.It Fl -login-options Ar <options> +(IMAP POP3 SMTP) Specify the login options to use during server +authentication. +.Pp +You can use the 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 the login +options please see RFC 2384, RFC 5092 and IETF draft +draft-earhart-url-smtp-00.txt +.Pp +If this option is used several times, the last one will be used. +.Pp +Added in 7.34.0. +.It Fl -mail-auth Ar <address> +(SMTP) Specify a single address. This will be used to specify the +authentication address (identity) of a submitted message that is being +relayed to another server. +.Pp +See also \fI--mail-rcpt\fP and \fI--mail-from\fP. Added in 7.25.0. +.It Fl -mail-from Ar <address> +(SMTP) Specify a single address that the given mail should get sent +from. +.Pp +See also \fI--mail-rcpt\fP and \fI--mail-auth\fP. Added in 7.20.0. +.It Fl -mail-rcpt Ar <address> +(SMTP) Specify a single address, user name or mailing list +name. Repeat this option several times to send to multiple recipients. +.Pp +When performing a mail transfer, the recipient should specify a valid +email address to send the mail to. +.Pp +When performing an address verification (VRFY command), the recipient +should be specified as the user name or user name and domain (as per +Section 3.5 of RFC5321). (Added in 7.34.0) +.Pp +When performing a mailing list expand (EXPN command), the recipient +should be specified using the mailing list name, such as "Friends" or +"London-Office". (Added in 7.34.0) +.Pp +Added in 7.20.0. +.It Fl M | -manual +Manual. Display the huge help text. +.It Fl -max-filesize Ar <bytes> +Specify the maximum size (in bytes) of a file to download. If the file +requested is larger than this value, the transfer will not start and +curl will return with exit code 63. +.Pp +A size modifier may be used. For example, Appending 'k' or 'K' will +count the number as kilobytes, 'm' or 'M' makes it megabytes, +while 'g' or 'G' makes it gigabytes. Examples: 200K, 3m and 1G. (Added +in 7.58.0) +.Pp +\fBNOTE:\fP The file size is not always known prior to download, and +for such files this option has no effect even if the file transfer +ends up being larger than this given limit. This concerns both FTP and +HTTP transfers. +.Pp +See also \fI--limit-rate\fP. +.It Fl -max-redirs Ar <num> +(HTTP) Set maximum number of redirection-followings allowed. When +\fI-L, --location\fP is used, is used to prevent curl from following +redirections too much. By default, the limit is set to 50 +redirections. Set this option to -1 to make it unlimited. +.Pp +If this option is used several times, the last one will be used. +.It Fl m Ar seconds | Fl -max-time seconds +Maximum time in seconds that you allow the whole operation to take. +This is useful for preventing your batch jobs from hanging for hours +due to slow networks or links going down. Since 7.32.0, this option +accepts decimal values, but the actual timeout will decrease in +accuracy as the specified timeout increases in decimal precision. +.Pp +If this option is used several times, the last one will be used. +.Pp +See also \fI--connect-timeout\fP. +.It Fl -metalink +This option can tell curl to parse and process a given URI as Metalink +file (both version 3 and 4 (RFC 5854) are supported) and make use of +the mirrors listed within for failover if there are errors (such as +the file or server not being available). It will also verify the hash +of the file after the download completes. The Metalink file itself is +downloaded and processed in memory and not stored in the local file +system. +.Pp +Example to use a remote Metalink file: +.Pp +.Dl curl --metalink http://www.example.com/example.metalink +.Pp +To use a Metalink file in the local file system, use FILE protocol +(file://): +.Pp +.Dl curl --metalink file://example.metalink +.Pp +Please note that if FILE protocol is disabled, there is no way to use +a local Metalink file at the time of this writing. Also note that if +\fI--metalink\fP and \fI-i, --include\fP are used together, --include +will be ignored. This is because including headers in the response +will break Metalink parser and if the headers are included in the file +described in Metalink file, hash check will fail. +.Pp +\fI--metalink\fP requires that the underlying libgnurl was built to +support metalink. Added in 7.27.0. +.It Fl -negotiate +(HTTP) Enables Negotiate (SPNEGO) authentication. +.Pp +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. +.Pp +When using this option, you must also provide a fake \fI-u, --user\fP +option to activate the authentication code properly. Sending a '-u :' +is enough as the user name and password from the \fI-u, --user\fP +option aren't actually used. +.Pp +If this option is used several times, only the first one is used. +.Pp +See also \fI--basic\fP and \fI--ntlm\fP and \fI--anyauth\fP and +\fI--proxy-negotiate\fP. +.It Fl -netrc-file Ar filename +This option is similar to \fI-n, --netrc\fP, except that you provide +the path (absolute or relative) to the netrc file that curl should +use. You can only specify one netrc file per invocation. If several +\fI--netrc-file\fP options are provided, the last one will be used. +.Pp +It will abide by \fI--netrc-optional\fP if specified. +.Pp +This option overrides \fI-n, --netrc\fP. Added in 7.21.5. +.It Fl -netrc-optional +Very 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. +.Pp +See also \fI--netrc-file\fP. This option overrides \fI-n, --netrc\fP. +.It Fl n | -netrc +Makes curl scan the \fI.netrc\fP (\fI_netrc\fP on Windows) file in the +user's home directory for login name and password. This is typically +used for FTP on Unix. If used with HTTP, curl will enable user +authentication. See \fInetrc(5)\fP \fIftp(1)\fP for details on the +file format. Curl will not complain if that file doesn't have the +right permissions (it should not be either world- or +group-readable). The environment variable "HOME" is used to find the +home directory. +.Pp +A quick and very simple example of how to setup a \fI.netrc\fP to +allow curl to FTP to the machine host.domain.com with user name +\&'myself' and password \&'secret' should look similar to: +.Pp +.Dl "machine host.domain.com login myself password secret" +.It Fl : | -next +Tells curl to 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 user +names or custom requests for each. +.Pp +\fI-:, --next\fP will reset all local options and only global ones +will 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. +.Pp +For example, you can do both a GET and a POST in a single command line: +.Pp +.Dl curl www1.example.com --next -d postthis www2.example.com +.Pp +Added in 7.36.0. +.It Fl -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. +.Pp +See also \fI--no-npn\fP and \fI--http2\fP. \fI--no-alpn\fP requires +that the underlying libgnurl was built to support TLS. Added in +7.36.0. +.It Fl N | -no-buffer +Disables the buffering of the output stream. In normal work +situations, curl will use a standard buffered output stream that will +have the effect that it will output the data in chunks, not +necessarily exactly when the data arrives. Using this option will +disable that buffering. +.Pp +Note that this is the negated option name documented. You can thus use +--buffer to enforce the buffering. +.It Fl -no-keepalive +Disables the use of keepalive messages on the TCP connection. curl +otherwise enables them by default. +.Pp +Note that this is the negated option name documented. You can thus use +--keepalive to enforce keepalive. +.It Fl -no-npn +(HTTPS) 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. +.Pp +See also \fI--no-alpn\fP and \fI--http2\fP. \fI--no-npn\fP requires +that the underlying libgnurl was built to support TLS. Added in +7.36.0. +.It Fl -no-sessionid +(TLS) Disable curl's 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. +.Pp +Note that this is the negated option name documented. You can thus use +--sessionid to enforce session-ID caching. +.Pp +Added in 7.16.0. +.It Fl -noproxy Ar no-proxy-list +Comma-separated list of hosts which do not 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. +.Pp +Since 7.53.0, This option overrides the environment variables that +disable the proxy. If there's an environment variable disabling a +proxy, you can set noproxy list to \&"" to override it. +.Pp +Added in 7.19.4. +.It Fl -ntlm-wb +(HTTP) Enables NTLM much in the style \fI--ntlm\fP does, but hand over +the authentication to the separate binary ntlmauth application that is +executed when needed. +.Pp +See also \fI--ntlm\fP and \fI--proxy-ntlm\fP. +.It Fl -ntlm +(HTTP) Enables 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. +.Pp +If you want to enable NTLM for your proxy authentication, then use +\fI--proxy-ntlm\fP. +.Pp +If this option is used several times, only the first one is used. +.Pp +See also \fI--proxy-ntlm\fP. \fI--ntlm\fP requires that the underlying +libgnurl was built to support TLS. This option overrides \fI--basic\fP +and \fI--negotiate\fP and \fI--digest\fP and \fI--anyauth\fP. +.It Fl -oauth2-bearer Ar token +(IMAP POP3 SMTP) Specify the Bearer Token for OAUTH 2.0 server +authentication. The Bearer Token is used in conjunction with the user +name which can be specified as part of the \fI--url\fP or \fI-u, +--user\fP options. +.Pp +The Bearer Token and user name are formatted according to RFC 6750. +.Pp +If this option is used several times, the last one will be used. +.It Fl o Ar FILE | Fl -output Ar FILE +Write output to +.Ar FILE +instead of stdout. If you are using {} or [] to fetch multiple +documents, you can use '#' followed by a number in the +.Ar file +specifier. That variable will be replaced with the current string for +the URL being fetched. Like in: +.Pp +.Dl curl http://{one,two}.example.com -o "file_#1.txt" +.Pp +or use several variables like: +.Pp +.Dl curl http://{site,host}.host[1-5].com -o "#1_#2" +.Pp +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: +.Pp +.Dl curl -o aa example.com -o bb example.net +.Pp +and the order of the -o options and the URLs doesn't matter, just that +the first -o is for the first URL and so on, so the above command line +can also be written as +.Pp +.Dl curl example.com example.net -o aa -o bb +.Pp +See also the \fI--create-dirs\fP option to create the local +directories dynamically. Specifying the output as '-' (a single dash) +will force the output to be done to stdout. +.Pp +See also \fI-O, --remote-name\fP and \fI--remote-name-all\fP and +\fI-J, --remote-header-name\fP. +.It Fl -pass Ar phrase +(SSH TLS) Passphrase for the private key +.Pp +If this option is used several times, the last one will be used. +.It Fl -path-as-is +Tell curl to not handle sequences of /../ or /./ in the given URL +path. Normally curl will squash or merge them according to standards +but with this option set you tell it not to do that. +.Pp +Added in 7.42.0. +.It Fl -pinnedpubkey Ar <hashes> +(TLS) Tells curl to 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 \'sha256//\' and separated by \';\' +.Pp +When negotiating a TLS or SSL connection, the server sends a +certificate indicating its identity. A public key is extracted from +this certificate and if it does not exactly match the public key +provided to this option, curl will abort the connection before sending +or receiving any data. +.Pp +PEM/DER support: +.Bl -bullet -offset indent -compact +.It +7.39.0: OpenSSL, GnuTLS and GSKit +.It +7.43.0: NSS and wolfSSL/CyaSSL +.It +7.47.0: mbedtls +.El +sha256 support: +.Bl -bullet -offset indent -compact +.It +7.44.0: OpenSSL, GnuTLS, NSS and wolfSSL/CyaSSL. +.It +7.47.0: mbedtls +.El +Other SSL backends not supported. +.Pp +If this option is used several times, the last one will be used. +.It Fl -post301 +(HTTP) Tells curl to respect RFC 7231/6.4.2 and not convert POST +requests into GET requests when following a 301 redirection. The +non-RFC behaviour 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 +.Fl L , +.Fl -location . +.Pp +See also +.Fl -post302 +and +.Fl -post303 +and +.Fl L , +.Fl -location . +Added in 7.17.1. +.It Fl -post302 +(HTTP) Tells curl to respect RFC 7231/6.4.3 and not convert POST +requests into GET requests when following a 302 redirection. The +non-RFC behaviour 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 +.Fl L , +.Fl -location . +.Pp +See also \fI--post301\fP and \fI--post303\fP and \fI-L, +--location\fP. Added in 7.19.1. +.It Fl -post303 +(HTTP) Tells curl to violate RFC 7231/6.4.4 and not convert POST +requests into GET requests when following 303 redirections. 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. +.Pp +See also \fI--post302\fP and \fI--post301\fP and \fI-L, +--location\fP. Added in 7.26.0. +.It Fl -preproxy Ar [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. +.Pp +The pre proxy string should be specified with a protocol:// prefix to +specify alternative proxy protocols. Use socks4://, socks4a://, +socks5:// or socks5h:// to request the specific SOCKS version to be +used. No protocol specified will make curl default to SOCKS4. +.Pp +If the port number is not specified in the proxy string, it is assumed +to be 1080. +.Pp +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. +.Pp +If this option is used several times, the last one will be used. +.Pp +Added in 7.52.0. +.It Fl # | -progress-bar +Make curl display transfer progress as a simple progress bar instead +of the standard, more informational, meter. +.Pp +This progress bar draws a single line of '#' characters across the +screen and shows a percentage if the transfer size is known. For +transfers without a known size, there will be space ship (-=o=-) that +moves back and forth but only while data is being transferred, with a +set of flying hash sign symbols on top. +.It Fl -proto-default Ar <protocol> +Tells curl to use \fIprotocol\fP for any URL missing a scheme name. +.Pp +Example: +.Pp +.Dl curl --proto-default https ftp.mozilla.org +.Pp +An unknown or unsupported protocol causes error +\fICURLE_UNSUPPORTED_PROTOCOL\fP (1). +.Pp +This option does not change the default proxy protocol (http). +.Pp +Without this option curl would make a guess based on the host, see +\fI--url\fP for details. +.Pp +Added in 7.45.0. +.It Fl -proto-redir Ar <protocols> +Tells curl to limit what protocols it may use on redirect. Protocols +denied by \fI--proto\fP are not overridden by this option. See --proto +for how protocols are represented. +.Pp +Example, allow only HTTP and HTTPS on redirect: +.Pp +.Dl curl --proto-redir -all,http,https http://example.com +.Pp +By default curl will allow all protocols on redirect except several +disabled for security reasons: Since 7.19.4 FILE and SCP are disabled, +and since 7.40.0 SMB and SMBS are also disabled. Specifying \fIall\fP +or \fI+all\fP enables all protocols on redirect, including those +disabled for security. +.Pp +Added in 7.20.2. +.It Fl -proto Ar <protocols> +Tells curl to limit what protocols it may use in the +transfer. Protocols are evaluated left to right, are comma separated, +and are each a protocol name or +.Ar all , +optionally prefixed by zero or more modifiers. Available modifiers are: +.Bl -tag -width indent +.It + +Permit this protocol in addition to protocols already permitted (this +is the default if no modifier is used). +.It - +Deny this protocol, removing it from the list of protocols already +permitted. +.It = +Permit only this protocol (ignoring the list already permitted), +though subject to later modification by subsequent entries in the +comma separated list. +.El +.Pp +For example: +.Pp +.Dl \fI--proto\fP -ftps +.Pp +uses the default protocols, but disables ftps +.Pp +.Dl \fI--proto\fP -all,https,+http +.Pp +only enables http and https +.Pp +.Dl \fI--proto\fP =http,https +.Pp +also only enables http and https +.Pp +Unknown 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. +.Pp +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. +.Pp +See also \fI--proto-redir\fP and \fI--proto-default\fP. Added in +7.20.2. +.It Fl -proxy-anyauth +Tells curl to pick a suitable authentication method when communicating +with the given HTTP proxy. This might cause an extra request/response +round-trip. +.Pp +See also \fI-x, --proxy\fP and \fI--proxy-basic\fP and +\fI--proxy-digest\fP. Added in 7.13.2. +.It Fl -proxy-basic +Tells curl to 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. +.Pp +See also \fI-x, --proxy\fP and \fI--proxy-anyauth\fP and +\fI--proxy-digest\fP. +.It Fl -proxy-cacert Ar <file> +Same as +.Fl -cacert +but used in HTTPS proxy context. +.Pp +See also +.Fl -proxy-capath +and +.Fl -cacert +and +.Fl -capath +and +.Fl x , +.Fl -proxy . +Added in 7.52.0. +.It Fl -proxy-capath Ar <dir> +Same as +.Fl -capath +but used in HTTPS proxy context. +.Pp +See also +.Fl -proxy-cacert +and +.Fl x , +.Fl -proxy +and +.Fl -capath . +Added in 7.52.0. +.It Fl -proxy-cert-type Ar <type> +Same as +.Fl -cert-type +but used in HTTPS proxy context. +.Pp +Added in 7.52.0. +.It Fl -proxy-cert Ar <cert[:passwd]> +Same as +.Fl E , +.Fl -cert +but used in HTTPS proxy context. +.Pp +Added in 7.52.0. +.It Fl -proxy-ciphers Ar <list> +Same as +.Fl -ciphers +but used in HTTPS proxy context. +.Pp +Added in 7.52.0. +.It Fl -proxy-crlfile Ar <file> +Same as +.Fl -crlfile +but used in HTTPS proxy context. +.Pp +Added in 7.52.0. +.It Fl -proxy-digest +Tells curl to use HTTP Digest authentication when communicating with +the given proxy. Use +.Fl -digest +for enabling HTTP Digest with a remote host. +.Pp +See also +.Fl x , +.Fl -proxy +and +.Fl -proxy-anyauth +and +.Fl -proxy-basic . +.It Fl -proxy-header Ar <header/@file> +(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 +.Fl H , +.Fl -header +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. +.Pp +curl will make 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 will only mess things up for you. +.Pp +Headers specified with this option will not be included in requests +that curl knows will not be sent to a proxy. +.Pp +Starting in 7.55.0, this option can take an argument in @filename +style, which then adds a header for each line in the input file. Using +@- will make curl read the header file from stdin. +.Pp +This option can be used multiple times to add/replace/remove multiple +headers. +.Pp +Added in 7.37.0. +.It Fl -proxy-insecure +Same as +.Fl k , +.Fl -insecure +but used in HTTPS proxy context. +.Pp +Added in 7.52.0. +.It Fl -proxy-key-type Ar <type> +Same as +.Fl -key-type +but used in HTTPS proxy context. +.Pp +Added in 7.52.0. +.It Fl -proxy-key Ar <key> +Same as +.Fl -key +but used in HTTPS proxy context. +.It Fl -proxy-negotiate +Tells curl to use HTTP Negotiate (SPNEGO) authentication when +communicating with the given proxy. Use +.Fl -negotiate +for enabling HTTP Negotiate (SPNEGO) with a remote host. +.Pp +See also +.Fl -proxy-anyauth +and +.Fl -proxy-basic . +Added in 7.17.1. +.It Fl -proxy-ntlm +Tells curl to use HTTP NTLM authentication when communicating with the +given proxy. Use +.Fl -ntlm +for enabling NTLM with a remote host. +.Pp +See also +.Fl -proxy-negotiate +and +.Fl -proxy-anyauth . +.It Fl -proxy-pass Ar <phrase> +Same as +.Fl -pass +but used in HTTPS proxy context. +.Pp +Added in 7.52.0. +.It Fl -proxy-pinnedpubkey Ar <hashes> +(TLS) Tells curl to 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 \'sha256//\' and separated by \';\' +.Pp +When negotiating a TLS or SSL connection, the server sends a +certificate indicating its identity. A public key is extracted from +this certificate and if it does not exactly match the public key +provided to this option, curl will abort the connection before sending +or receiving any data. +.Pp +If this option is used several times, the last one will be used. +.It Fl -proxy-service-name Ar <name> +This option allows you to change the service name for proxy +negotiation. +.Pp +Added in 7.43.0. +.It Fl -proxy-ssl-allow-beast +Same as +.Fl -ssl-allow-beast +but used in HTTPS proxy context. +.Pp +Added in 7.52.0. +.It Fl -proxy-tls13-ciphers Ar <ciphersuite list> +(TLS) Specifies 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: +.Pp +.Dl https://curl.haxx.se/docs/ssl-ciphers.html +.Pp +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 +.Fl -proxy-ciphers +option. +.Pp +If this option is used several times, the last one will be used. +.It Fl -proxy-tlsauthtype Ar <type> +Same as +.Fl -tlsauthtype +but used in HTTPS proxy context. +.Pp +Added in 7.52.0. +.It Fl -proxy-tlspassword Ar <string> +Same as +.Fl -tlspassword +but used in HTTPS proxy context. +.Pp +Added in 7.52.0. +.It Fl -proxy-tlsuser Ar <name> +Same as +.Fl -tlsuser +but used in HTTPS proxy context. +.Pp +Added in 7.52.0. +.It Fl -proxy-tlsv1 +Same as +.Fl 1 , +.Fl -tlsv1 +but used in HTTPS proxy context. +.Pp +Added in 7.52.0. +.It Fl U Ar <user:password> | Fl -proxy-user Ar <user:password> +Specify the user name and password to use for proxy authentication. +.Pp +If you use a Windows SSPI-enabled curl binary and do either Negotiate +or NTLM authentication then you can tell curl to select the user name +and password from your environment by specifying a single colon with +this option: "-U :". +.Pp +On systems where it works, curl will hide the given option argument +from process listings. This is not enough to protect credentials from +possibly getting seen by other users on the same system as they will +still be visible for a brief moment before cleared. Such sensitive +data should be retrieved from a file instead or similar and never used +in clear text in a command line. +.Pp +If this option is used several times, the last one will be used. +.It Fl x Ar [protocol://]host[:port] | -proxy Ar [protocol://]host[:port] +Use the specified proxy. +.Pp +The proxy string can be specified with a protocol:// prefix. No +protocol specified or http:// will be treated as HTTP proxy. Use +socks4://, socks4a://, socks5:// or socks5h:// to request a specific +SOCKS version to be used. (The protocol support was added in curl +7.21.7) +.Pp +HTTPS proxy support via https:// protocol prefix was added in 7.52.0 +for OpenSSL, GnuTLS and NSS. +.Pp +Unrecognized and unsupported proxy protocols cause an error since +7.52.0. Prior versions may ignore the protocol and use http:// +instead. +.Pp +If the port number is not specified in the proxy string, it is assumed +to be 1080. +.Pp +This option overrides existing environment variables that set the +proxy to use. If there's an environment variable setting a proxy, you +can set proxy to \&"" to override it. +.Pp +All operations that are performed over an HTTP proxy will +transparently be 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 +.Fl p , +.Fl -proxytunnel +option. +.Pp +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. +.Pp +The proxy host can be specified the exact same way as the proxy +environment variables, including the protocol prefix (http://) and the +embedded user + password. +.Pp +If this option is used several times, the last one will be used. +.It Fl -proxy1.0 Ar <host[:port]> +Use the specified HTTP 1.0 proxy. If the port number is not specified, +it is assumed at port 1080. +.Pp +The only difference between this and the HTTP proxy option +.Fl x , +.Fl -proxy , +is that attempts to use CONNECT through the proxy will specify an HTTP +1.0 protocol instead of the default HTTP 1.1. +.It Fl p | -proxytunnel +When an HTTP proxy is used +.Fl x , +.Fl -proxy , +this option will make curl tunnel through the proxy. The tunnel +approach is made with the HTTP proxy CONNECT request and requires that +the proxy allows direct connect to the remote port number curl wants +to tunnel through to. +.Pp +To suppress proxy CONNECT response headers when curl is set to output +headers use +.Fl -suppress-connect-headers . +.Pp +See also +.Fl x , +.Fl -proxy . +.It Fl -pubkey Ar <key> +(SFTP SCP) Public key file name. Allows you to provide your public key +in this separate file. +.Pp +If this option is used several times, the last one will be used. +.Pp +(As of 7.39.0, 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.) +.It Fl 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 PWD command in an FTP transfer, to be exact). To +make commands take place after a successful transfer, prefix them with +a dash '-'. To make commands be sent after curl has changed the +working directory, just before the transfer command(s), prefix the +command with a '+' (this is only supported for FTP). You may specify +any number of commands. +.Pp +If the server returns failure for one of the commands, the entire +operation will be 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. +.Pp +This option can be used multiple times. When speaking to an FTP +server, prefix the command with an asterisk (*) to make curl continue +even if the command fails as by default curl will stop at first +failure. +.Pp +SFTP is a binary protocol. Unlike for FTP, curl interprets SFTP quote +commands itself before sending them to the server. File names may be +quoted shell-style to embed spaces or special characters. Following +is the list of all supported SFTP quote commands: +.Bl -tag -width indent +.It 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. +.It chmod mode file +The chmod command modifies the file mode bits of the specified +file. The mode operand is an octal integer mode number. +.It 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. +.It 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. +.It mkdir directory_name +The mkdir command creates the directory named by the directory_name +operand. +.It pwd +The pwd command returns the absolute pathname of the current working +directory. +.It 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. +.It rm file +The rm command removes the file specified by the file operand. +.It rmdir directory +The rmdir command removes the directory entry specified by the directory +operand, provided it is empty. +.It symlink source_file target_file +See ln. +.El +.It Fl -random-file Ar <file> +Specify the path name to file containing what will be considered as random +data. The data may be used to seed the random engine for SSL connections. +See also the +.Fl -egd-file +option. +.It Fl r Ar <range> | Fl -range Ar <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. +.Bl -tag -width indent +.It 0-499 +specifies the first 500 bytes +.It 500-999 +specifies the second 500 bytes +.It -500 +specifies the last 500 bytes +.It 9500- +specifies the bytes from offset 9500 and forward +.It 0-0,-1 +specifies the first and last byte only(*)(HTTP) +.It 100-199,500-599 +specifies two separate 100-byte ranges(*) (HTTP) +.El +(*) = NOTE that this will cause the server to reply with a multipart +response! +.Pp +Only digit characters (0-9) are valid in the 'start' and 'stop' fields +of the \&'start-stop' range syntax. If a non-digit character is given +in the range, the server's response will be unspecified, depending on +the server's configuration. +.Pp +You should also be aware that many HTTP/1.1 servers do not have this +feature enabled, so that when you attempt to get a range, you'll +instead get the whole document. +.Pp +FTP and SFTP range downloads only support the simple 'start-stop' +syntax (optionally with one of the numbers omitted). FTP use depends +on the extended FTP command SIZE. +.Pp +If this option is used several times, the last one will be used. +.It Fl -raw +(HTTP) When used, it disables all internal HTTP decoding of content or +transfer encodings and instead makes them passed on unaltered, raw. +.Pp +Added in 7.16.2. +.It Fl e | -referer Ar <URL> +(HTTP) Sends the "Referrer Page" information to the HTTP server. This +bcan also be set with the +.Fl H , +.Fl -header +flag of course. When used with +.Fl L , +.Fl -location +you can append ";auto" to the +.Fl e , +.Fl -referer +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 +don't set an initial +.Fl e , +.Fl -referer . +.Pp +If this option is used several times, the last one will be used. +.Pp +See also +.Fl A , +.Fl -user-agent +and +.Fl H , +.Fl -header . +.It Fl J | -remote-header-name +(HTTP) This option tells the \fI-O, --remote-name\fP option to use the +server-specified Content-Disposition filename instead of extracting a +filename from the URL. +.Pp +If the server specifies a file name and a file with that name already +exists in the current working directory it will not be overwritten and +an error will occur. If the server doesn't specify a file name then +this option has no effect. +.Pp +There's no attempt to decode %-sequences (yet) in the provided file +name, so this option may provide you with rather unexpected file +names. +.Pp +\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 possibly be loaded automatically by Windows or some third +party software. +.It Fl -remote-name-all +This option changes the default action for all given URLs to be dealt +with as if \fI-O, --remote-name\fP were used for each one. So if you +want to disable that for a specific URL after \fI--remote-name-all\fP +has been used, you must use "-o -" or --no-remote-name. +.Pp +Added in 7.19.0. +.It Fl 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.) +.Pp +The file will be saved in the current working directory. If you want +the file saved in a different directory, make sure you change the +current working directory before invoking curl with this option. +.Pp +The remote file name to use for saving is extracted from the given +URL, nothing else, and if it already exists it will be overwritten. If +you want the server to be able to choose the file name refer to \fI-J, +--remote-header-name\fP which can be used in addition to this +option. If the server chooses a file name and that name already exists +it will not be overwritten. +.Pp +There is no URL decoding done on the file name. If it has %20 or other +URL encoded parts of the name, they will end up as-is as file name. +.Pp +You may use this option as many times as the number of URLs you have. +.It Fl R | -remote-time +When used, this will make curl attempt to figure out the timestamp of +the remote file, and if that is available make the local file get that +same timestamp. +.It Fl -request-target +(HTTP) Tells curl to 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 doesn't follow the regular URL pattern, like "OPTIONS *". +.Pp +Added in 7.55.0. +.It Fl X Ar command | -request Ar <command> +(HTTP) Specifies a custom request method to use when communicating +with the HTTP server. The specified request method will be used +instead of the method otherwise used (which defaults to GET). Read the +HTTP 1.1 specification for details and explanations. Common additional +HTTP requests include PUT and DELETE, but related technologies like +WebDAV offers PROPFIND, COPY, MOVE and more. +.Pp +Normally you don't need this option. All sorts of GET, HEAD, POST and +PUT requests are rather invoked by using dedicated command line +options. +.Pp +This option only changes the actual word used in the HTTP request, it +does not alter the way curl behaves. So for example if you want to +make a proper HEAD request, using -X HEAD will not suffice. You need +to use the \fI-I, --head\fP option. +.Pp +The method string you set with \fI-X, --request\fP will be used for +all requests, which if you for example use \fI-L, --location\fP may +cause unintended side-effects when curl doesn't change request method +according to the HTTP 30x response codes - and similar. +.Pp +(FTP) Specifies a custom FTP command to use instead of LIST when doing +file lists with FTP. +.Pp +(POP3) Specifies a custom POP3 command to use instead of LIST or +RETR. (Added in 7.26.0) +.Pp +(IMAP) Specifies a custom IMAP command to use instead of LIST. (Added +in 7.30.0) +.Pp +(SMTP) Specifies a custom SMTP command to use instead of HELP or +VRFY. (Added in 7.34.0) +.Pp +If this option is used several times, the last one will be used. +.It Fl "--resolve <host:port:address[,address]...>" +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 will be used for. It means you need several entries if you want +to provide address for the same host but different ports. +.Pp +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 will be used +first. +.Pp +The provided address set by this option will be used even if \fI-4, +--ipv4\fP or \fI-6, --ipv6\fP is set to make curl use another IP +version. +.Pp +Support for providing the IP address within [brackets] was added in 7.57.0. +.Pp +Support for providing multiple IP addresses per entry was added in 7.59.0. +.Pp +Support for resolving with wildcard was added in 7.64.0. +.Pp +This option can be used many times to add many host names to resolve. +.Pp +Added in 7.21.3. +.It Fl -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 --retry. +.Pp +Added in 7.52.0. +.It Fl -retry-delay Ar <seconds> +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 will make curl +use the default backoff time. +.Pp +If this option is used several times, the last one will be used. +.Pp +Added in 7.12.3. +.It Fl -retry-max-time Ar <seconds> +The retry timer is reset before the first transfer attempt. Retries +will be done as usual (see \fI--retry\fP) as long as the timer hasn't +reached this given limit. Notice that if the timer hasn't reached the +limit, the request will be made and while performing, it may take +longer than this given time period. To limit a single request\'s +maximum time, use \fI-m, --max-time\fP. Set this option to zero to +not timeout retries. +.Pp +If this option is used several times, the last one will be used. +.Pp +Added in 7.12.3. +.It Fl -retry Ar <num> +If a transient error is returned when curl tries to perform a +transfer, it will retry 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 or 5xx response code. +.Pp +When curl is about to retry a transfer, it will first wait one second +and then for all forthcoming retries it will double the waiting time +until it reaches 10 minutes which then will be the 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. +.Pp +If this option is used several times, the last one will be used. +.Pp +Added in 7.12.3. +.It Fl -sasl-ir +Enable initial response in SASL authentication. +.Pp +Added in 7.31.0. +.It Fl -service-name Ar <name> +This option allows you to change the service name for SPNEGO. +.Pp +Examples: \fI--negotiate\fP \fI--service-name\fP sockd would use +sockd/server-name. +.Pp +Added in 7.43.0. +.It Fl S | -show-error +When used with \fI-s, --silent\fP, it makes curl show an error message +if it fails. +.It Fl s | -silent +Silent or quiet mode. Don't show progress meter or error messages. +Makes Curl mute. It will still output the data you ask for, +potentially even to the terminal/stdout unless you redirect it. +.Pp +Use \fI-S, --show-error\fP in addition to this option to disable +progress meter but still show error messages. +.Pp +See also \fI-v, --verbose\fP and \fI--stderr\fP. +.It Fl -socks4 Ar <host[:port]> +Use the specified SOCKS4 proxy. If the port number is not specified, +it is assumed at port 1080. +.Pp +This option overrides any previous use of \fI-x, --proxy\fP, as they +are mutually exclusive. +.Pp +Since 7.21.7, this option is superfluous since you can specify a +socks4 proxy with \fI-x, --proxy\fP using a socks4:// protocol prefix. +.Pp +Since 7.52.0, \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. In +such a case curl first connects to the SOCKS proxy and then connects +(through SOCKS) to the HTTP or HTTPS proxy. +.Pp +If this option is used several times, the last one will be used. +.Pp +Added in 7.15.2. +.It Fl -socks4a Ar <host[:port]> +Use the specified SOCKS4a proxy. If the port number is not specified, +it is assumed at port 1080. +.Pp +This option overrides any previous use of \fI-x, --proxy\fP, as they +are mutually exclusive. +.Pp +Since 7.21.7, this option is superfluous since you can specify a +socks4a proxy with \fI-x, --proxy\fP using a socks4a:// protocol +prefix. +.Pp +Since 7.52.0, \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. In +such a case curl first connects to the SOCKS proxy and then connects +(through SOCKS) to the HTTP or HTTPS proxy. +.Pp +If this option is used several times, the last one will be used. +.Pp +Added in 7.18.0. +.It Fl -socks5-basic +Tells curl to 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. +.Pp +Added in 7.55.0. +.It Fl -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. +.Pp +Added in 7.19.4. +.It Fl -socks5-gssapi-service Ar <name> +The default service name for a socks server is rcmd/server-fqdn. This +option allows you to change it. +.Pp +Examples: \fI--socks5\fP proxy-name \fI--socks5-gssapi-service\fP sockd would use +sockd/proxy-name \fI--socks5\fP proxy-name \fI--socks5-gssapi-service\fP sockd/real-name +would use sockd/real-name for cases where the proxy-name does not match the +principal name. +.Pp +Added in 7.19.4. +.It Fl -socks5-gssapi +Tells curl to 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. +.Pp +Added in 7.55.0. +.It Fl -socks5-hostname Ar <host[:port]> +Use the specified SOCKS5 proxy (and let the proxy resolve the host +name). If the port number is not specified, it is assumed at port +1080. +.Pp +This option overrides any previous use of \fI-x, --proxy\fP, as they +are mutually exclusive. +.Pp +Since 7.21.7, this option is superfluous since you can specify a socks5 +hostname proxy with \fI-x, --proxy\fP using a socks5h:// protocol prefix. +.Pp +Since 7.52.0, \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. In +such a case curl first connects to the SOCKS proxy and then connects +(through SOCKS) to the HTTP or HTTPS proxy. +.Pp +If this option is used several times, the last one will be used. +.Pp +Added in 7.18.0. +.It Fl -socks5 Ar <host[:port]> +Use the specified SOCKS5 proxy - but resolve the host name locally. If +the port number is not specified, it is assumed at port 1080. +.Pp +This option overrides any previous use of \fI-x, --proxy\fP, as they +are mutually exclusive. +.Pp +Since 7.21.7, this option is superfluous since you can specify a +socks5 proxy with \fI-x, --proxy\fP using a socks5:// protocol prefix. +.Pp +Since 7.52.0, \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. In +such a case curl first connects to the SOCKS proxy and then connects +(through SOCKS) to the HTTP or HTTPS proxy. +.Pp +If this option is used several times, the last one will be used. +.Pp +This option (as well as \fI--socks4\fP) does not work with IPV6, FTPS +or LDAP. +.Pp +Added in 7.18.0. +.It Fl Y Ar speed | Fl -speed-limit Ar <speed> +If a download is slower than this given speed (in bytes per second) +for speed-time seconds it gets aborted. speed-time is set with \fI-y, +--speed-time\fP and is 30 if not set. +.Pp +If this option is used several times, the last one will be used. +.It Fl Fl y Ar seconds | -speed-time Ar <seconds> +If a download is slower than speed-limit bytes per second during a +speed-time period, the download gets aborted. If speed-time is used, +the default speed-limit will be 1 unless set with \fI-Y, +--speed-limit\fP. +.Pp +This option controls transfers and thus will not affect slow connects +etc. If this is a concern for you, try the \fI--connect-timeout\fP +option. +.Pp +If this option is used several times, the last one will be used. +.It Fl -ssl-allow-beast +This option tells curl to not work around a security flaw in the SSL3 +and TLS1.0 protocols known as BEAST. If this option isn't used, the +SSL layer may use workarounds known to cause interoperability problems +with some older SSL implementations. WARNING: this option loosens the +SSL security, and by using this flag you ask for exactly that. +.Pp +Added in 7.25.0. +.It Fl -ssl-no-revoke +(Schannel) This option tells curl to disable certificate revocation +checks. WARNING: this option loosens the SSL security, and by using +this flag you ask for exactly that. +.Pp +Added in 7.44.0. +.It Fl -ssl-reqd +(FTP IMAP POP3 SMTP) Require SSL/TLS for the connection. Terminates +the connection if the server doesn't support SSL/TLS. +.Pp +This option was formerly known as --ftp-ssl-reqd. +.Pp +Added in 7.20.0. +.It Fl -ssl +(FTP IMAP POP3 SMTP) Try to use SSL/TLS for the connection. Reverts +to a non-secure connection if the server doesn't support SSL/TLS. See +also \fI--ftp-ssl-control\fP and \fI--ssl-reqd\fP for different levels +of encryption required. +.Pp +This option was formerly known as --ftp-ssl (Added in 7.11.0). That +option name can still be used but will be removed in a future version. +.Pp +Added in 7.20.0. +.It Fl 2 | -sslv2 +(SSL) Forces curl to use SSL version 2 when negotiating with a remote +SSL server. Sometimes curl is built without SSLv2 support. SSLv2 is +widely considered insecure (see RFC 6176). +.Pp +See also \fI--http1.1\fP and \fI--http2\fP. \fI-2, --sslv2\fP requires +that the underlying libgnurl was built to support TLS. This option +overrides \fI-3, --sslv3\fP and \fI-1, --tlsv1\fP and \fI--tlsv1.1\fP +and \fI--tlsv1.2\fP. +.It Fl 3 | -sslv3 +(SSL) Forces curl to use SSL version 3 when negotiating with a remote +SSL server. Sometimes curl is built without SSLv3 support. SSLv3 is +widely considered insecure (see RFC 7568). +.Pp +See also \fI--http1.1\fP and \fI--http2\fP. \fI-3, --sslv3\fP requires +that the underlying libgnurl was built to support TLS. This option +overrides \fI-2, --sslv2\fP and \fI-1, --tlsv1\fP and \fI--tlsv1.1\fP +and \fI--tlsv1.2\fP. +.It Fl -stderr +Redirect all writes to stderr to the specified file instead. If the +file name is a plain '-', it is instead written to stdout. +.Pp +If this option is used several times, the last one will be used. +.Pp +See also \fI-v, --verbose\fP and \fI-s, --silent\fP. +.It Fl -styled-output +Enables the automatic use of bold font styles when writing HTTP +headers to the terminal. Use --no-styled-output to switch them off. +.Pp +Added in 7.61.0. +.It Fl -suppress-connect-headers +When \fI-p, --proxytunnel\fP is used and a CONNECT request is made +don't 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. +.Pp +See also \fI-D, --dump-header\fP and \fI-i, --include\fP and \fI-p, +--proxytunnel\fP. +.It Fl -tcp-fastopen +Enable use of TCP Fast Open (RFC7413). +.Pp +Added in 7.49.0. +.It Fl -tcp-nodelay +Turn on the TCP_NODELAY option. See the \fIcurl_easy_setopt(3)\fP man +page for details about this option. +.Pp +Since 7.50.2, curl sets this option by default and you need to +explicitly switch it off if you don't want it on. +.Pp +Added in 7.11.2. +.It Fl t Ar opt=val | Fl -telnet-option Ar <opt=val> +Pass options to the telnet protocol. Supported options are: +.Bl -tag -width indent +.It TTYPE=<term> +Sets the terminal type. +.It XDISPLOC=<X display> +Sets the X display location. +.It NEW_ENV=<var,val> +Sets an environment variable. +.El +.It Fl -tftp-blksize Ar <value> +(TFTP) Set TFTP BLKSIZE option (must be >512). This is the block size +that curl will try to use when transferring data to or from a TFTP +server. By default 512 bytes will be used. +.Pp +If this option is used several times, the last one will be used. +.Pp +Added in 7.20.0. +.It Fl -tftp-no-options +(TFTP) Tells curl not to send TFTP options requests. +.Pp +This option 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. +.Pp +Added in 7.48.0. +.It Fl z time | -time-cond Ar <time> +(HTTP FTP) Request a file that has been modified later than the given +time and date, or one that has been modified before that time. The +<date expression> can be all sorts of date strings or if it doesn't +match any internal ones, it is taken as a filename and tries to get +the modification date (mtime) from <file> instead. See the +\fIcurl_getdate(3)\fP man pages for date expression details. +.Pp +Start the date expression with a dash (-) to make it request for a +document that is older than the given date/time, default is a document +that is newer than the specified date/time. +.Pp +If this option is used several times, the last one will be used. +.It Fl -tls-max Ar <VERSION> +(SSL) VERSION defines maximum supported TLS version. The minimum +acceptable version is set by tlsv1.0, tlsv1.1, tlsv1.2 or tlsv1.3. +.Bl -tag -width indent +.It default +Use up to recommended TLS version. +.It 1.0 +Use up to TLSv1.0. +.It 1.1 +Use up to TLSv1.1. +.It 1.2 +Use up to TLSv1.2. +.It 1.3 +Use up to TLSv1.3. +.El +See also \fI--tlsv1.0\fP and \fI--tlsv1.1\fP and \fI--tlsv1.2\fP and +\fI--tlsv1.3\fP. \fI--tls-max\fP requires that the underlying libgnurl +was built to support TLS. Added in 7.54.0. +.It Fl -tls13-ciphers Ar <list of TLS 1.3 ciphersuites> +(TLS) Specifies which cipher suites to use in the connection if 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: +.Lk https://curl.haxx.se/docs/ssl-ciphers.html +.Pp +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 +.Fl -ciphers +option. +.Pp +If this option is used several times, the last one will be used. +.It Fl -tlsauthtype Ar <type> +Set TLS authentication type. Currently, the only supported option is +"SRP", for TLS-SRP (RFC 5054). If \fI--tlsuser\fP and +\fI--tlspassword\fP are specified but \fI--tlsauthtype\fP is not, then +this option defaults to "SRP". This option works only if the +underlying libcurl is built with TLS-SRP support, which requires +OpenSSL or GnuTLS with TLS-SRP support. +.Pp +Added in 7.21.4. +.It Fl -tlspassword +Set password for use with the TLS authentication method specified with +\fI--tlsauthtype\fP. Requires that \fI--tlsuser\fP also be set. +.Pp +Added in 7.21.4. +.It Fl -tlsuser Ar <name> +Set username for use with the TLS authentication method specified with +\fI--tlsauthtype\fP. Requires that \fI--tlspassword\fP also is set. +.Pp +Added in 7.21.4. +.It Fl -tlsv1.0 +(TLS) Forces curl to use TLS version 1.0 or later when connecting to a remote TLS server. +.Pp +Added in 7.34.0. +.It Fl -tlsv1.1 +(TLS) Forces curl to use TLS version 1.1 or later when connecting to a remote TLS server. +.Pp +Added in 7.34.0. +.It Fl -tlsv1.2 +(TLS) Forces curl to use TLS version 1.2 or later when connecting to a remote TLS server. +.Pp +Added in 7.34.0. +.It Fl -tlsv1.3 +(TLS) Forces curl to use TLS version 1.3 or later when connecting to a remote TLS server. +.Pp +Note that TLS 1.3 is only supported by a subset of TLS backends. At the time +of this writing, they are BoringSSL, NSS, and Secure Transport (on iOS 11 or +later, and macOS 10.13 or later). +.Pp +Added in 7.52.0. +.It Fl 1 | -tlsv1 +(SSL) Tells curl to use at least TLS version 1.x when negotiating with a remote TLS +server. That means TLS version 1.0 or higher +.Pp +See also \fI--http1.1\fP and \fI--http2\fP. \fI-1, --tlsv1\fP requires +that the underlying libgnurl was built to support TLS. This option +overrides \fI--tlsv1.1\fP and \fI--tlsv1.2\fP and \fI--tlsv1.3\fP. +.It Fl -tr-encoding +(HTTP) Request a compressed Transfer-Encoding response using one of the algorithms +curl supports, and uncompress the data while receiving it. +.Pp +Added in 7.21.6. +.It Fl -trace-ascii Ar <file> +Enables a full trace dump of all incoming and outgoing data, including +descriptive information, to the given output file. Use "-" as filename to have +the output sent to stdout. +.Pp +This is very similar to \fI--trace\fP, but leaves out the hex part and only shows +the ASCII part of the dump. It makes smaller output that might be easier to +read for untrained humans. +.Pp +If this option is used several times, the last one will be used. +.Pp +This option overrides \fI--trace\fP and \fI-v, --verbose\fP. +.It Fl -trace-time +Prepends a time stamp to each trace or verbose line that curl displays. +.Pp +Added in 7.14.0. +.It Fl -trace Ar <file> +Enables a full trace dump of all incoming and outgoing data, including +descriptive information, to the given output file. Use "-" as filename to have +the output sent to stdout. Use "%" as filename to have the output sent to +stderr. +.Pp +If this option is used several times, the last one will be used. +.Pp +This option overrides \fI-v, --verbose\fP and \fI--trace-ascii\fP. +.It Fl -unix-socket Ar <path> +(HTTP) Connect through this Unix domain socket, instead of using the network. +.Pp +Added in 7.40.0. +.It Fl T Ar file | Fl -upload-file Ar <file> +This transfers the specified local file to the remote URL. If there is +no file part in the specified URL, curl will append the local file +name. NOTE that you must use a trailing / on the last directory to +really prove to Curl that there is no file name or curl will think +that your last directory name is the remote file name to use. That +will most likely cause the upload operation to fail. If this is used +on an HTTP(S) server, the PUT command will be used. +.Pp +Use the file name "-" (a single dash) to use stdin instead of a given +file. Alternately, the file name "." (a single period) may be +specified instead of "-" to use stdin in non-blocking mode to allow +reading server output while stdin is being uploaded. +.Pp +You can specify one \fI-T, --upload-file\fP for each URL on the +command line. Each \fI-T, --upload-file\fP + URL pair specifies what +to upload and to where. curl also supports "globbing" of the \fI-T, +--upload-file\fP argument, meaning that you can upload multiple files +to a single URL by using the same URL globbing style supported in the +URL, like this: +.Pp +.Dl curl --upload-file "{file1,file2}" http://www.example.com +.Pp +or even +.Pp +.Dl curl -T "img[1-1000].png" ftp://ftp.example.com/upload/ +.Pp +When uploading to an SMTP server: the uploaded data is assumed to be +RFC 5322 formatted. It has to feature the necessary set of headers and +mail body formatted correctly by the user as curl will not transcode +nor encode it further in any way. +.It Fl -url Ar <url> +Specify a URL to fetch. This option is mostly handy when you want to +specify URL(s) in a config file. +.Pp +If the given URL is missing a scheme name (such as "http://" or +"ftp://" etc) then curl will make a guess based on the host. If the +outermost sub-domain name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP +then that protocol will be used, otherwise HTTP will be used. Since +7.45.0 guessing can be disabled by setting a default protocol, see +\fI--proto-default\fP for details. +.Pp +This option may be used any number of times. To control where this URL +is written, use the \fI-o, --output\fP or the \fI-O, --remote-name\fP +options. +.It Fl B | -use-ascii +(FTP LDAP) Enable ASCII transfer. For FTP, this can also be enforced +by using a URL that ends with ";type=A". This option causes data sent +to stdout to be in text mode for win32 systems. +.It Fl A Ar <name> | Fl -user-agent Ar <name> +(HTTP) +Specify the User-Agent string to send to the HTTP server. To encode blanks in +the string, surround the string with single quote marks. This header can also +be set with the \fI-H, --header\fP or the \fI--proxy-header\fP options. +.Pp +If this option is used several times, the last one will be used. +.It Fl u Ar <user:password> | Fl -user Ar <user:password> +Specify the user name and password to use for server authentication. Overrides +\fI-n, --netrc\fP and \fI--netrc-optional\fP. +.Pp +If you simply specify the user name, curl will prompt for a password. +.Pp +The user name and passwords are split up on the first colon, which makes it +impossible to use a colon in the user name with this option. The password can, +still. +.Pp +On systems where it works, curl will hide the given option argument from +process listings. This is not enough to protect credentials from possibly +getting seen by other users on the same system as they will still be visible +for a brief moment before cleared. Such sensitive data should be retrieved +from a file instead or similar and never used in clear text in a command line. +.Pp +When using Kerberos V5 with a Windows based server you should include the +Windows domain name in the user name, in order for the server to successfully +obtain a Kerberos Ticket. If you don't then the initial authentication +handshake may fail. +.Pp +When using NTLM, the user name can be specified simply as the user name, +without the domain, if there is a single domain and forest in your setup +for example. +.Pp +To specify the domain name use either Down-Level Logon Name or UPN (User +Principal Name) formats. For example, EXAMPLE\\user and user@example.com +respectively. +.Pp +If you use a Windows SSPI-enabled curl binary and perform Kerberos V5, +Negotiate, NTLM or Digest authentication then you can tell curl to select +the user name and password from your environment by specifying a single colon +with this option: "-u :". +.Pp +If this option is used several times, the last one will be used. +.It Fl v | -verbose +Makes curl verbose during the operation. Useful for debugging and seeing +what's going on "under the hood". A line starting with '>' means "header data" +sent by curl, '<' means "header data" received by curl that is hidden in +normal cases, and a line starting with '*' means additional info provided by +curl. +.Pp +If you only want HTTP headers in the output, +.Fl i | -include +might be the option you're looking for. +.Pp +If you think this option still doesn't give you enough details, consider using +.Fl -trace +or +.Fl -trace-ascii +instead. +.Pp +Use +.Fl s | -silent +to make curl really quiet. +.Pp +See also +.Fl i | -include . +This option overrides +.Fl -trace +and +.Fl -trace-ascii . +.It Fl V | -version +Displays information about curl and the libcurl version it uses. +.Pp +The first line includes the full version of curl, libcurl and other 3rd party +libraries linked with the executable. +.Pp +The second line (starts with "Protocols:") shows all protocols that libcurl +reports to support. +.Pp +The third line (starts with "Features:") shows specific features libcurl +reports to offer. Available features include: +.Bl -tag -width indent +.It IPv6 +You can use IPv6 with this. +.It krb4 +Krb4 for FTP is supported. +.It SSL +SSL versions of various protocols are supported, such as HTTPS, FTPS, POP3S +and so on. +.It libz +Automatic decompression of compressed files over HTTP is supported. +.It NTLM +NTLM authentication is supported. +.It Debug +This curl uses a libcurl built with Debug. This enables more error-tracking +and memory debugging etc. For curl-developers only! +.It AsynchDNS +This curl uses asynchronous name resolves. Asynchronous name resolves can be +done using either the c-ares or the threaded resolver backends. +.It SPNEGO +SPNEGO authentication is supported. +.It Largefile +This curl supports transfers of large files, files larger than 2GB. +.It IDN +This curl supports IDN - international domain names. +.It GSS-API +GSS-API is supported. +.It SSPI +SSPI is supported. +.It TLS-SRP +SRP (Secure Remote Password) authentication is supported for TLS. +.It HTTP2 +HTTP/2 support has been built-in. +.It UnixSockets +Unix sockets support is provided. +.It HTTPS-proxy +This curl is built to support HTTPS proxy. +.It Metalink +This curl supports Metalink (both version 3 and 4 (RFC 5854)), which +describes mirrors and hashes. curl will use mirrors for failover if +there are errors (such as the file or server not being available). +.It PSL +PSL is short for Public Suffix List and means that this curl has been built +with knowledge about "public suffixes". +.It MultiSSL +This gnurl supports multiple TLS backends. +.El +.It Fl w Ar <format> | Fl -write-out Ar <format> +Make curl display information on stdout after a completed transfer. The format +is a string that may contain plain text mixed with any number of +variables. The format can be specified as a literal "string", or you can have +curl read the format from a file with "@filename" and to tell curl to read the +format from stdin you write "@-". +.Pp +The variables present in the output format will be substituted by the value or +text that curl thinks fit, as described below. All variables are specified as +%{variable_name} and to output a normal % you just write them as %%. You can +output a newline by using \\n, a carriage return with \\r and a tab space with +\\t. +.Pp +The output will be written to standard output, but this can be switched to +standard error by using %{stderr}. +.Pp +NOTE: The %-symbol is a special symbol in the win32-environment, where +all occurrences of % must be doubled when using this option. +.Pp +The variables available are: +.Bl -tag -width indent +.It content_type +The Content-Type of the requested document, if there was any. +.It filename_effective +The ultimate filename that curl writes out to. This is only meaningful if curl +is told to write to a file with the \fI-O, --remote-name\fP or \fI-o, --output\fP +option. It's most useful in combination with the \fI-J, --remote-header-name\fP +option. (Added in 7.26.0) +.It ftp_entry_path +The initial path curl ended up in when logging on to the remote FTP +server. (Added in 7.15.4) +.It http_code +The numerical response code that was found in the last retrieved HTTP(S) or +FTP(s) transfer. In 7.18.2 the alias \fBresponse_code\fP was added to show the +same info. +.It http_connect +The numerical code that was found in the last response (from a proxy) to a +curl CONNECT request. (Added in 7.12.4) +.It http_version +The http version that was effectively used. (Added in 7.50.0) +.It local_ip +The IP address of the local end of the most recently done connection - can be +either IPv4 or IPv6 (Added in 7.29.0) +.It local_port +The local port number of the most recently done connection (Added in 7.29.0) +.It num_connects +Number of new connects made in the recent transfer. (Added in 7.12.3) +.It num_redirects +Number of redirects that were followed in the request. (Added in 7.12.3) +.It proxy_ssl_verify_result +The result of the HTTPS proxy's SSL peer certificate verification that was +requested. 0 means the verification was successful. (Added in 7.52.0) +.It redirect_url +When an HTTP request was made without \fI-L, --location\fP to follow redirects (or when +--max-redir is met), this variable will show the actual URL a redirect +\fIwould\fP have gone to. (Added in 7.18.2) +.It remote_ip +The remote IP address of the most recently done connection - can be either +IPv4 or IPv6 (Added in 7.29.0) +.It remote_port +The remote port number of the most recently done connection (Added in 7.29.0) +.It scheme +The URL scheme (sometimes called protocol) that was effectively used (Added in 7.52.0) +.It size_download +The total amount of bytes that were downloaded. +.It size_header +The total amount of bytes of the downloaded headers. +.It size_request +The total amount of bytes that were sent in the HTTP request. +.It size_upload +The total amount of bytes that were uploaded. +.It speed_download +The average download speed that curl measured for the complete download. Bytes +per second. +.It speed_upload +The average upload speed that curl measured for the complete upload. Bytes per +second. +.It ssl_verify_result +The result of the SSL peer certificate verification that was requested. 0 +means the verification was successful. (Added in 7.19.0) +.It stderr +From this point on, the \fI-w, --write-out\fP output will be written to standard +error. (Added in 7.63.0) +.It stdout +From this point on, the \fI-w, --write-out\fP output will be written to standard output. +This is the default, but can be used to switch back after switching to stderr. +(Added in 7.63.0) +.It time_appconnect +The time, in seconds, it took from the start until the SSL/SSH/etc +connect/handshake to the remote host was completed. (Added in 7.19.0) +.It time_connect +The time, in seconds, it took from the start until the TCP connect to the +remote host (or proxy) was completed. +.It time_namelookup +The time, in seconds, it took from the start until the name resolving was +completed. +.It time_pretransfer +The time, in seconds, it took from the start until the file transfer was just +about to begin. This includes all pre-transfer commands and negotiations that +are specific to the particular protocol(s) involved. +.It time_redirect +The time, in seconds, it took for all redirection steps including name lookup, +connect, pretransfer and transfer before the final transaction was +started. time_redirect shows the complete execution time for multiple +redirections. (Added in 7.12.3) +.It time_starttransfer +The time, in seconds, it took from the start until the first byte was just +about to be transferred. This includes time_pretransfer and also the time the +server needed to calculate the result. +.It time_total +The total time, in seconds, that the full operation lasted. +.It url_effective +The URL that was fetched last. This is most meaningful if you've told curl +to follow location: headers. +.El +If this option is used several times, the last one will be used. +.It Fl -xattr +When saving output to a file, this option tells curl to store certain file +metadata in extended file attributes. Currently, the URL is stored in the +xdg.origin.url attribute and, for HTTP, the content type is stored in +the mime_type attribute. If the file system does not support extended +attributes, a warning is issued. +.El +.Sh FILES +.Pa ~/.curlrc +default config file, see +.Fl -config +for details. +.Sh ENVIRONMENT +The environment variables can be specified in lower case or upper case. The +lower case version has precedence. http_proxy is an exception as it is only +available in lower case. +.Pp +Using an environment variable to set the proxy has the same effect as using +the +.Fl -proxy +option. +.Bl -tag -width indent +.It "http_proxy [protocol://]<host>[:port]" +Sets the proxy server to use for HTTP. +.It "HTTPS_PROXY [protocol://]<host>[:port]" +Sets the proxy server to use for HTTPS. +.It "[url-protocol]_PROXY [protocol://]<host>[:port]" +Sets the proxy server to use for [url-protocol], where the protocol is a +protocol that curl supports and as specified in a URL. FTP, FTPS, POP3, IMAP, +SMTP, LDAP etc. +.It "ALL_PROXY [protocol://]<host>[:port]" +Sets the proxy server to use if no protocol-specific proxy is set. +.It "NO_PROXY <comma-separated list of hosts/domains>" +list of host names that shouldn't go through any proxy. If set to an asterisk +\&'*' only, it matches all hosts. Each name in this list is matched as either +a domain name which contains the hostname, or the hostname itself. +.El +.Pp +This environment variable disables use of the proxy even when specified with +the +.Fl x , -proxy +option. That is +.Pp +.Dl NO_PROXY=direct.example.com curl -x http://proxy.example.com http://direct.example.com +.Pp +accesses the target URL directly, and +.Pp +.Dl NO_PROXY=direct.example.com curl -x http://proxy.example.com http://somewhere.example.com +.Pp +accesses the target URL through the proxy. +.Pp +The list of host names can also be include numerical IP addresses, and IPv6 +versions should then be given without enclosing brackets. +.Ss PROXY PROTOCOL PREFIXES +Since curl version 7.21.7, the proxy string may be specified with a +protocol:// prefix to specify alternative proxy protocols. +.Pp +If no protocol is specified in the proxy string or if the string doesn't match +a supported one, the proxy will be treated as an HTTP proxy. +.Pp +The supported proxy protocol prefixes are as follows: +.Bl -tag -width indent +.It http:// +Makes it use it as an HTTP proxy. +The default if no scheme prefix is used. +.It https:// +Makes it treated as an \fBHTTPS\fP proxy. +.It socks4:// +Makes it the equivalent of +.Fl -socks4 +.It socks4a:// +Makes it the equivalent of +.Fl -socks4a +.It socks5:// +Makes it the equivalent of +.Fl -socks5 +.It socks5h:// +Makes it the equivalent of +.Fl -socks5-hostname +.El +.Sh EXIT STATUS +There are a bunch of different error codes and their corresponding error +messages that may appear during bad conditions. At the time of this writing, +the exit codes are: +.Bl -tag -width indent +.It 1 +Unsupported protocol. This build of curl has no support for this protocol. +.It 2 +Failed to initialize. +.It 3 +URL malformed. The syntax was not correct. +.It 4 +A feature or option that was needed to perform the desired request was not +enabled or was explicitly disabled at build-time. To make curl able to do +this, you probably need another build of libcurl! +.It 5 +Couldn't resolve proxy. The given proxy host could not be resolved. +.It 6 +Couldn't resolve host. The given remote host was not resolved. +.It 7 +Failed to connect to host. +.It 8 +Weird server reply. The server sent data curl couldn't parse. +.It 9 +FTP access denied. The server denied login or denied access to the +particular resource or directory you wanted to reach. Most often you +tried to change to a directory that doesn't exist on the server. +.It 10 +FTP accept failed. While waiting for the server to connect back when +an active FTP session is used, an error code was sent over the control +connection or similar. +.It 11 +FTP weird PASS reply. Curl couldn't parse the reply sent to the PASS +request. +.It 12 +During an active FTP session while waiting for the server to connect +back to curl, the timeout expired. +.It 13 +FTP weird PASV reply, Curl couldn't parse the reply sent to the PASV +request. +.It 14 +FTP weird 227 format. Curl couldn't parse the 227-line the server sent. +.It 15 +FTP can't get host. Couldn't resolve the host IP we got in the 227-line. +.It 16 +HTTP/2 error. A problem was detected in the HTTP2 framing layer. This +is somewhat generic and can be one out of several problems, see the +error message for details. +.It 17 +FTP couldn't set binary. Couldn't change transfer method to binary. +.It 18 +Partial file. Only a part of the file was transferred. +.It 19 +FTP couldn't download/access the given file, the RETR (or similar) command +failed. +.It 21 +FTP quote error. A quote command returned error from the server. +.It 22 +HTTP page not retrieved. The requested url was not found or returned +another error with the HTTP error code being 400 or above. This return +code only appears if +.Fl f | -fail +is used. +.It 23 +Write error. Curl couldn't write data to a local filesystem or similar. +.It 25 +FTP couldn't STOR file. The server denied the STOR operation, used for +FTP uploading. +.It 26 +Read error. Various reading problems. +.It 27 +Out of memory. A memory allocation request failed. +.It 28 +Operation timeout. The specified time-out period was reached according +to the conditions. +.It 30 +FTP PORT failed. The PORT command failed. Not all FTP servers support +the PORT command, try doing a transfer using PASV instead! +.It 31 +FTP couldn't use REST. The REST command failed. This command is used +for resumed FTP transfers. +.It 33 +HTTP range error. The range "command" didn't work. +.It 34 +HTTP post error. Internal post-request generation error. +.It 35 +SSL connect error. The SSL handshaking failed. +.It 36 +Bad download resume. Couldn't continue an earlier aborted download. +.It 37 +FILE couldn't read file. Failed to open the file. Permissions? +.It 38 +LDAP cannot bind. LDAP bind operation failed. +.It 39 +LDAP search failed. +.It 41 +Function not found. A required LDAP function was not found. +.It 42 +Aborted by callback. An application told curl to abort the operation. +.It 43 +Internal error. A function was called with a bad parameter. +.It 45 +Interface error. A specified outgoing interface could not be used. +.It 47 +Too many redirects. When following redirects, curl hit the maximum amount. +.It 48 +Unknown option specified to libcurl. This indicates that you passed a +weird option to curl that was passed on to libcurl and rejected. Read +up in the manual! +.It 49 +Malformed telnet option. +.It 51 +The peer's SSL certificate or SSH MD5 fingerprint was not OK. +.It 52 +The server didn't reply anything, which here is considered an error. +.It 53 +SSL crypto engine not found. +.It 54 +Cannot set SSL crypto engine as default. +.It 55 +Failed sending network data. +.It 56 +Failure in receiving network data. +.It 58 +Problem with the local certificate. +.It 59 +Couldn't use specified SSL cipher. +.It 60 +Peer certificate cannot be authenticated with known CA certificates. +.It 61 +Unrecognized transfer encoding. +.It 62 +Invalid LDAP URL. +.It 63 +Maximum file size exceeded. +.It 64 +Requested FTP SSL level failed. +.It 65 +Sending the data requires a rewind that failed. +.It 66 +Failed to initialise SSL Engine. +.It 67 +The user name, password, or similar was not accepted and curl failed +to log in. +.It 68 +File not found on TFTP server. +.It 69 +Permission problem on TFTP server. +.It 70 +Out of disk space on TFTP server. +.It 71 +Illegal TFTP operation. +.It 72 +Unknown TFTP transfer ID. +.It 73 +File already exists (TFTP). +.It 74 +No such user (TFTP). +.It 75 +Character conversion failed. +.It 76 +Character conversion functions required. +.It 77 +Problem with reading the SSL CA cert (path? access rights?). +.It 78 +The resource referenced in the URL does not exist. +.It 79 +An unspecified error occurred during the SSH session. +.It 80 +Failed to shut down the SSL connection. +.It 82 +Could not load CRL file, missing or wrong format (added in 7.19.0). +.It 83 +Issuer check failed (added in 7.19.0). +.It 84 +The FTP PRET command failed +.It 85 +RTSP: mismatch of CSeq numbers +.It 86 +RTSP: mismatch of Session Identifiers +.It 87 +unable to parse FTP file list +.It 88 +FTP chunk callback reported error +.It 89 +No connection available, the session will be queued +.It 90 +SSL public key does not matched pinned public key +.It 91 +Invalid SSL certificate status. +.It 92 +Stream error in HTTP/2 framing layer. +.It XX +.El +More error codes will appear here in future releases. The existing +ones are meant to never change. +.Sh AUTHORS +Daniel Stenberg is the main author of curl, but the whole list of +contributors is found in the separate THANKS file. +.Pp +gnurl is based on curl and is maintained by +.An ng0 Aq Mt ng0@n0.is . +This mdoc man page was derived from the curl automated groff page +generation output and is slowly being adjusted to reflect the smaller +feature set found in gnurl. +.Sh SEE ALSO +.Lk https://curl.haxx.se , +.Xr ftp 1 , +.Xr wget 1 |