cmdline-docs: more options converted over

docs/cmdline-opts/anyauth.d

@@ -0,0 +1,17 @@
+Long: anyauth
+Help: Pick any authentication method
+Protocols: HTTP
+See-also: proxy-anyauth basic digest
+---
+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 --basic, --digest, --ntlm, and --negotiate.
+
+Using --anyauth is not recommended if you do uploads from stdin, since it may
+require data to be sent twice and then the client must be able to rewind. If
+the need should arise when uploading from stdin, the upload operation will
+fail.
+
+Used together with --user.

docs/cmdline-opts/append.d

@@ -0,0 +1,8 @@
+Short: a
+Long: append
+Help: Append to target file when uploading
+Protocols: 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).

docs/cmdline-opts/basic.d

@@ -0,0 +1,11 @@
+Long: basic
+Help: Use HTTP Basic Authentication
+See-also: proxy-basic
+Protocols: 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
+--ntlm, --digest, or --negotiate).
+
+Used together with --user.

docs/cmdline-opts/cacert.d

@@ -0,0 +1,28 @@
+Long: cacert
+Arg: <CA certificate>
+Help: CA certificate to verify peer against
+Protocols: 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.
+
+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.
+
+The windows version of curl will automatically look for a CA certs file named
+\'curl-ca-bundle.crt\', either in the same directory as curl.exe, or in the
+Current Working Directory, or in any folder along your PATH.
+
+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.
+
+(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.
+
+If this option is used several times, the last one will be used.

docs/cmdline-opts/capath.d

@@ -0,0 +1,15 @@
+Long: capath
+Arg: <dir>
+Help: CA directory to verify peer against
+Protocols: 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 --capath can allow
+OpenSSL-powered curl to make SSL-connections much more efficiently than using
+--cacert if the --cacert file contains many CA certificates.
+
+If this option is set, the default capath value will be ignored, and if it is
+used several times, the last one will be used.

docs/cmdline-opts/cert-status.d

@@ -0,0 +1,13 @@
+Long: cert-status
+Protocols: TLS
+Added: 7.41.0
+Help: Verify the status of the server certificate
+---
+Tells curl to verify the status of the server certificate by using the
+Certificate Status Request (aka. OCSP stapling) TLS extension.
+
+If this option is enabled and the server sends an invalid (e.g. expired)
+response, if the response suggests that the server certificate has been revoked,
+or no response at all is received, the verification fails.
+
+This is currently only implemented in the OpenSSL, GnuTLS and NSS backends.

docs/cmdline-opts/cert-type.d

@@ -0,0 +1,10 @@
+Long: cert-type
+Protocols: TLS
+Arg: <type>
+Help: Certificate file type (DER/PEM/ENG)
+See-also: cert key key-type
+---
+Tells curl what certificate type the provided certificate is in. PEM, DER and
+ENG are recognized types.  If not specified, PEM is assumed.
+
+If this option is used several times, the last one will be used.

docs/cmdline-opts/cert.d

@@ -0,0 +1,32 @@
+Short: E
+Long: cert
+Arg: <certificate[:password]>
+Help: Client certificate file and password
+Protocols: TLS
+See-also: cert-type key key-type
+---
+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 --cert and --key to
+specify them independently.
+
+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.
+
+(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.
+
+If this option is used several times, the last one will be used.

docs/cmdline-opts/ciphers.d

@@ -0,0 +1,16 @@
+Long: ciphers
+Arg: <list of ciphers>
+help: SSL ciphers to use
+Protocols: TLS
+---
+Specifies which ciphers to use in the connection. The list of ciphers must
+specify valid ciphers. Read up on SSL cipher list details on this URL:
+
+ https://www.openssl.org/docs/apps/ciphers.html
+
+NSS ciphers are done differently than OpenSSL and GnuTLS. The full list of NSS
+ciphers is in the NSSCipherSuite entry at this URL:
+
+ https://git.fedorahosted.org/cgit/mod_nss.git/plain/docs/mod_nss.html#Directives
+
+If this option is used several times, the last one will be used.

docs/cmdline-opts/compressed.d

@@ -0,0 +1,7 @@
+Long: compressed
+Help: Request compressed response
+Protocols: 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.

docs/cmdline-opts/config.d

@@ -0,0 +1,60 @@
+Long: config
+Arg: <file>
+Help: Read config from a file
+Short: K
+---
+Specify which config file to read curl arguments from. The config file is a
+text file in which command line arguments can be written which then will be
+used as if they were written on the actual command line.
+
+Options and their parameters must be specified on the same config file line,
+separated by whitespace, colon, or the equals sign. Long option names can
+optionally be given in the config file without the initial double dashes and
+if so, the colon or equals characters can be used as separators. If the option
+is specified with one or two dashes, there can be no colon or equals character
+between the option and its parameter.
+
+If the parameter is to contain whitespace, 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.
+
+Specify the filename to --config as '-' to make curl read the file from stdin.
+
+Note that to be able to specify a URL in the config file, you need to specify
+it using the --url option, and not by simply writing the URL on its own
+line. So, it could look similar to this:
+
+url = "https://curl.haxx.se/docs/"
+
+When curl is invoked, it always (unless --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:
+
+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 getpwuid() on
+Unix-like systems (which returns the home dir given the current user in your
+system). On Windows, it then checks for the APPDATA variable, or as a last
+resort the '%USERPROFILE%\\Application Data'.
+
+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.
+
+.nf
+# --- Example file ---
+# this is a comment
+url = "example.com"
+output = "curlhere.html"
+user-agent = "superagent/1.0"
+
+# and fetch another URL too
+url = "example.com/docs/manpage.html"
+-O
+referer = "http://nowhereatall.example.com/"
+# --- End of example file ---
+.fi
+
+This option can be used multiple times to load multiple config files.

docs/cmdline-opts/connect-timeout.d

@@ -0,0 +1,11 @@
+Long: connect-timeout
+Arg: <seconds>
+Help: Maximum time allowed for connection
+See-also: max-time
+---
+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.
+
+If this option is used several times, the last one will be used.

docs/cmdline-opts/continue-at.d

@@ -0,0 +1,15 @@
+Short: C
+Long: continue-at
+Arg: <offset>
+Help: Resumed transfer offset
+See-also: range
+---
+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.
+
+Use "-C -" to tell curl to automatically find out where/how to resume the
+transfer. It then uses the given output/input files to figure that out.
+
+If this option is used several times, the last one will be used.

docs/cmdline-opts/create-dirs.d

@@ -0,0 +1,9 @@
+Long: create-dirs
+Help: Create necessary local directory hierarchy
+---
+When used in conjunction with the --output option, curl will create the
+necessary local directory hierarchy as needed. This option creates the dirs
+mentioned with the --output option, nothing else. If the --output file name
+uses no dir or if the dirs it mentions already exist, no dir will be created.
+
+To create remote directories when using FTP or SFTP, try --ftp-create-dirs.

docs/cmdline-opts/crlf.d

@@ -0,0 +1,7 @@
+Long: crlf
+Help: Convert LF to CRLF in upload
+Protocols: FTP SMTP
+---
+Convert LF to CRLF in upload. Useful for MVS (OS/390).
+
+(SMTP added in 7.40.0)

docs/cmdline-opts/crlfile.d

@@ -0,0 +1,10 @@
+Long: crfile
+Arg: <file>
+Protocols: TLS
+Help: Get a CRL list in PEM format from the given file
+Added: 7.19.7
+---
+Provide a file using PEM format with a Certificate Revocation List that may
+specify peer certificates that are to be considered revoked.
+
+If this option is used several times, the last one will be used.

docs/cmdline-opts/data-ascii.d

@@ -0,0 +1,5 @@
+Long: data-ascii
+Arg: <data>
+Help: HTTP POST ASCII data
+Protocols: HTTP
+Redirect: data

docs/cmdline-opts/data-binary.d

@@ -0,0 +1,13 @@
+Long: data-binary
+Arg: <data>
+Help: HTTP POST binary data
+Protocols: HTTP
+---
+This posts data exactly as specified with no extra processing whatsoever.
+
+If you start the data with the letter @, the rest should be a filename.  Data
+is posted in a similar manner as --data does, except that newlines and
+carriage returns are preserved and conversions are never done.
+
+If this option is used several times, the ones following the first will append
+data as described in --data.

docs/cmdline-opts/data-raw.d

@@ -0,0 +1,9 @@
+Long: data-raw
+Arg: <data>
+Protocols: HTTP
+Help: HTTP POST data, '@' allowed
+Added: 7.43.0
+See-also: data
+---
+This posts data similarly to --data but without the special
+interpretation of the @ character.

docs/cmdline-opts/data-urlencode.d

@@ -0,0 +1,33 @@
+Long: data-urlencode
+Arg: <data>
+Help: HTTP POST data url encoded
+Protocols: HTTP
+See-also: data data-raw
+Added: 7.18.0
+---
+This posts data, similar to the other --data options with the exception
+that this performs URL-encoding.
+
+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:
+.RS
+.IP "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!
+.IP "=content"
+This will make curl URL-encode the content and pass that on. The preceding =
+symbol is not included in the data.
+.IP "name=content"
+This will make curl URL-encode the content part and pass that on. Note that
+the name part is expected to be URL-encoded already.
+.IP "@filename"
+This will make curl load data from the given file (including any newlines),
+URL-encode that data and pass it on in the POST.
+.IP "name@filename"
+This will make curl load data from the given file (including any newlines),
+URL-encode that data and pass it on in the POST. The name part gets an equal
+sign appended, resulting in \fIname=urlencoded-file-content\fP. Note that the
+name is expected to be URL-encoded already.
+.RE

docs/cmdline-opts/data.d

@@ -0,0 +1,30 @@
+Long: data
+Short: d
+Arg: <data>
+Help: HTTP POST data
+Protocols: HTTP
+See-also: data-binary data-urlencode data-raw
+Mutexed: form head upload
+---
+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 --form.
+
+--data-raw is almost the same but does not have a special interpretation of
+the @ character. To post data purely binary, you should instead use the
+--data-binary option.  To URL-encode the value of a form field you may use
+--data-urlencode.
+
+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'.
+
+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 \fI--data\fP @foobar. When --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
+--data-raw instead.

docs/cmdline-opts/delegation.d

@@ -0,0 +1,16 @@
+Long: delegation
+Arg: <LEVEL>
+Help: GSS-API delegation permission
+Protocols: GSS/kerberos
+---
+Set LEVEL to tell the server what it is allowed to delegate when it
+comes to user credentials.
+.RS
+.IP "none"
+Don't allow any delegation.
+.IP "policy"
+Delegates if and only if the OK-AS-DELEGATE flag is set in the Kerberos
+service ticket, which is a matter of realm policy.
+.IP "always"
+Unconditionally allow the server to delegate.
+.RE

docs/cmdline-opts/digest.d

@@ -0,0 +1,11 @@
+Long: digest
+Help: Use HTTP Digest Authentication
+Protocols: HTTP
+Mutexed: basic ntlm negotiate
+See-also: user proxy-digest anyauth
+---
+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 --user option to set user name and password.
+
+If this option is used several times, only the first one is used.

docs/cmdline-opts/disable-eprt.d

@@ -0,0 +1,19 @@
+Long: disable-eprt
+Help: Inhibit using EPRT or LPRT
+Protocols: 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.
+
+--eprt can be used to explicitly enable EPRT again and --no-eprt is an alias
+for --disable-eprt.
+
+If the server is accessed using IPv6, this option will have no effect as EPRT
+is necessary then.
+
+Disabling EPRT only changes the active behavior. If you want to switch to
+passive mode you need to not use --ftp-port or force it with --ftp-pasv.

docs/cmdline-opts/dns-interface.d

@@ -0,0 +1,11 @@
+Long: dns-interface
+Arg: <interface>
+Help: Interface to use for DNS requests
+Protocols: DNS
+See-also: dns-ipv4-addr dns-ipv6-addr
+Added: 7.33.0
+Requires: c-ares
+---
+Tell curl to send outgoing DNS requests through <interface>. This option is a
+counterpart to --interface (which does not affect DNS). The supplied string
+must be an interface name (not an address).

docs/cmdline-opts/dns-ipv4-addr.d

@@ -0,0 +1,11 @@
+Long: dns-ipv4-addr
+Arg: <address>
+Help: IPv4 address to use for DNS requests
+Protocols: DNS
+See-also: dns-interface dns-ipv6-addr
+Added: 7.33.0
+Requires: c-ares
+---
+Tell curl to bind to <ip-address> when making IPv4 DNS requests, so that
+the DNS requests originate from this address. The argument should be a
+single IPv4 address.

docs/cmdline-opts/dns-ipv6-addr.d

@@ -0,0 +1,11 @@
+Long: dns-ipv6-addr
+Arg: <address>
+Help: IPv6 address to use for DNS requests
+Protocols: DNS
+See-also: dns-interface dns-ipv4-addr
+Added: 7.33.0
+Requires: c-ares
+---
+Tell curl to bind to <ip-address> when making IPv6 DNS requests, so that
+the DNS requests originate from this address. The argument should be a
+single IPv6 address.

docs/cmdline-opts/dns-servers.d

@@ -0,0 +1,10 @@
+Long: dns-servers
+Arg: <addresses>
+Help: DNS server addrs to use
+Requires: c-ares
+Added: 7.33.0
+---
+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.

docs/cmdline-opts/dump-header.d

@@ -0,0 +1,18 @@
+Long: dump-header
+Short: D
+Arg: <filename>
+Help: Write the received headers to <filename>
+Protocols: HTTP FTP
+See-also: output
+---
+Write the received protocol headers to the specified file.
+
+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 --cookie option! The --cookie-jar option is a
+better way to store cookies.
+
+When used in FTP, the FTP server response lines are considered being "headers"
+and thus are saved there.
+
+If this option is used several times, the last one will be used.

docs/cmdline-opts/egd-file.d

@@ -0,0 +1,7 @@
+Long: egd-file
+Help: EGD socket path for random data
+Protocols: TLS
+See-also: random-file
+---
+Specify the path name to the Entropy Gathering Daemon socket. The socket is
+used to seed the random engine for SSL connections.

docs/cmdline-opts/engine.d

@@ -0,0 +1,8 @@
+Long: engine
+Arg: <name>
+Help: Crypto engine to use
+Protocols: TLS
+---
+Select the OpenSSL crypto engine to use for cipher operations. Use \fI--engine
+list\fP to print a list of build-time supported engines. Note that not all (or
+none) of the engines may be available at run-time.

docs/cmdline-opts/environment.d

@@ -0,0 +1,7 @@
+Long: environment
+Help: Write results to environment variables
+Requires: RISC OS
+---
+Sets a range of environment variables, using the names the --write-out option
+supports, to allow easier extraction of useful information after having run
+curl.

docs/cmdline-opts/expect100-timeout.d

@@ -0,0 +1,11 @@
+Long: expect100-timeout
+Arg: <seconds>
+Help: How long to wait for 100-continue
+Protocols: HTTP
+Added: 7.47.0
+See-also: connect-timeout
+---
+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.

docs/cmdline-opts/fail-early.d

@@ -0,0 +1,18 @@
+Long: fail-early
+Help: Fail on first transfer error, do not continue
+Added: 7.52.0
+---
+Fail and exit on first detected error.
+
+When curl is used to do multiple transfers on the command line, it will
+attempt to operate on each given URL, one by one. By default, it will ignore
+errors if there are more URLs given and the last URL's success will determine
+the error code curl returns. So early failures will be "hidden" by subsequent
+successful transfers.
+
+Using this option, curl will instead return an error on the first transfers
+that fails, independent on the amount of more URLs that are given on the
+command line. This way, no transfer failures go undetected by scripts and
+similar.
+
+This option will apply for all given URLs even if you use --next.

docs/cmdline-opts/fail.d

@@ -0,0 +1,14 @@
+Long: fail
+Short: f
+Protocols: HTTP
+Help: Fail silently (no output at all) on HTTP errors
+---
+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.
+
+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).

docs/cmdline-opts/false-start.d

@@ -0,0 +1,12 @@
+Long: false-start
+Help: Enable TLS False Start
+Protocols: TLS
+Added: 7.42.0
+---
+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.
+
+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.

docs/cmdline-opts/form-string.d

@@ -0,0 +1,10 @@
+Long: form-string
+Help: Specify HTTP multipart POST data
+Protocols: HTTP
+See-also: form
+---
+Similar to --form 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 --form\fP if
+there's any possibility that the string value may accidentally trigger the
+\&'@' or \&'<' features of --form.

docs/cmdline-opts/form.d

@@ -0,0 +1,54 @@
+Long: form
+Short: F
+Arg: <name=content>
+Help: Specify HTTP multipart POST data
+Protocols: HTTP
+Mutexed: data head upload
+---
+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. 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.
+
+Example: to send an image to a server, where \&'profile' is the name of the
+form-field to which portrait.jpg will be the input:
+
+ curl -F profile=@portrait.jpg https://example.com/upload.cgi
+
+To read content from stdin instead of a file, use - as the filename. This goes
+for both @ and < constructs. Unfortunately it does not support reading the
+file from a named pipe or similar, as it needs the full size before the
+transfer starts.
+
+You can also tell curl what Content-Type to use by using 'type=', in a manner
+similar to:
+
+ curl -F "web=@index.html;type=text/html" example.com
+
+or
+
+ curl -F "name=daniel;type=text/foo" example.com
+
+You can also explicitly change the name field of a file upload part by setting
+filename=, like this:
+
+ curl -F "file=@localfile;filename=nameinpost" example.com
+
+If filename/path contains ',' or ';', it must be quoted by double-quotes like:
+
+ curl -F "file=@\\"localfile\\";filename=\\"nameinpost\\"" example.com
+
+or
+
+ curl -F 'file=@"localfile";filename="nameinpost"' example.com
+
+Note that if a filename/path is quoted by double-quotes, any double-quote
+or backslash within the filename must be escaped by backslash.
+
+See further examples and details in the MANUAL.
+
+This option can be used multiple times.

docs/cmdline-opts/ftp-account.d

@@ -0,0 +1,10 @@
+Long: ftp-account
+Arg: <data>
+Help: Account data string
+Protocols: FTP
+Added: 7.13.0
+---
+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.
+
+If this option is used several times, the last one will be used.

docs/cmdline-opts/ftp-alternative-to-user.d

@@ -0,0 +1,10 @@
+Long: ftp-alternative-to-user
+Arg: <command>
+Help: String to replace USER [name]
+Protocols: FTP
+Added: 7.15.5
+---
+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.

docs/cmdline-opts/ftp-create-dirs.d

@@ -0,0 +1,8 @@
+Long: ftp-create-dirs
+Protocols: FTP SFTP
+Help: Create the remote dirs if not present
+See-also: create-dirs
+---
+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.

docs/cmdline-opts/ftp-method.d

@@ -0,0 +1,21 @@
+Long: ftp-method
+Arg: <method>
+Help: Control CWD usage
+Protocols: FTP
+Added: 7.15.1
+---
+Control what method curl should use to reach a file on an FTP(S)
+server. The method argument should be one of the following alternatives:
+.RS
+.IP multicwd
+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.
+.IP 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.
+.IP 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'.
+.RE

docs/cmdline-opts/ftp-pasv.d

@@ -0,0 +1,16 @@
+Long: ftp-pasv
+Help: Use PASV/EPSV instead of PORT
+Protocols: FTP
+Added: 7.11.0
+See-also: disable-epsv
+---
+Use passive mode for the data connection. Passive is the internal default
+behavior, but using this option can be used to override a previous --ftp-port
+option.
+
+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 --ftp-port again.
+
+Passive mode means that curl will try the EPSV command first and then PASV,
+unless --disable-epsv is used.

docs/cmdline-opts/ftp-pret.d

@@ -0,0 +1,8 @@
+Long: ftp-pret
+Help: Send PRET before PASV
+Protocols: FTP
+Added: 7.20.0
+---
+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.

docs/cmdline-opts/ftp-skip-pasv-ip.d

@@ -0,0 +1,12 @@
+Long: ftp-skip-pasv-ip
+Help: Skip the IP address for PASV
+Protocols: FTP
+Added: 7.14.2
+See-also: ftp-pasv
+---
+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.
+
+This option has no effect if PORT, EPRT or EPSV is used instead of PASV.

docs/cmdline-opts/ftp-ssl-ccc-mode.d

@@ -0,0 +1,11 @@
+Long: ftp-ssl-ccc-mode
+Arg: <active/passive>
+Help: Set CCC mode
+Protocols: FTP
+Added: 7.16.2
+See-also: ftp-ssl-ccc
+---
+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.

docs/cmdline-opts/ftp-ssl-ccc.d

@@ -0,0 +1,10 @@
+Long: ftp-ssl-ccc
+Help: Send CCC after authenticating
+Protocols: FTP
+See-also: ssl ftp-ssl-ccc-mode
+Added: 7.16.1
+---
+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.

docs/cmdline-opts/ftp-ssl-control.d

@@ -0,0 +1,8 @@
+Long: ftp-ssl-control
+Help: Require SSL/TLS for FTP login, clear for transfer
+Protocols: FTP
+Added: 7.16.0
+---
+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.

docs/cmdline-opts/ftp-ssl-reqd.d

@@ -0,0 +1,3 @@
+Long: ftp-ssl-reqd
+Help: Require SSL/TLS
+Redirect: ssl-reqd

docs/cmdline-opts/ftp-ssl.d

@@ -0,0 +1,3 @@
+Long: ftp-ssl
+Help: Try SSL/TLS
+Redirect: ssl

docs/cmdline-opts/get.d

@@ -0,0 +1,15 @@
+Long: get
+Short: G
+Help: Put the post data in the URL and use GET
+---
+When used, this option will make all data specified with --data, --data-binary
+or --data-urlencode to be used in an HTTP GET request instead of the POST
+request that otherwise would be used. The data will be appended to the URL
+with a '?' separator.
+
+If used in combination with --head, the POST data will instead be appended to
+the URL with a HEAD request.
+
+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.

docs/cmdline-opts/globoff.d

@@ -0,0 +1,8 @@
+Long: globoff
+Short: g
+Help: Disable URL sequences and ranges using {} and []
+---
+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.

docs/cmdline-opts/head.d

@@ -0,0 +1,8 @@
+Long: head
+Short: I
+Help: Show document info only
+Protocols: 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.

docs/cmdline-opts/header.d

@@ -0,0 +1,39 @@
+Long: header
+Short: H
+Arg: <header>
+Help: Pass custom header LINE to server
+Protocols: 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 \-H \&"X-Custom-Header;" to send "X-Custom-Header:".
+
+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.
+
+See also the --user-agent and --referer options.
+
+Starting in 7.37.0, you need --proxy-header to send custom headers intended
+for a proxy.
+
+Example:
+
+ curl -H "X-First-Name: Joe" http://example.com/
+
+\fBWARNING\fP: headers set with this option will be set in all requests - even
+after redirects are followed, like when told with \fB-L, --location\fP. This
+can lead to the header being sent to other hosts than the original host, so
+sensitive headers should be used with caution combined with following
+redirects.
+
+This option can be used multiple times to add/replace/remove multiple headers.

docs/cmdline-opts/hostpubmd5.d

@@ -0,0 +1,9 @@
+Long: hostpubmd5
+Arg: <md5>
+Help: Acceptable MD5 hash of the host public key
+Protocols: SFTP SCP
+Added: 7.17.1
+---
+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.

docs/cmdline-opts/ignore-content-length.d

@@ -0,0 +1,10 @@
+Long: ignore-content-length
+Help: Ignore the size of the remote resource
+Protocols: 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.
+
+For FTP (since 7.46.0), skip the RETR command to figure out the size before
+downloading a file.

docs/cmdline-opts/include.d

@@ -0,0 +1,7 @@
+Long: include
+Short: i
+Help: Include protocol headers in the output
+See-also: verbose
+---
+Include the HTTP-header in the output. The HTTP-header includes things like
+server-name, date of the document, HTTP-version and more...

docs/cmdline-opts/insecure.d

@@ -0,0 +1,12 @@
+Long: insecure
+Short: k
+Help: Allow insecure connections when using SSL
+Protocols: TLS
+---
+This option explicitly allows curl to perform "insecure" SSL connections and
+transfers. All SSL connections are attempted to be made secure by using the CA
+certificate bundle installed by default. This makes all connections considered
+\&"insecure" fail unless --insecure is used.
+
+See this online resource for further details:
+ https://curl.haxx.se/docs/sslcerts.html

docs/cmdline-opts/interface.d

@@ -0,0 +1,12 @@
+Long: interface
+Arg: <name>
+Help: Use network INTERFACE (or address)
+See-also: dns-interface
+---
+
+Perform an operation using a specified interface. You can enter interface
+name, IP address or host name. An example could look like:
+
+ curl --interface eth0:1 https://www.example.com/
+
+If this option is used several times, the last one will be used.

docs/cmdline-opts/ipv4.d

@@ -0,0 +1,12 @@
+Short: 4
+Long: ipv4
+Tags: Versions
+Protocols:
+Added:
+Mutexed: ipv6
+Requires:
+See-also: http1.1 http2
+Help: Resolve names to IPv4 addresses
+---
+This option tells curl to resolve names to IPv4 addresses only, and not for
+example try IPv6.

docs/cmdline-opts/ipv6.d

@@ -0,0 +1,12 @@
+Short: 6
+Long: ipv6
+Tags: Versions
+Protocols:
+Added:
+Mutexed: ipv6
+Requires:
+See-also: http1.1 http2
+Help: Resolve names to IPv6 addresses
+---
+This option tells curl to resolve names to IPv6 addresses only, and not for
+example try IPv4.

docs/cmdline-opts/junk-session-cookies.d

@@ -0,0 +1,10 @@
+Long: junk-session-cookies
+Short: j
+Help: Ignore session cookies read from file
+Protocols: HTTP
+See-also: cookie cookie-jar
+---
+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.

docs/cmdline-opts/keepalive-time.d

@@ -0,0 +1,13 @@
+Long: keepalive-time
+Arg: <seconds>
+Help: Interval time for keepalive probes
+Added: 7.18.0
+---
+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 --no-keepalive is used.
+
+If this option is used several times, the last one will be used. If
+unspecified, the option defaults to 60 seconds.

docs/cmdline-opts/key-type.d

@@ -0,0 +1,9 @@
+Long: key-type
+Arg: <type>
+Help: Private key file type (DER/PEM/ENG)
+Protocols: TLS
+---
+Private key file type. Specify which type your --key provided private key
+is. DER, PEM, and ENG are supported. If not specified, PEM is assumed.
+
+If this option is used several times, the last one will be used.

docs/cmdline-opts/key.d

@@ -0,0 +1,10 @@
+Long: key
+Arg: <key>
+Protocols: TLS SSH
+Help: Private key file name
+---
+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:
+'~/.ssh/id_rsa', '~/.ssh/id_dsa', './id_rsa', './id_dsa'.
+
+If this option is used several times, the last one will be used.

docs/cmdline-opts/krb.d

@@ -0,0 +1,11 @@
+Long: krb
+Arg: <level>
+Help: Enable Kerberos with security <level>
+Protocols: FTP
+Requires: Kerberos
+---
+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.
+
+If this option is used several times, the last one will be used.

docs/cmdline-opts/krb4.d

@@ -0,0 +1,2 @@
+Long: krb4
+Redirect: krb

docs/cmdline-opts/libcurl.d

@@ -0,0 +1,11 @@
+Long: libcurl
+Arg: <file>
+Help: Dump libcurl equivalent code of this command line
+Added: 7.16.1
+---
+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!
+
+If this option is used several times, the last given file name will be
+used.

docs/cmdline-opts/limit-rate.d

@@ -0,0 +1,18 @@
+Long: limit-rate
+Arg: <speed>
+Help: Limit transfer speed to RATE
+---
+Specify the maximum transfer rate you want curl to use - for both downloads
+and uploads. This feature is useful if you have a limited pipe and you'd like
+your transfer not to use your entire bandwidth. To make it slower than it
+otherwise would be.
+
+The given speed is measured in bytes/second, unless a suffix is appended.
+Appending '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.
+
+If you also use the --speed-limit option, that option will take precedence and
+might cripple the rate-limiting slightly, to help keeping the speed-limit
+logic working.
+
+If this option is used several times, the last one will be used.

docs/cmdline-opts/list-only.d

@@ -0,0 +1,24 @@
+Long: list-only
+Short: l
+Protocols: FTP POP3
+Help: List only mode
+Added: 7.21.5
+---
+(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.
+
+Note: Some FTP servers list only files in their response to NLST; they do not
+include sub-directories and symbolic links.
+
+(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.
+
+Note: When combined with --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.

docs/cmdline-opts/local-port.d

@@ -0,0 +1,9 @@
+Long: local-port
+Arg: <num/range>
+Help: Force use of RANGE for local port numbers
+Added: 7.15.2
+---
+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.

docs/cmdline-opts/location-trusted.d

@@ -0,0 +1,9 @@
+Long: location-trusted
+Help: Like --location, and send auth to other hosts
+Protocols: HTTP
+See-also: user
+---
+Like --location, but will allow sending the name + password to all hosts that
+the site may redirect to. This may or may not introduce a security breach if
+the site redirects you to a site to which you'll send your authentication info
+(which is plaintext in the case of HTTP Basic authentication).

docs/cmdline-opts/location.d

@@ -0,0 +1,23 @@
+Long: location
+Short: L
+Help: Follow redirects
+Protocols: 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
+--include or --head, headers from all requested pages will be shown. When
+authentication is used, curl only sends its credentials to the initial
+host. If a redirect takes curl to a different host, it won't be able to
+intercept the user+password. See also --location-trusted on how to change
+this. You can limit the amount of redirects to follow by using the
+--max-redirs option.
+
+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.
+
+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: --post301, --post302 and
+--post303.

docs/cmdline-opts/login-options.d

@@ -0,0 +1,13 @@
+Long: login-options
+Arg: <options>
+Protocols: IMAP POP3 SMTP
+Added: 7.34.0
+---
+Specify the login options to use during server authentication.
+
+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
+
+If this option is used several times, the last one will be used.

docs/cmdline-opts/max-time.d

@@ -0,0 +1,13 @@
+Long: max-time
+Short: m
+Arg: <time>
+Help: Maximum time allowed for the transfer
+See-also: connect-timeout
+---
+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.
+
+If this option is used several times, the last one will be used.

docs/cmdline-opts/pinnedpubkey.d

@@ -0,0 +1,27 @@
+Long: pinnedpubkey
+Arg: <hashes>
+Help: FILE/HASHES Public key to verify peer against
+Protocols: 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 \';\'
+
+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.
+
+PEM/DER support:
+  7.39.0: OpenSSL, GnuTLS and GSKit
+  7.43.0: NSS and wolfSSL/CyaSSL
+  7.47.0: mbedtls
+  7.49.0: PolarSSL
+sha256 support:
+  7.44.0: OpenSSL, GnuTLS, NSS and wolfSSL/CyaSSL.
+  7.47.0: mbedtls
+  7.49.0: PolarSSL
+Other SSL backends not supported.
+
+If this option is used several times, the last one will be used.

docs/cmdline-opts/referer.d

@@ -0,0 +1,12 @@
+Long: referer
+Protocols: HTTP
+Help: Referer URL
+See-also: user-agent header
+---
+Sends the "Referrer Page" information to the HTTP server. This can also be set
+with the --header flag of course.  When used with --location you can append
+";auto" to the --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 --referer.
+
+If this option is used several times, the last one will be used.

docs/cmdline-opts/remote-header-name.d

@@ -0,0 +1,19 @@
+Long: remote-header-name
+Short: J
+Protocols: HTTP
+Help: Use the header-provided filename
+---
+This option tells the --remote-name option to use the server-specified
+Content-Disposition filename instead of extracting a filename from the URL.
+
+If the server 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.
+
+There's no attempt to decode %-sequences (yet) in the provided file name, so
+this option may provide you with rather unexpected file names.
+
+\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.

docs/cmdline-opts/sslv2.d

@@ -0,0 +1,13 @@
+Short: 2
+Long: sslv2
+Tags: Versions
+Protocols: SSL
+Added:
+Mutexed: sslv3 tlsv1 tlsv1.1 tlsv1.2
+Requires: TLS
+See-also: http1.1 http2
+Help: Use SSLv2
+---
+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).

docs/cmdline-opts/sslv3.d

@@ -0,0 +1,13 @@
+Short: 3
+Long: sslv3
+Tags: Versions
+Protocols: SSL
+Added:
+Mutexed: sslv2 tlsv1 tlsv1.1 tlsv1.2
+Requires: TLS
+See-also: http1.1 http2
+Help: Use SSLv3
+---
+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).

docs/cmdline-opts/use-ascii.d

@@ -0,0 +1,8 @@
+Short: B
+Long: use-ascii
+Help: Use ASCII/text transfer
+Protocols: FTP LDAP
+---
+Enable ASCII transfer. For FTP, this can also be enforced by using an URL that
+ends with ";type=A". This option causes data sent to stdout to be in text mode
+for win32 systems.

docs/cmdline-opts/user-agent.d

@@ -0,0 +1,12 @@
+Short: A
+Long: user-agent
+Arg: <name>
+Help: Send User-Agent <name> to server
+Protocols: 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 can also be set
+with the --header option of course.
+
+If this option is used several times, the last one will be used.

docs/cmdline-opts/verbose.d

@@ -2,6 +2,7 @@ Short: v
 Long: verbose
 Mutexed: trace trace-ascii
 Help: Make the operation more talkative
+See-also: include
 ---
 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"