curl.1: provide examples for each option
The file format for each option now features a "Example:" header that
can provide one or more examples that get rendered appropriately in the
output. All options MUST have at least one example or gen.pl complains
at build-time.
This fix also does a few other minor format and consistency cleanups.
Closes #7654
diff --git a/docs/cmdline-opts/MANPAGE.md b/docs/cmdline-opts/MANPAGE.md
index b903bc2..f7f09eb 100644
--- a/docs/cmdline-opts/MANPAGE.md
+++ b/docs/cmdline-opts/MANPAGE.md
@@ -28,6 +28,7 @@
Requires: (space separated list of features this requires, no dashes)
See-also: (space separated list of related options, no dashes)
Help: (short text for the --help output for this option)
+ Example: (example command line, without "curl" and can use `$URL`)
--- (end of meta-data)
### Body
diff --git a/docs/cmdline-opts/abstract-unix-socket.d b/docs/cmdline-opts/abstract-unix-socket.d
index 8403cab..e26048f 100644
--- a/docs/cmdline-opts/abstract-unix-socket.d
+++ b/docs/cmdline-opts/abstract-unix-socket.d
@@ -4,6 +4,7 @@
Added: 7.53.0
Protocols: HTTP
Category: connection
+Example: --abstract-unix-socket socketpath $URL
---
Connect through an abstract Unix domain socket, instead of using the network.
Note: netstat shows the path of an abstract socket prefixed with '@', however
diff --git a/docs/cmdline-opts/alt-svc.d b/docs/cmdline-opts/alt-svc.d
index 5598b59..914b1fb 100644
--- a/docs/cmdline-opts/alt-svc.d
+++ b/docs/cmdline-opts/alt-svc.d
@@ -4,9 +4,8 @@
Help: Enable alt-svc with this cache file
Added: 7.64.1
Category: http
+Example: --alt-svc svc.txt $URL
---
-WARNING: this option is experimental. Do not use in production.
-
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.
diff --git a/docs/cmdline-opts/anyauth.d b/docs/cmdline-opts/anyauth.d
index bec0c0c..427a64c 100644
--- a/docs/cmdline-opts/anyauth.d
+++ b/docs/cmdline-opts/anyauth.d
@@ -3,6 +3,7 @@
Protocols: HTTP
See-also: proxy-anyauth basic digest
Category: http proxy auth
+Example: --anyauth --user me:pwd $URL
---
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
diff --git a/docs/cmdline-opts/append.d b/docs/cmdline-opts/append.d
index 8bdb259..8afaf0e 100644
--- a/docs/cmdline-opts/append.d
+++ b/docs/cmdline-opts/append.d
@@ -3,6 +3,7 @@
Help: Append to target file when uploading
Protocols: FTP SFTP
Category: ftp sftp
+Example: --upload-file local --append ftp://example.com/
---
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
diff --git a/docs/cmdline-opts/aws-sigv4.d b/docs/cmdline-opts/aws-sigv4.d
index 26546df..db98864 100644
--- a/docs/cmdline-opts/aws-sigv4.d
+++ b/docs/cmdline-opts/aws-sigv4.d
@@ -3,6 +3,7 @@
Help: Use AWS V4 signature authentication
Category: auth http
Added: 7.75.0
+Example: --aws-sigv4 "aws:amz:east-2:es" --user "key:secret" $URL
---
Use AWS V4 signature authentication in the transfer.
diff --git a/docs/cmdline-opts/basic.d b/docs/cmdline-opts/basic.d
index e222c51..62d2c22 100644
--- a/docs/cmdline-opts/basic.d
+++ b/docs/cmdline-opts/basic.d
@@ -3,6 +3,7 @@
See-also: proxy-basic
Protocols: HTTP
Category: auth
+Example: -u name:password --basic $URL
---
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
diff --git a/docs/cmdline-opts/cacert.d b/docs/cmdline-opts/cacert.d
index 793d8c1..1f38040 100644
--- a/docs/cmdline-opts/cacert.d
+++ b/docs/cmdline-opts/cacert.d
@@ -3,6 +3,7 @@
Help: CA certificate to verify peer against
Protocols: TLS
Category: tls
+Example: --cacert CA-file.txt $URL
---
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
@@ -26,9 +27,9 @@
certificates in the system and user Keychain to verify the peer, which is the
preferred method of verifying the peer's certificate chain.
-(Schannel only) This option is supported for Schannel in Windows 7 or later 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).
+(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).
If this option is used several times, the last one will be used.
diff --git a/docs/cmdline-opts/capath.d b/docs/cmdline-opts/capath.d
index 4ce077a..ba407ed 100644
--- a/docs/cmdline-opts/capath.d
+++ b/docs/cmdline-opts/capath.d
@@ -3,6 +3,7 @@
Help: CA directory to verify peer against
Protocols: TLS
Category: tls
+Example: --capath /local/directory $URL
---
Tells curl to use the specified certificate directory to verify the
peer. Multiple paths can be provided by separating them with ":" (e.g.
diff --git a/docs/cmdline-opts/cert-status.d b/docs/cmdline-opts/cert-status.d
index 63e3520..360e5c9 100644
--- a/docs/cmdline-opts/cert-status.d
+++ b/docs/cmdline-opts/cert-status.d
@@ -3,6 +3,7 @@
Added: 7.41.0
Help: Verify the status of the server cert via OCSP-staple
Category: tls
+Example: --cert-status $URL
---
Tells curl to verify the status of the server certificate by using the
Certificate Status Request (aka. OCSP stapling) TLS extension.
diff --git a/docs/cmdline-opts/cert-type.d b/docs/cmdline-opts/cert-type.d
index b041bcb..9fcbfe7 100644
--- a/docs/cmdline-opts/cert-type.d
+++ b/docs/cmdline-opts/cert-type.d
@@ -4,6 +4,7 @@
Help: Certificate type (DER/PEM/ENG)
See-also: cert key key-type
Category: tls
+Example: --cert-type PEM --cert file $URL
---
Tells curl what type the provided client certificate is using. PEM, DER, ENG
and P12 are recognized types. If not specified, PEM is assumed.
diff --git a/docs/cmdline-opts/cert.d b/docs/cmdline-opts/cert.d
index 2938e57..8e0fb88 100644
--- a/docs/cmdline-opts/cert.d
+++ b/docs/cmdline-opts/cert.d
@@ -5,6 +5,7 @@
Protocols: TLS
See-also: cert-type key key-type
Category: tls
+Example: --cert certfile --key keyfile $URL
---
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
diff --git a/docs/cmdline-opts/ciphers.d b/docs/cmdline-opts/ciphers.d
index 723b959..c2cb92e 100644
--- a/docs/cmdline-opts/ciphers.d
+++ b/docs/cmdline-opts/ciphers.d
@@ -3,6 +3,7 @@
Help: SSL ciphers to use
Protocols: TLS
Category: tls
+Example: --ciphers ECDHE-ECDSA-AES256-CCM8 $URL
---
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:
diff --git a/docs/cmdline-opts/compressed-ssh.d b/docs/cmdline-opts/compressed-ssh.d
index 849fe18..d95c6ad 100644
--- a/docs/cmdline-opts/compressed-ssh.d
+++ b/docs/cmdline-opts/compressed-ssh.d
@@ -3,6 +3,7 @@
Protocols: SCP SFTP
Added: 7.56.0
Category: scp ssh
+Example: --compressed-ssh sftp://example.com/
---
Enables built-in SSH compression.
This is a request, not an order; the server may or may not do it.
diff --git a/docs/cmdline-opts/compressed.d b/docs/cmdline-opts/compressed.d
index dedd0e9..945beb8 100644
--- a/docs/cmdline-opts/compressed.d
+++ b/docs/cmdline-opts/compressed.d
@@ -2,6 +2,7 @@
Help: Request compressed response
Protocols: HTTP
Category: http
+Example: --compressed $URL
---
Request a compressed response using one of the algorithms curl supports, and
automatically decompress the content. Headers are not modified.
diff --git a/docs/cmdline-opts/config.d b/docs/cmdline-opts/config.d
index 5a0ad1f..1805926 100644
--- a/docs/cmdline-opts/config.d
+++ b/docs/cmdline-opts/config.d
@@ -3,6 +3,7 @@
Help: Read config from a file
Short: K
Category: curl
+Example: --config file.txt $URL
---
Specify a text file to read curl arguments from. The command line arguments
diff --git a/docs/cmdline-opts/connect-timeout.d b/docs/cmdline-opts/connect-timeout.d
index fa32772..e66e35a 100644
--- a/docs/cmdline-opts/connect-timeout.d
+++ b/docs/cmdline-opts/connect-timeout.d
@@ -1,8 +1,10 @@
Long: connect-timeout
-Arg: <seconds>
+Arg: <fractional seconds>
Help: Maximum time allowed for connection
See-also: max-time
Category: connection
+Example: --connect-timeout 20 $URL
+Example: --connect-timeout 3.14 $URL
---
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
diff --git a/docs/cmdline-opts/connect-to.d b/docs/cmdline-opts/connect-to.d
index 2f015f8..ebea9b9 100644
--- a/docs/cmdline-opts/connect-to.d
+++ b/docs/cmdline-opts/connect-to.d
@@ -4,6 +4,7 @@
Added: 7.49.0
See-also: resolve header
Category: connection
+Example: --connect-to example.com:443:example.net:8443 $URL
---
For a request to the given HOST1:PORT1 pair, connect to HOST2:PORT2 instead.
diff --git a/docs/cmdline-opts/continue-at.d b/docs/cmdline-opts/continue-at.d
index c44d2f4..9e11bdb 100644
--- a/docs/cmdline-opts/continue-at.d
+++ b/docs/cmdline-opts/continue-at.d
@@ -4,6 +4,8 @@
Help: Resumed transfer offset
See-also: range
Category: connection
+Example: -C - $URL
+Example: -C 400 $URL
---
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
diff --git a/docs/cmdline-opts/cookie-jar.d b/docs/cmdline-opts/cookie-jar.d
index f11991f..f418af6 100644
--- a/docs/cmdline-opts/cookie-jar.d
+++ b/docs/cmdline-opts/cookie-jar.d
@@ -4,6 +4,8 @@
Protocols: HTTP
Help: Write cookies to <filename> after operation
Category: http
+Example: -c store-here.txt $URL
+Example: -c store-here.txt -b read-these $URL
---
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
diff --git a/docs/cmdline-opts/cookie.d b/docs/cmdline-opts/cookie.d
index 5c40cf2..b593935 100644
--- a/docs/cmdline-opts/cookie.d
+++ b/docs/cmdline-opts/cookie.d
@@ -4,6 +4,8 @@
Protocols: HTTP
Help: Send cookies from string/file
Category: http
+Example: -b cookiefile $URL
+Example: -b cookiefile -c cookiefile $URL
---
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
diff --git a/docs/cmdline-opts/create-dirs.d b/docs/cmdline-opts/create-dirs.d
index 801e95d..cae1d5a 100644
--- a/docs/cmdline-opts/create-dirs.d
+++ b/docs/cmdline-opts/create-dirs.d
@@ -1,6 +1,7 @@
Long: create-dirs
Help: Create necessary local directory hierarchy
Category: curl
+Example: --create-dirs --output local/dir/file $URL
---
When used in conjunction with the --output option, curl will create the
necessary local directory hierarchy as needed. This option creates the
diff --git a/docs/cmdline-opts/create-file-mode.d b/docs/cmdline-opts/create-file-mode.d
index 275fc6c..429b5ee 100644
--- a/docs/cmdline-opts/create-file-mode.d
+++ b/docs/cmdline-opts/create-file-mode.d
@@ -5,6 +5,7 @@
Category: sftp scp file upload
See-also: ftp-create-dirs
Added: 7.75.0
+Example: --create-file-mode 0777 -T localfile sftp://example.com/new
---
When curl is used to create files remotely using one of the supported
protocols, this option allows the user to set which 'mode' to set on the file
diff --git a/docs/cmdline-opts/crlf.d b/docs/cmdline-opts/crlf.d
index 50c4bef..856cd13 100644
--- a/docs/cmdline-opts/crlf.d
+++ b/docs/cmdline-opts/crlf.d
@@ -2,6 +2,7 @@
Help: Convert LF to CRLF in upload
Protocols: FTP SMTP
Category: ftp smtp
+Example: --crlf -T file ftp://example.com/
---
Convert LF to CRLF in upload. Useful for MVS (OS/390).
diff --git a/docs/cmdline-opts/crlfile.d b/docs/cmdline-opts/crlfile.d
index 360e668..21e86a8 100644
--- a/docs/cmdline-opts/crlfile.d
+++ b/docs/cmdline-opts/crlfile.d
@@ -1,9 +1,10 @@
Long: crlfile
Arg: <file>
Protocols: TLS
-Help: Get a CRL list in PEM format from the given file
+Help: Use this CRL list
Added: 7.19.7
Category: tls
+Example: --crlfile rejects.txt $URL
---
Provide a file using PEM format with a Certificate Revocation List that may
specify peer certificates that are to be considered revoked.
diff --git a/docs/cmdline-opts/curves.d b/docs/cmdline-opts/curves.d
index 47870a2..ac5ab10 100644
--- a/docs/cmdline-opts/curves.d
+++ b/docs/cmdline-opts/curves.d
@@ -4,6 +4,7 @@
Protocols: TLS
Added: 7.73.0
Category: tls
+Example: --curves X25519 $URL
---
Tells curl to request specific curves to use during SSL session establishment
according to RFC 8422, 5.1. Multiple algorithms can be provided by separating
diff --git a/docs/cmdline-opts/data-ascii.d b/docs/cmdline-opts/data-ascii.d
index 3522f63..943f301 100644
--- a/docs/cmdline-opts/data-ascii.d
+++ b/docs/cmdline-opts/data-ascii.d
@@ -3,5 +3,6 @@
Help: HTTP POST ASCII data
Protocols: HTTP
Category: http post upload
+Example: --data-ascii @file $URL
---
This is just an alias for --data.
diff --git a/docs/cmdline-opts/data-binary.d b/docs/cmdline-opts/data-binary.d
index c40785e..578cebc 100644
--- a/docs/cmdline-opts/data-binary.d
+++ b/docs/cmdline-opts/data-binary.d
@@ -3,6 +3,7 @@
Help: HTTP POST binary data
Protocols: HTTP
Category: http post upload
+Example: --data-binary @filename $URL
---
This posts data exactly as specified with no extra processing whatsoever.
diff --git a/docs/cmdline-opts/data-raw.d b/docs/cmdline-opts/data-raw.d
index 4db83ae..b8cd0f7 100644
--- a/docs/cmdline-opts/data-raw.d
+++ b/docs/cmdline-opts/data-raw.d
@@ -5,6 +5,8 @@
Added: 7.43.0
See-also: data
Category: http post upload
+Example: --data-raw "hello" $URL
+Example: --data-raw "@at@at@" $URL
---
This posts data similarly to --data but without the special
interpretation of the @ character.
diff --git a/docs/cmdline-opts/data-urlencode.d b/docs/cmdline-opts/data-urlencode.d
index 2205f9d..8b12957 100644
--- a/docs/cmdline-opts/data-urlencode.d
+++ b/docs/cmdline-opts/data-urlencode.d
@@ -5,6 +5,10 @@
See-also: data data-raw
Added: 7.18.0
Category: http post upload
+Example: --data-urlencode name=val $URL
+Example: --data-urlencode =encodethis $URL
+Example: --data-urlencode name@file $URL
+Example: --data-urlencode @fileonly $URL
---
This posts data, similar to the other --data options with the exception
that this performs URL-encoding.
diff --git a/docs/cmdline-opts/data.d b/docs/cmdline-opts/data.d
index 53ba86b..35fd675 100644
--- a/docs/cmdline-opts/data.d
+++ b/docs/cmdline-opts/data.d
@@ -6,6 +6,9 @@
See-also: data-binary data-urlencode data-raw
Mutexed: form head upload-file
Category: important http post upload
+Example: -d "name=curl" $URL
+Example: -d "name=curl" -d "tool=cmdline" $URL
+Example: -d @filename $URL
---
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
diff --git a/docs/cmdline-opts/delegation.d b/docs/cmdline-opts/delegation.d
index 41fa940..1514d66 100644
--- a/docs/cmdline-opts/delegation.d
+++ b/docs/cmdline-opts/delegation.d
@@ -3,6 +3,7 @@
Help: GSS-API delegation permission
Protocols: GSS/kerberos
Category: auth
+Example: --delegation "none" $URL
---
Set LEVEL to tell the server what it is allowed to delegate when it
comes to user credentials.
diff --git a/docs/cmdline-opts/digest.d b/docs/cmdline-opts/digest.d
index da8c01e..1934137 100644
--- a/docs/cmdline-opts/digest.d
+++ b/docs/cmdline-opts/digest.d
@@ -4,6 +4,7 @@
Mutexed: basic ntlm negotiate
See-also: user proxy-digest anyauth
Category: proxy auth http
+Example: -u name:password --digest $URL
---
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
diff --git a/docs/cmdline-opts/disable-eprt.d b/docs/cmdline-opts/disable-eprt.d
index ffcf684..38b3e0b 100644
--- a/docs/cmdline-opts/disable-eprt.d
+++ b/docs/cmdline-opts/disable-eprt.d
@@ -2,6 +2,7 @@
Help: Inhibit using EPRT or LPRT
Protocols: FTP
Category: ftp
+Example: --disable-eprt ftp://example.com/
---
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
diff --git a/docs/cmdline-opts/disable-epsv.d b/docs/cmdline-opts/disable-epsv.d
index dadef09..281ec5c 100644
--- a/docs/cmdline-opts/disable-epsv.d
+++ b/docs/cmdline-opts/disable-epsv.d
@@ -2,6 +2,7 @@
Help: Inhibit using EPSV
Protocols: FTP
Category: ftp
+Example: --disable-epsv ftp://example.com/
---
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
diff --git a/docs/cmdline-opts/disable.d b/docs/cmdline-opts/disable.d
index d909608..3eb87f8 100644
--- a/docs/cmdline-opts/disable.d
+++ b/docs/cmdline-opts/disable.d
@@ -2,6 +2,7 @@
Short: q
Help: Disable .curlrc
Category: curl
+Example: -q $URL
---
If used as the first parameter on the command line, the *curlrc* config
file will not be read and used. See the --config for details on the default
diff --git a/docs/cmdline-opts/disallow-username-in-url.d b/docs/cmdline-opts/disallow-username-in-url.d
index e124f67..f3122ae 100644
--- a/docs/cmdline-opts/disallow-username-in-url.d
+++ b/docs/cmdline-opts/disallow-username-in-url.d
@@ -4,5 +4,7 @@
Added: 7.61.0
See-also: proto
Category: curl http
+Example: --disallow-username-in-url $URL
---
-This tells curl to exit if passed a url containing a username.
+This tells curl to exit if passed a url containing a username. This is probably
+most useful when the URL is being provided at run-time or similar.
diff --git a/docs/cmdline-opts/dns-interface.d b/docs/cmdline-opts/dns-interface.d
index 3cb818a..fec7927 100644
--- a/docs/cmdline-opts/dns-interface.d
+++ b/docs/cmdline-opts/dns-interface.d
@@ -6,6 +6,7 @@
Added: 7.33.0
Requires: c-ares
Category: dns
+Example: --dns-interface eth0 $URL
---
Tell curl to send outgoing DNS requests through <interface>. This option is a
counterpart to --interface (which does not affect DNS). The supplied string
diff --git a/docs/cmdline-opts/dns-ipv4-addr.d b/docs/cmdline-opts/dns-ipv4-addr.d
index 0d7bae6..e09153a 100644
--- a/docs/cmdline-opts/dns-ipv4-addr.d
+++ b/docs/cmdline-opts/dns-ipv4-addr.d
@@ -6,6 +6,7 @@
Added: 7.33.0
Requires: c-ares
Category: dns
+Example: --dns-ipv4-addr 10.1.2.3 $URL
---
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
diff --git a/docs/cmdline-opts/dns-ipv6-addr.d b/docs/cmdline-opts/dns-ipv6-addr.d
index a964dbb..954cb98 100644
--- a/docs/cmdline-opts/dns-ipv6-addr.d
+++ b/docs/cmdline-opts/dns-ipv6-addr.d
@@ -6,6 +6,7 @@
Added: 7.33.0
Requires: c-ares
Category: dns
+Example: --dns-ipv6-addr 2a04:4e42::561 $URL
---
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
diff --git a/docs/cmdline-opts/dns-servers.d b/docs/cmdline-opts/dns-servers.d
index a0954b3..0894735 100644
--- a/docs/cmdline-opts/dns-servers.d
+++ b/docs/cmdline-opts/dns-servers.d
@@ -4,6 +4,7 @@
Requires: c-ares
Added: 7.33.0
Category: dns
+Example: --dns-servers 192.168.0.1,192.168.0.2 $URL
---
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
diff --git a/docs/cmdline-opts/doh-cert-status.d b/docs/cmdline-opts/doh-cert-status.d
index 1442fc8..a760a6f 100644
--- a/docs/cmdline-opts/doh-cert-status.d
+++ b/docs/cmdline-opts/doh-cert-status.d
@@ -3,5 +3,6 @@
Protocols: all
Added: 7.76.0
Category: dns tls
+Example: --doh-cert-status --doh-url https://doh.example $URL
---
Same as --cert-status but used for DoH (DNS-over-HTTPS).
diff --git a/docs/cmdline-opts/doh-insecure.d b/docs/cmdline-opts/doh-insecure.d
index fe399a2..907a5dc 100644
--- a/docs/cmdline-opts/doh-insecure.d
+++ b/docs/cmdline-opts/doh-insecure.d
@@ -3,5 +3,6 @@
Protocols: all
Added: 7.76.0
Category: dns tls
+Example: --doh-insecure --doh-url https://doh.example $URL
---
Same as --insecure but used for DoH (DNS-over-HTTPS).
diff --git a/docs/cmdline-opts/doh-url.d b/docs/cmdline-opts/doh-url.d
index 612945a..80ff96c 100644
--- a/docs/cmdline-opts/doh-url.d
+++ b/docs/cmdline-opts/doh-url.d
@@ -4,6 +4,7 @@
Protocols: all
Added: 7.62.0
Category: dns
+Example: --doh-url https://doh.example $URL
---
Specifies which DNS-over-HTTPS (DoH) server to use to resolve hostnames,
instead of using the default name resolver mechanism. The URL must be HTTPS.
diff --git a/docs/cmdline-opts/dump-header.d b/docs/cmdline-opts/dump-header.d
index aa3bd9e..62c92f4 100644
--- a/docs/cmdline-opts/dump-header.d
+++ b/docs/cmdline-opts/dump-header.d
@@ -5,6 +5,7 @@
Protocols: HTTP FTP
See-also: output
Category: http ftp
+Example: --dump-header store.txt $URL
---
Write the received protocol headers to the specified file. If no headers are
received, the use of this option will create an empty file.
diff --git a/docs/cmdline-opts/egd-file.d b/docs/cmdline-opts/egd-file.d
index 05ede9a..2e99df4 100644
--- a/docs/cmdline-opts/egd-file.d
+++ b/docs/cmdline-opts/egd-file.d
@@ -4,6 +4,7 @@
Protocols: TLS
See-also: random-file
Category: tls
+Example: --egd-file /random/here $URL
---
Specify the path name to the Entropy Gathering Daemon socket. The socket is
used to seed the random engine for SSL connections.
diff --git a/docs/cmdline-opts/engine.d b/docs/cmdline-opts/engine.d
index 034796c..8a2dcf7 100644
--- a/docs/cmdline-opts/engine.d
+++ b/docs/cmdline-opts/engine.d
@@ -3,6 +3,7 @@
Help: Crypto engine to use
Protocols: TLS
Category: tls
+Example: --engine flavor $URL
---
Select the OpenSSL crypto engine to use for cipher operations. Use --engine
list to print a list of build-time supported engines. Note that not all (and
diff --git a/docs/cmdline-opts/etag-compare.d b/docs/cmdline-opts/etag-compare.d
index c984cc9..fa16762 100644
--- a/docs/cmdline-opts/etag-compare.d
+++ b/docs/cmdline-opts/etag-compare.d
@@ -4,6 +4,7 @@
Protocols: HTTP
Added: 7.68.0
Category: http
+Example: --etag-compare etag.txt $URL
---
This option makes a conditional HTTP request for the specific ETag read
from the given file by sending a custom If-None-Match header using the
diff --git a/docs/cmdline-opts/etag-save.d b/docs/cmdline-opts/etag-save.d
index dc2484c..8efad90 100644
--- a/docs/cmdline-opts/etag-save.d
+++ b/docs/cmdline-opts/etag-save.d
@@ -4,6 +4,7 @@
Protocols: HTTP
Added: 7.68.0
Category: http
+Example: --etag-save storetag.txt $URL
---
This option saves an HTTP ETag to the specified file. An ETag is a
caching related header, usually returned in a response.
diff --git a/docs/cmdline-opts/expect100-timeout.d b/docs/cmdline-opts/expect100-timeout.d
index 431a529..8855edd 100644
--- a/docs/cmdline-opts/expect100-timeout.d
+++ b/docs/cmdline-opts/expect100-timeout.d
@@ -5,6 +5,7 @@
Added: 7.47.0
See-also: connect-timeout
Category: http
+Example: --expect100-timeout 2.5 -T file $URL
---
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
diff --git a/docs/cmdline-opts/fail-early.d b/docs/cmdline-opts/fail-early.d
index 3fbe238..aad15c3 100644
--- a/docs/cmdline-opts/fail-early.d
+++ b/docs/cmdline-opts/fail-early.d
@@ -2,6 +2,7 @@
Help: Fail on first transfer error, do not continue
Added: 7.52.0
Category: curl
+Example: --fail-early $URL https://two.example
---
Fail and exit on the first detected transfer error.
diff --git a/docs/cmdline-opts/fail-with-body.d b/docs/cmdline-opts/fail-with-body.d
index e27d459..9b8c7db 100644
--- a/docs/cmdline-opts/fail-with-body.d
+++ b/docs/cmdline-opts/fail-with-body.d
@@ -4,6 +4,7 @@
Category: http output
Added: 7.76.0
See-also: fail
+Example: --fail-with-body $URL
---
Return an error on server errors where the HTTP response code is 400 or
greater). In normal cases when an HTTP server fails to deliver a document, it
diff --git a/docs/cmdline-opts/fail.d b/docs/cmdline-opts/fail.d
index d4d65fb..a5e0c91 100644
--- a/docs/cmdline-opts/fail.d
+++ b/docs/cmdline-opts/fail.d
@@ -4,6 +4,7 @@
Help: Fail silently (no output at all) on HTTP errors
See-also: fail-with-body
Category: important http
+Example: --fail $URL
---
Fail silently (no output at all) on server errors. This is mostly done to
enable scripts etc to better deal with failed attempts. In normal cases
diff --git a/docs/cmdline-opts/false-start.d b/docs/cmdline-opts/false-start.d
index abeff0e..de36962 100644
--- a/docs/cmdline-opts/false-start.d
+++ b/docs/cmdline-opts/false-start.d
@@ -3,6 +3,7 @@
Protocols: TLS
Added: 7.42.0
Category: tls
+Example: --false-start $URL
---
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
diff --git a/docs/cmdline-opts/form-string.d b/docs/cmdline-opts/form-string.d
index 04d2578..4f1a766 100644
--- a/docs/cmdline-opts/form-string.d
+++ b/docs/cmdline-opts/form-string.d
@@ -4,6 +4,7 @@
Arg: <name=string>
See-also: form
Category: http upload
+Example: --form-string "data" $URL
---
Similar to --form except that the value string for the named parameter is used
literally. Leading \&'@' and \&'<' characters, and the \&';type=' string in
diff --git a/docs/cmdline-opts/form.d b/docs/cmdline-opts/form.d
index eec9aac..06f2c55 100644
--- a/docs/cmdline-opts/form.d
+++ b/docs/cmdline-opts/form.d
@@ -5,6 +5,7 @@
Protocols: HTTP SMTP IMAP
Mutexed: data head upload-file
Category: http upload
+Example: --form "name=curl" --form "file=@loadthis" $URL
---
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
diff --git a/docs/cmdline-opts/ftp-account.d b/docs/cmdline-opts/ftp-account.d
index bc04ba0..ce816f1 100644
--- a/docs/cmdline-opts/ftp-account.d
+++ b/docs/cmdline-opts/ftp-account.d
@@ -4,6 +4,7 @@
Protocols: FTP
Added: 7.13.0
Category: ftp auth
+Example: --ftp-account "mr.robot" ftp://example.com/
---
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.
diff --git a/docs/cmdline-opts/ftp-alternative-to-user.d b/docs/cmdline-opts/ftp-alternative-to-user.d
index 1714849..a5fb985 100644
--- a/docs/cmdline-opts/ftp-alternative-to-user.d
+++ b/docs/cmdline-opts/ftp-alternative-to-user.d
@@ -4,6 +4,7 @@
Protocols: FTP
Added: 7.15.5
Category: ftp
+Example: --ftp-alternative-to-user "U53r" ftp://example.com
---
If authenticating with the USER and PASS commands fails, send this command.
When connecting to Tumbleweed's Secure Transport server over FTPS using a
diff --git a/docs/cmdline-opts/ftp-create-dirs.d b/docs/cmdline-opts/ftp-create-dirs.d
index 5d9dfda..579f8e3 100644
--- a/docs/cmdline-opts/ftp-create-dirs.d
+++ b/docs/cmdline-opts/ftp-create-dirs.d
@@ -3,6 +3,7 @@
Help: Create the remote dirs if not present
See-also: create-dirs
Category: ftp sftp curl
+Example: --ftp-create-dirs -T file ftp://example.com/remote/path/file
---
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
diff --git a/docs/cmdline-opts/ftp-method.d b/docs/cmdline-opts/ftp-method.d
index 149340b..4af0baf 100644
--- a/docs/cmdline-opts/ftp-method.d
+++ b/docs/cmdline-opts/ftp-method.d
@@ -4,6 +4,9 @@
Protocols: FTP
Added: 7.15.1
Category: ftp
+Example: --ftp-method multicwd ftp://example.com/dir1/dir2/file
+Example: --ftp-method nocwd ftp://example.com/dir1/dir2/file
+Example: --ftp-method singlecwd ftp://example.com/dir1/dir2/file
---
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:
diff --git a/docs/cmdline-opts/ftp-pasv.d b/docs/cmdline-opts/ftp-pasv.d
index cbd548d..d920fef 100644
--- a/docs/cmdline-opts/ftp-pasv.d
+++ b/docs/cmdline-opts/ftp-pasv.d
@@ -4,6 +4,7 @@
Added: 7.11.0
See-also: disable-epsv
Category: ftp
+Example: --ftp-pasv ftp://example.com/
---
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
diff --git a/docs/cmdline-opts/ftp-port.d b/docs/cmdline-opts/ftp-port.d
index 9bb1d43..52e55e5 100644
--- a/docs/cmdline-opts/ftp-port.d
+++ b/docs/cmdline-opts/ftp-port.d
@@ -5,6 +5,9 @@
Protocols: FTP
See-also: ftp-pasv disable-eprt
Category: ftp
+Example: -P - ftp:/example.com
+Example: -P eth0 ftp:/example.com
+Example: -P 192.168.0.2 ftp:/example.com
---
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
diff --git a/docs/cmdline-opts/ftp-pret.d b/docs/cmdline-opts/ftp-pret.d
index e9c7d25..453d8cf 100644
--- a/docs/cmdline-opts/ftp-pret.d
+++ b/docs/cmdline-opts/ftp-pret.d
@@ -3,6 +3,7 @@
Protocols: FTP
Added: 7.20.0
Category: ftp
+Example: --ftp-pret ftp://example.com/
---
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
diff --git a/docs/cmdline-opts/ftp-skip-pasv-ip.d b/docs/cmdline-opts/ftp-skip-pasv-ip.d
index bcf4e7e..36f9e6d 100644
--- a/docs/cmdline-opts/ftp-skip-pasv-ip.d
+++ b/docs/cmdline-opts/ftp-skip-pasv-ip.d
@@ -4,6 +4,7 @@
Added: 7.14.2
See-also: ftp-pasv
Category: ftp
+Example: --ftp-skip-pasv-ip ftp://example.com/
---
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
diff --git a/docs/cmdline-opts/ftp-ssl-ccc-mode.d b/docs/cmdline-opts/ftp-ssl-ccc-mode.d
index 6289e54..15ad1f5 100644
--- a/docs/cmdline-opts/ftp-ssl-ccc-mode.d
+++ b/docs/cmdline-opts/ftp-ssl-ccc-mode.d
@@ -5,6 +5,7 @@
Added: 7.16.2
See-also: ftp-ssl-ccc
Category: ftp tls
+Example: --ftp-ssl-ccc-mode active --ftp-ssl-ccc ftps://example.com/
---
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
diff --git a/docs/cmdline-opts/ftp-ssl-ccc.d b/docs/cmdline-opts/ftp-ssl-ccc.d
index 33cab43..bfaf431 100644
--- a/docs/cmdline-opts/ftp-ssl-ccc.d
+++ b/docs/cmdline-opts/ftp-ssl-ccc.d
@@ -4,6 +4,7 @@
See-also: ssl ftp-ssl-ccc-mode
Added: 7.16.1
Category: ftp tls
+Example: --ftp-ssl-ccc ftps://example.com/
---
Use CCC (Clear Command Channel) Shuts down the SSL/TLS layer after
authenticating. The rest of the control channel communication will be
diff --git a/docs/cmdline-opts/ftp-ssl-control.d b/docs/cmdline-opts/ftp-ssl-control.d
index 5191353..72dc080 100644
--- a/docs/cmdline-opts/ftp-ssl-control.d
+++ b/docs/cmdline-opts/ftp-ssl-control.d
@@ -3,6 +3,7 @@
Protocols: FTP
Added: 7.16.0
Category: ftp tls
+Example: --ftp-ssl-control ftp://example.com
---
Require SSL/TLS for the FTP login, clear for transfer. Allows secure
authentication, but non-encrypted data transfers for efficiency. Fails the
diff --git a/docs/cmdline-opts/gen.pl b/docs/cmdline-opts/gen.pl
index e651f02..c058987 100755
--- a/docs/cmdline-opts/gen.pl
+++ b/docs/cmdline-opts/gen.pl
@@ -138,8 +138,11 @@
my $requires;
my $category;
my $seealso;
+ my @examples; # there can be more than one
my $magic; # cmdline special option
+ my $line;
while(<F>) {
+ $line++;
if(/^Short: *(.)/i) {
$short=$1;
}
@@ -173,6 +176,9 @@
elsif(/^Category: *(.*)/i) {
$category=$1;
}
+ elsif(/^Example: *(.*)/i) {
+ push @examples, $1;
+ }
elsif(/^Help: *(.*)/i) {
;
}
@@ -185,6 +191,10 @@
print STDERR "ERROR: no 'Category:' in $f\n";
exit 2;
}
+ if(!$examples[0]) {
+ print STDERR "$f:$line:1:ERROR: no 'Example:' present\n";
+ exit 2;
+ }
last;
}
else {
@@ -276,6 +286,16 @@
}
push @foot, overrides($standalone, "This option overrides $mstr. ");
}
+ if($examples[0]) {
+ my $s ="";
+ $s="s" if($examples[1]);
+ print "\nExample$s:\n.nf\n";
+ foreach my $e (@examples) {
+ $e =~ s!\$URL!https://example.com!g;
+ print " curl $e\n";
+ }
+ print ".fi\n";
+ }
if($added) {
push @foot, added($standalone, $added);
}
diff --git a/docs/cmdline-opts/get.d b/docs/cmdline-opts/get.d
index d529bb4..e51c155 100644
--- a/docs/cmdline-opts/get.d
+++ b/docs/cmdline-opts/get.d
@@ -2,6 +2,7 @@
Short: G
Help: Put the post data in the URL and use GET
Category: http upload
+Example: --get $URL
---
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
diff --git a/docs/cmdline-opts/globoff.d b/docs/cmdline-opts/globoff.d
index 1db0fa2..ec2c7ae 100644
--- a/docs/cmdline-opts/globoff.d
+++ b/docs/cmdline-opts/globoff.d
@@ -2,6 +2,7 @@
Short: g
Help: Disable URL sequences and ranges using {} and []
Category: curl
+Example: -g "https://example.com/{[]}}}}"
---
This option switches off the "URL globbing parser". When you set this option,
you can specify URLs that contain the letters {}[] without having curl itself
diff --git a/docs/cmdline-opts/happy-eyeballs-timeout-ms.d b/docs/cmdline-opts/happy-eyeballs-timeout-ms.d
index 1488a5a..c3b2a51 100644
--- a/docs/cmdline-opts/happy-eyeballs-timeout-ms.d
+++ b/docs/cmdline-opts/happy-eyeballs-timeout-ms.d
@@ -3,6 +3,7 @@
Help: Time for IPv6 before trying IPv4
Added: 7.59.0
Category: connection
+Example: --happy-eyeballs-timeout-ms 500 $URL
---
Happy Eyeballs is an algorithm that attempts to connect to both IPv4 and IPv6
addresses for dual-stack hosts, giving IPv6 a head-start of the specified
diff --git a/docs/cmdline-opts/haproxy-protocol.d b/docs/cmdline-opts/haproxy-protocol.d
index 8358204..446dc65 100644
--- a/docs/cmdline-opts/haproxy-protocol.d
+++ b/docs/cmdline-opts/haproxy-protocol.d
@@ -3,10 +3,11 @@
Protocols: HTTP
Added: 7.60.0
Category: http proxy
+Example: --haproxy-protocol $URL
---
-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.
+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.
This option is primarily useful when sending test requests to a service that
expects this header.
diff --git a/docs/cmdline-opts/head.d b/docs/cmdline-opts/head.d
index 6fe4685..06d2489 100644
--- a/docs/cmdline-opts/head.d
+++ b/docs/cmdline-opts/head.d
@@ -3,6 +3,7 @@
Help: Show document info only
Protocols: HTTP FTP FILE
Category: http ftp file
+Example: -I $URL
---
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,
diff --git a/docs/cmdline-opts/header.d b/docs/cmdline-opts/header.d
index 121285a..11c96d5 100644
--- a/docs/cmdline-opts/header.d
+++ b/docs/cmdline-opts/header.d
@@ -5,6 +5,9 @@
Protocols: HTTP
Category: http
See-also: user-agent referer
+Example: -H "X-First-Name: Joe" $URL
+Example: -H "User-Agent: yes-please/2000" $URL
+Example: -H "Host:" $URL
---
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
@@ -32,10 +35,6 @@
Passing on a "Transfer-Encoding: chunked" header when doing a HTTP request
with a request body, will make curl send the data using chunked encoding.
-Example:
-
- curl -H "X-First-Name: Joe" http://example.com/
-
**WARNING**: headers set with this option will be set in all requests - even
after redirects are followed, like when told with --location. This can lead to
the header being sent to other hosts than the original host, so sensitive
diff --git a/docs/cmdline-opts/help.d b/docs/cmdline-opts/help.d
index b7c6823..28ae868 100644
--- a/docs/cmdline-opts/help.d
+++ b/docs/cmdline-opts/help.d
@@ -3,6 +3,7 @@
Short: h
Help: Get help for commands
Category: important curl
+Example: --help all
---
Usage help. This lists all commands of the <category>.
If no arg was provided, curl will display the most important
diff --git a/docs/cmdline-opts/hostpubmd5.d b/docs/cmdline-opts/hostpubmd5.d
index c926ed8..833db95 100644
--- a/docs/cmdline-opts/hostpubmd5.d
+++ b/docs/cmdline-opts/hostpubmd5.d
@@ -4,6 +4,7 @@
Protocols: SFTP SCP
Added: 7.17.1
Category: sftp scp
+Example: --hostpubmd5 e5c1c49020640a5ab0f2034854c321a8 sftp://example.com/
---
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
diff --git a/docs/cmdline-opts/hsts.d b/docs/cmdline-opts/hsts.d
index 2399084..f9cd453 100644
--- a/docs/cmdline-opts/hsts.d
+++ b/docs/cmdline-opts/hsts.d
@@ -4,9 +4,8 @@
Help: Enable HSTS with this cache file
Added: 7.74.0
Category: http
+Example: --hsts cache.txt $URL
---
-WARNING: this option is experimental. Do not use in production.
-
This option enables HSTS for the transfer. If the file name points to an
existing HSTS cache file, that will be used. After a completed transfer, the
cache will be saved to the file name again if it has been modified.
diff --git a/docs/cmdline-opts/http0.9.d b/docs/cmdline-opts/http0.9.d
index 954c22a..7c45d56 100644
--- a/docs/cmdline-opts/http0.9.d
+++ b/docs/cmdline-opts/http0.9.d
@@ -4,6 +4,7 @@
Added:
Help: Allow HTTP 0.9 responses
Category: http
+Example: --http0.9 $URL
---
Tells curl to be fine with HTTP version 0.9 response.
diff --git a/docs/cmdline-opts/http1.0.d b/docs/cmdline-opts/http1.0.d
index a4059db..cbfbaee 100644
--- a/docs/cmdline-opts/http1.0.d
+++ b/docs/cmdline-opts/http1.0.d
@@ -6,6 +6,7 @@
Mutexed: http1.1 http2
Help: Use HTTP 1.0
Category: http
+Example: --http1.0 $URL
---
Tells curl to use HTTP version 1.0 instead of using its internally preferred
HTTP version.
diff --git a/docs/cmdline-opts/http1.1.d b/docs/cmdline-opts/http1.1.d
index a71a40b..01fa76d 100644
--- a/docs/cmdline-opts/http1.1.d
+++ b/docs/cmdline-opts/http1.1.d
@@ -5,5 +5,6 @@
Mutexed: http1.0 http2
Help: Use HTTP 1.1
Category: http
+Example: --http1.1 $URL
---
Tells curl to use HTTP version 1.1.
diff --git a/docs/cmdline-opts/http2-prior-knowledge.d b/docs/cmdline-opts/http2-prior-knowledge.d
index ea2906e..e3b32f6 100644
--- a/docs/cmdline-opts/http2-prior-knowledge.d
+++ b/docs/cmdline-opts/http2-prior-knowledge.d
@@ -6,6 +6,7 @@
Requires: HTTP/2
Help: Use HTTP 2 without HTTP/1.1 Upgrade
Category: http
+Example: --http2-prior-knowledge $URL
---
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
diff --git a/docs/cmdline-opts/http2.d b/docs/cmdline-opts/http2.d
index 197515e..2a85db6 100644
--- a/docs/cmdline-opts/http2.d
+++ b/docs/cmdline-opts/http2.d
@@ -8,5 +8,12 @@
Help: Use HTTP 2
See-also: http1.1 http3
Category: http
+Example: --http2 $URL
---
Tells curl to use HTTP version 2.
+
+For HTTPS, this means curl will attempt to negotiate HTTP/2 in the TLS
+handshake. curl does this by default.
+
+For HTTP, this means curl will attempt to upgrade the request to HTTP/2 using
+the Upgrade: request header.
diff --git a/docs/cmdline-opts/http3.d b/docs/cmdline-opts/http3.d
index 5063079..f6c92b3 100644
--- a/docs/cmdline-opts/http3.d
+++ b/docs/cmdline-opts/http3.d
@@ -7,8 +7,9 @@
Help: Use HTTP v3
See-also: http1.1 http2
Category: http
+Example: --http3 $URL
---
-WARNING: this option is experimental. Do not use in production.
+**WARNING**: this option is experimental. Do not use in production.
Tells curl to use HTTP version 3 directly to the host and port number used in
the URL. A normal HTTP/3 transaction will be done to a host and then get
diff --git a/docs/cmdline-opts/ignore-content-length.d b/docs/cmdline-opts/ignore-content-length.d
index 2555cca..8a4c247 100644
--- a/docs/cmdline-opts/ignore-content-length.d
+++ b/docs/cmdline-opts/ignore-content-length.d
@@ -2,6 +2,7 @@
Help: Ignore the size of the remote resource
Protocols: FTP HTTP
Category: http ftp
+Example: --ignore-content-length $URL
---
For HTTP, Ignore the Content-Length header. This is particularly useful for
servers running Apache 1.x, which will report incorrect Content-Length for
diff --git a/docs/cmdline-opts/include.d b/docs/cmdline-opts/include.d
index 250d4ac..80a05e0 100644
--- a/docs/cmdline-opts/include.d
+++ b/docs/cmdline-opts/include.d
@@ -3,6 +3,7 @@
Help: Include protocol response headers in the output
See-also: verbose
Category: important verbose
+Example: -i $URL
---
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
diff --git a/docs/cmdline-opts/insecure.d b/docs/cmdline-opts/insecure.d
index 443ddd5..fb2c17d 100644
--- a/docs/cmdline-opts/insecure.d
+++ b/docs/cmdline-opts/insecure.d
@@ -4,6 +4,7 @@
Protocols: TLS
See-also: proxy-insecure cacert
Category: tls
+Example: --insecure $URL
---
By default, every SSL connection curl makes is verified to be secure. This
option allows curl to proceed and operate even for server connections
@@ -14,3 +15,5 @@
See this online resource for further details:
https://curl.se/docs/sslcerts.html
+
+**WARNING**: this makes the transfer insecure.
diff --git a/docs/cmdline-opts/interface.d b/docs/cmdline-opts/interface.d
index 196e7ef..b2c8eee 100644
--- a/docs/cmdline-opts/interface.d
+++ b/docs/cmdline-opts/interface.d
@@ -3,6 +3,7 @@
Help: Use network INTERFACE (or address)
See-also: dns-interface
Category: connection
+Example: --interface eth0 $URL
---
Perform an operation using a specified interface. You can enter interface
diff --git a/docs/cmdline-opts/ipv4.d b/docs/cmdline-opts/ipv4.d
index a669137..90a6dda 100644
--- a/docs/cmdline-opts/ipv4.d
+++ b/docs/cmdline-opts/ipv4.d
@@ -8,6 +8,7 @@
See-also: http1.1 http2
Help: Resolve names to IPv4 addresses
Category: connection dns
+Example: --ipv4 $URL
---
This option tells curl to resolve names to IPv4 addresses only, and not for
example try IPv6.
diff --git a/docs/cmdline-opts/ipv6.d b/docs/cmdline-opts/ipv6.d
index ce0415c..dfa79ab 100644
--- a/docs/cmdline-opts/ipv6.d
+++ b/docs/cmdline-opts/ipv6.d
@@ -8,6 +8,7 @@
See-also: http1.1 http2
Help: Resolve names to IPv6 addresses
Category: connection dns
+Example: --ipv6 $URL
---
This option tells curl to resolve names to IPv6 addresses only, and not for
example try IPv4.
diff --git a/docs/cmdline-opts/junk-session-cookies.d b/docs/cmdline-opts/junk-session-cookies.d
index 993b77f..0cc342c 100644
--- a/docs/cmdline-opts/junk-session-cookies.d
+++ b/docs/cmdline-opts/junk-session-cookies.d
@@ -4,6 +4,7 @@
Protocols: HTTP
See-also: cookie cookie-jar
Category: http
+Example: --junk-session-cookies -b cookies.txt $URL
---
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
diff --git a/docs/cmdline-opts/keepalive-time.d b/docs/cmdline-opts/keepalive-time.d
index 4126153..1b96c4d 100644
--- a/docs/cmdline-opts/keepalive-time.d
+++ b/docs/cmdline-opts/keepalive-time.d
@@ -3,6 +3,7 @@
Help: Interval time for keepalive probes
Added: 7.18.0
Category: connection
+Example: --keepalive-time 20 $URL
---
This option sets the time a connection needs to remain idle before sending
keepalive probes and the time between individual keepalive probes. It is
diff --git a/docs/cmdline-opts/key-type.d b/docs/cmdline-opts/key-type.d
index 50a0686..4baa9af 100644
--- a/docs/cmdline-opts/key-type.d
+++ b/docs/cmdline-opts/key-type.d
@@ -3,6 +3,7 @@
Help: Private key file type (DER/PEM/ENG)
Protocols: TLS
Category: tls
+Example: --key-type DER --key here $URL
---
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.
diff --git a/docs/cmdline-opts/key.d b/docs/cmdline-opts/key.d
index a762e6f..d7f5e22 100644
--- a/docs/cmdline-opts/key.d
+++ b/docs/cmdline-opts/key.d
@@ -3,6 +3,7 @@
Protocols: TLS SSH
Help: Private key file name
Category: tls ssh
+Example: --cert certificate --key here $URL
---
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:
diff --git a/docs/cmdline-opts/krb.d b/docs/cmdline-opts/krb.d
index 7759cfb..3d9ce99 100644
--- a/docs/cmdline-opts/krb.d
+++ b/docs/cmdline-opts/krb.d
@@ -4,6 +4,7 @@
Protocols: FTP
Requires: Kerberos
Category: ftp
+Example: --krb clear ftp://example.com/
---
Enable Kerberos authentication and use. The level must be entered and should
be one of 'clear', 'safe', 'confidential', or 'private'. Should you use a
diff --git a/docs/cmdline-opts/libcurl.d b/docs/cmdline-opts/libcurl.d
index 4016082..b7371ff 100644
--- a/docs/cmdline-opts/libcurl.d
+++ b/docs/cmdline-opts/libcurl.d
@@ -3,6 +3,7 @@
Help: Dump libcurl equivalent code of this command line
Added: 7.16.1
Category: curl
+Example: --libcurl client.c $URL
---
Append this option to any ordinary curl command line, and you will get
libcurl-using C source code written to the file that does the equivalent
diff --git a/docs/cmdline-opts/limit-rate.d b/docs/cmdline-opts/limit-rate.d
index 66f5cda..7c46e54 100644
--- a/docs/cmdline-opts/limit-rate.d
+++ b/docs/cmdline-opts/limit-rate.d
@@ -2,6 +2,9 @@
Arg: <speed>
Help: Limit transfer speed to RATE
Category: connection
+Example: --limit-rate 100K $URL
+Example: --limit-rate 1000 $URL
+Example: --limit-rate 10M $URL
---
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
diff --git a/docs/cmdline-opts/list-only.d b/docs/cmdline-opts/list-only.d
index ac39906..29f9ba2 100644
--- a/docs/cmdline-opts/list-only.d
+++ b/docs/cmdline-opts/list-only.d
@@ -4,6 +4,7 @@
Help: List only mode
Added: 4.0
Category: ftp pop3
+Example: --list-only ftp://example.com/dir/
---
(FTP)
When listing an FTP directory, this switch forces a name-only view. This is
diff --git a/docs/cmdline-opts/local-port.d b/docs/cmdline-opts/local-port.d
index 3f7a0e0..7766417 100644
--- a/docs/cmdline-opts/local-port.d
+++ b/docs/cmdline-opts/local-port.d
@@ -3,6 +3,7 @@
Help: Force use of RANGE for local port numbers
Added: 7.15.2
Category: connection
+Example: --local-port 1000-3000 $URL
---
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
diff --git a/docs/cmdline-opts/location-trusted.d b/docs/cmdline-opts/location-trusted.d
index f01d842..98c49ff 100644
--- a/docs/cmdline-opts/location-trusted.d
+++ b/docs/cmdline-opts/location-trusted.d
@@ -3,6 +3,7 @@
Protocols: HTTP
See-also: user
Category: http auth
+Example: --location-trusted -u user:password $URL
---
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
diff --git a/docs/cmdline-opts/location.d b/docs/cmdline-opts/location.d
index 6bf763d..08c939c 100644
--- a/docs/cmdline-opts/location.d
+++ b/docs/cmdline-opts/location.d
@@ -3,6 +3,7 @@
Help: Follow redirects
Protocols: HTTP
Category: http
+Example: -L $URL
---
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
diff --git a/docs/cmdline-opts/login-options.d b/docs/cmdline-opts/login-options.d
index b122468..de77288 100644
--- a/docs/cmdline-opts/login-options.d
+++ b/docs/cmdline-opts/login-options.d
@@ -4,6 +4,7 @@
Help: Server login options
Added: 7.34.0
Category: imap pop3 smtp auth
+Example: --login-options 'AUTH=*' imap://example.com
---
Specify the login options to use during server authentication.
diff --git a/docs/cmdline-opts/mail-auth.d b/docs/cmdline-opts/mail-auth.d
index 5299971..49a02d5 100644
--- a/docs/cmdline-opts/mail-auth.d
+++ b/docs/cmdline-opts/mail-auth.d
@@ -5,6 +5,7 @@
Added: 7.25.0
See-also: mail-rcpt mail-from
Category: smtp
+Example: --mail-auth [email protected] -T mail smtp://example.com/
---
Specify a single address. This will be used to specify the authentication
address (identity) of a submitted message that is being relayed to another
diff --git a/docs/cmdline-opts/mail-from.d b/docs/cmdline-opts/mail-from.d
index faf48e2..be0547c 100644
--- a/docs/cmdline-opts/mail-from.d
+++ b/docs/cmdline-opts/mail-from.d
@@ -5,5 +5,6 @@
Added: 7.20.0
See-also: mail-rcpt mail-auth
Category: smtp
+Example: --mail-from [email protected] -T mail smtp://example.com/
---
Specify a single address that the given mail should get sent from.
diff --git a/docs/cmdline-opts/mail-rcpt-allowfails.d b/docs/cmdline-opts/mail-rcpt-allowfails.d
index e96be3e..36d555e 100644
--- a/docs/cmdline-opts/mail-rcpt-allowfails.d
+++ b/docs/cmdline-opts/mail-rcpt-allowfails.d
@@ -3,6 +3,7 @@
Protocols: SMTP
Added: 7.69.0
Category: smtp
+Example: --mail-rcpt-allowfails --mail-rcpt [email protected] smtp://example.com
---
When sending data to multiple recipients, by default curl will abort SMTP
conversation if at least one of the recipients causes RCPT TO command to
diff --git a/docs/cmdline-opts/mail-rcpt.d b/docs/cmdline-opts/mail-rcpt.d
index d464bb4..d4a2502 100644
--- a/docs/cmdline-opts/mail-rcpt.d
+++ b/docs/cmdline-opts/mail-rcpt.d
@@ -4,6 +4,7 @@
Protocols: SMTP
Added: 7.20.0
Category: smtp
+Example: --mail-rcpt [email protected] smtp://example.com
---
Specify a single e-mail address, user name or mailing list name. Repeat this
option several times to send to multiple recipients.
diff --git a/docs/cmdline-opts/manual.d b/docs/cmdline-opts/manual.d
index 25ed08d..c81754b 100644
--- a/docs/cmdline-opts/manual.d
+++ b/docs/cmdline-opts/manual.d
@@ -2,5 +2,6 @@
Short: M
Help: Display the full manual
Category: curl
+Example: --manual
---
Manual. Display the huge help text.
diff --git a/docs/cmdline-opts/max-filesize.d b/docs/cmdline-opts/max-filesize.d
index 6717f2d..0f8aca4 100644
--- a/docs/cmdline-opts/max-filesize.d
+++ b/docs/cmdline-opts/max-filesize.d
@@ -4,6 +4,7 @@
Protocols: FTP HTTP MQTT
See-also: limit-rate
Category: connection
+Example: --max-filesize 100K $URL
---
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
diff --git a/docs/cmdline-opts/max-redirs.d b/docs/cmdline-opts/max-redirs.d
index 1b5de5b..eade17f 100644
--- a/docs/cmdline-opts/max-redirs.d
+++ b/docs/cmdline-opts/max-redirs.d
@@ -3,6 +3,7 @@
Help: Maximum number of redirects allowed
Protocols: HTTP
Category: http
+Example: --max-redirs 3 --location $URL
---
Set maximum number of redirections to follow. When --location is used, to
prevent curl from following too many redirects, by default, the limit is
diff --git a/docs/cmdline-opts/max-time.d b/docs/cmdline-opts/max-time.d
index c4e4ed7..cb86fa9 100644
--- a/docs/cmdline-opts/max-time.d
+++ b/docs/cmdline-opts/max-time.d
@@ -1,9 +1,11 @@
Long: max-time
Short: m
-Arg: <seconds>
-Help: Maximum time allowed for the transfer
+Arg: <fractional seconds>
+Help: Maximum time allowed for transfer
See-also: connect-timeout
Category: connection
+Example: --max-time 10 $URL
+Example: --max-time 2.92 $URL
---
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
diff --git a/docs/cmdline-opts/metalink.d b/docs/cmdline-opts/metalink.d
index 4725b38..1fc1087 100644
--- a/docs/cmdline-opts/metalink.d
+++ b/docs/cmdline-opts/metalink.d
@@ -2,6 +2,7 @@
Help: Process given URLs as metalink XML file
Added: 7.27.0
Category: misc
+Example: --metalink file $URL
---
This option was previously used to specify a metalink resource. Metalink
support has been disabled in curl since 7.78.0 for security reasons.
diff --git a/docs/cmdline-opts/negotiate.d b/docs/cmdline-opts/negotiate.d
index e247bfb..e862bc8 100644
--- a/docs/cmdline-opts/negotiate.d
+++ b/docs/cmdline-opts/negotiate.d
@@ -3,6 +3,7 @@
Protocols: HTTP
See-also: basic ntlm anyauth proxy-negotiate
Category: auth http
+Example: --negotiate -u : $URL
---
Enables Negotiate (SPNEGO) authentication.
diff --git a/docs/cmdline-opts/netrc-file.d b/docs/cmdline-opts/netrc-file.d
index 95fb265..df89d51 100644
--- a/docs/cmdline-opts/netrc-file.d
+++ b/docs/cmdline-opts/netrc-file.d
@@ -4,6 +4,7 @@
Added: 7.21.5
Mutexed: netrc
Category: curl
+Example: --netrc-file netrc $URL
---
This option is similar to --netrc, except that you provide the path (absolute
or relative) to the netrc file that curl should use. You can only specify one
diff --git a/docs/cmdline-opts/netrc-optional.d b/docs/cmdline-opts/netrc-optional.d
index e0b59d1..3869a20 100644
--- a/docs/cmdline-opts/netrc-optional.d
+++ b/docs/cmdline-opts/netrc-optional.d
@@ -3,6 +3,7 @@
Mutexed: netrc
See-also: netrc-file
Category: curl
+Example: --netrc-optional $URL
---
Very similar to --netrc, but this option makes the .netrc usage **optional**
and not mandatory as the --netrc option does.
diff --git a/docs/cmdline-opts/netrc.d b/docs/cmdline-opts/netrc.d
index a31e2ed..21e33a1 100644
--- a/docs/cmdline-opts/netrc.d
+++ b/docs/cmdline-opts/netrc.d
@@ -2,6 +2,7 @@
Short: n
Help: Must read .netrc for user name and password
Category: curl
+Example: --netrc $URL
---
Makes curl scan the *.netrc* (*_netrc* on Windows) file in the user's home
directory for login name and password. This is typically used for FTP on
diff --git a/docs/cmdline-opts/next.d b/docs/cmdline-opts/next.d
index 1adcc75..bcbad68 100644
--- a/docs/cmdline-opts/next.d
+++ b/docs/cmdline-opts/next.d
@@ -6,6 +6,8 @@
Magic: divider
Help: Make next URL use its separate set of options
Category: curl
+Example: $URL --next -d postthis www2.example.com
+Example: -I $URL --next https://example.net/
---
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
@@ -18,4 +20,6 @@
For example, you can do both a GET and a POST in a single command line:
+.nf
curl www1.example.com --next -d postthis www2.example.com
+.fi
diff --git a/docs/cmdline-opts/no-alpn.d b/docs/cmdline-opts/no-alpn.d
index 8031b4f..bc62076 100644
--- a/docs/cmdline-opts/no-alpn.d
+++ b/docs/cmdline-opts/no-alpn.d
@@ -6,6 +6,7 @@
Requires: TLS
Help: Disable the ALPN TLS extension
Category: tls http
+Example: --no-alpn $URL
---
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
diff --git a/docs/cmdline-opts/no-buffer.d b/docs/cmdline-opts/no-buffer.d
index 1079f47..fe8da4e 100644
--- a/docs/cmdline-opts/no-buffer.d
+++ b/docs/cmdline-opts/no-buffer.d
@@ -2,6 +2,7 @@
Short: N
Help: Disable buffering of the output stream
Category: curl
+Example: --no-buffer $URL
---
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
diff --git a/docs/cmdline-opts/no-keepalive.d b/docs/cmdline-opts/no-keepalive.d
index 72f3bc9..a264b7a 100644
--- a/docs/cmdline-opts/no-keepalive.d
+++ b/docs/cmdline-opts/no-keepalive.d
@@ -1,6 +1,7 @@
Long: no-keepalive
Help: Disable TCP keepalive on the connection
Category: connection
+Example: --no-keepalive $URL
---
Disables the use of keepalive messages on the TCP connection. curl otherwise
enables them by default.
diff --git a/docs/cmdline-opts/no-npn.d b/docs/cmdline-opts/no-npn.d
index 27e5974..7a9239d 100644
--- a/docs/cmdline-opts/no-npn.d
+++ b/docs/cmdline-opts/no-npn.d
@@ -7,6 +7,7 @@
Requires: TLS
Help: Disable the NPN TLS extension
Category: tls http
+Example: --no-npn $URL
---
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
diff --git a/docs/cmdline-opts/no-progress-meter.d b/docs/cmdline-opts/no-progress-meter.d
index bf28d63..9c7413e 100644
--- a/docs/cmdline-opts/no-progress-meter.d
+++ b/docs/cmdline-opts/no-progress-meter.d
@@ -3,6 +3,7 @@
See-also: verbose silent
Added: 7.67.0
Category: verbose
+Example: --no-progress-meter -o store $URL
---
Option to switch off the progress meter output without muting or otherwise
affecting warning and informational messages like --silent does.
diff --git a/docs/cmdline-opts/no-sessionid.d b/docs/cmdline-opts/no-sessionid.d
index 013ca4c..70a3221 100644
--- a/docs/cmdline-opts/no-sessionid.d
+++ b/docs/cmdline-opts/no-sessionid.d
@@ -3,6 +3,7 @@
Protocols: TLS
Added: 7.16.0
Category: tls
+Example: --no-sessionid $URL
---
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
diff --git a/docs/cmdline-opts/noproxy.d b/docs/cmdline-opts/noproxy.d
index c49e6d1..ee0978e 100644
--- a/docs/cmdline-opts/noproxy.d
+++ b/docs/cmdline-opts/noproxy.d
@@ -3,6 +3,7 @@
Help: List of hosts which do not use proxy
Added: 7.19.4
Category: proxy
+Example: --noproxy "www.example" $URL
---
Comma-separated list of hosts for which not to use a proxy, if one is
specified. The only wildcard is a single * character, which matches all hosts,
diff --git a/docs/cmdline-opts/ntlm-wb.d b/docs/cmdline-opts/ntlm-wb.d
index 4a2f7e1..8901370 100644
--- a/docs/cmdline-opts/ntlm-wb.d
+++ b/docs/cmdline-opts/ntlm-wb.d
@@ -3,6 +3,7 @@
Protocols: HTTP
See-also: ntlm proxy-ntlm
Category: auth http
+Example: --ntlm-wb -u user:password $URL
---
Enables NTLM much in the style --ntlm does, but hand over the authentication
to the separate binary ntlmauth application that is executed when needed.
diff --git a/docs/cmdline-opts/ntlm.d b/docs/cmdline-opts/ntlm.d
index c63c086..5a50632 100644
--- a/docs/cmdline-opts/ntlm.d
+++ b/docs/cmdline-opts/ntlm.d
@@ -5,6 +5,7 @@
Protocols: HTTP
Requires: TLS
Category: auth http
+Example: --ntlm -u user:password $URL
---
Enables NTLM authentication. The NTLM authentication method was designed by
Microsoft and is used by IIS web servers. It is a proprietary protocol,
diff --git a/docs/cmdline-opts/oauth2-bearer.d b/docs/cmdline-opts/oauth2-bearer.d
index e0ea210..1662a36 100644
--- a/docs/cmdline-opts/oauth2-bearer.d
+++ b/docs/cmdline-opts/oauth2-bearer.d
@@ -3,6 +3,7 @@
Arg: <token>
Protocols: IMAP POP3 SMTP HTTP
Category: auth
+Example: --oauth2-bearer "mF_9.B5f-4.1JqM" $URL
---
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
diff --git a/docs/cmdline-opts/output-dir.d b/docs/cmdline-opts/output-dir.d
index d2ff773..1664f45 100644
--- a/docs/cmdline-opts/output-dir.d
+++ b/docs/cmdline-opts/output-dir.d
@@ -4,6 +4,7 @@
Added: 7.73.0
See-also: remote-name remote-header-name
Category: curl
+Example: --output-dir "tmp" -O $URL
---
This option specifies the directory in which files should be stored, when
diff --git a/docs/cmdline-opts/output.d b/docs/cmdline-opts/output.d
index d639a23..ce9749d 100644
--- a/docs/cmdline-opts/output.d
+++ b/docs/cmdline-opts/output.d
@@ -4,6 +4,10 @@
Help: Write to file instead of stdout
See-also: remote-name remote-name-all remote-header-name
Category: important curl
+Example: -o file $URL
+Example: "http://{one,two}.example.com" -o "file_#1.txt"
+Example: "http://{site,host}.host[1-5].com" -o "#1_#2"
+Example: -o file $URL -o file2 https://example.net
---
Write output to <file> instead of stdout. If you are using {} or [] to fetch
multiple documents, you should quote the URL and you can use '#' followed by a
diff --git a/docs/cmdline-opts/parallel-immediate.d b/docs/cmdline-opts/parallel-immediate.d
index 47b9a79..4f7468d 100644
--- a/docs/cmdline-opts/parallel-immediate.d
+++ b/docs/cmdline-opts/parallel-immediate.d
@@ -3,6 +3,7 @@
Added: 7.68.0
See-also: parallel parallel-max
Category: connection curl
+Example: --parallel-immediate -Z $URL -o file1 $URL -o file2
---
When doing parallel transfers, this option will instruct curl that it should
rather prefer opening up more connections in parallel at once rather than
diff --git a/docs/cmdline-opts/parallel-max.d b/docs/cmdline-opts/parallel-max.d
index 9ec807c..1f22fcb 100644
--- a/docs/cmdline-opts/parallel-max.d
+++ b/docs/cmdline-opts/parallel-max.d
@@ -4,6 +4,7 @@
Added: 7.66.0
See-also: parallel
Category: connection curl
+Example: --parallel-max 100 -Z $URL ftp://example.com/
---
When asked to do parallel transfers, using --parallel, this option controls
the maximum amount of transfers to do simultaneously.
diff --git a/docs/cmdline-opts/parallel.d b/docs/cmdline-opts/parallel.d
index d49158c..2a0ca43 100644
--- a/docs/cmdline-opts/parallel.d
+++ b/docs/cmdline-opts/parallel.d
@@ -3,6 +3,7 @@
Help: Perform transfers in parallel
Added: 7.66.0
Category: connection curl
+Example: --parallel $URL -o file1 $URL -o file2
---
Makes curl perform its transfers in parallel as compared to the regular serial
manner.
diff --git a/docs/cmdline-opts/pass.d b/docs/cmdline-opts/pass.d
index e3fb97a..58e3558 100644
--- a/docs/cmdline-opts/pass.d
+++ b/docs/cmdline-opts/pass.d
@@ -3,6 +3,7 @@
Help: Pass phrase for the private key
Protocols: SSH TLS
Category: ssh tls auth
+Example: --pass secret --key file $URL
---
Passphrase for the private key.
diff --git a/docs/cmdline-opts/path-as-is.d b/docs/cmdline-opts/path-as-is.d
index 0bfaf66..fb87def 100644
--- a/docs/cmdline-opts/path-as-is.d
+++ b/docs/cmdline-opts/path-as-is.d
@@ -2,6 +2,7 @@
Help: Do not squash .. sequences in URL path
Added: 7.42.0
Category: curl
+Example: --path-as-is https://example.com/../../etc/passwd
---
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
diff --git a/docs/cmdline-opts/pinnedpubkey.d b/docs/cmdline-opts/pinnedpubkey.d
index 4e0ed5e..dc98b29 100644
--- a/docs/cmdline-opts/pinnedpubkey.d
+++ b/docs/cmdline-opts/pinnedpubkey.d
@@ -3,6 +3,8 @@
Help: FILE/HASHES Public key to verify peer against
Protocols: TLS
Category: tls
+Example: --pinnedpubkey keyfile $URL
+Example: --pinnedpubkey 'sha256//ce118b51897f4452dc' $URL
---
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
diff --git a/docs/cmdline-opts/post301.d b/docs/cmdline-opts/post301.d
index 64ead05..744ef58 100644
--- a/docs/cmdline-opts/post301.d
+++ b/docs/cmdline-opts/post301.d
@@ -4,6 +4,7 @@
See-also: post302 post303 location
Added: 7.17.1
Category: http post
+Example: --post301 --location -d "data" $URL
---
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 behavior is ubiquitous
diff --git a/docs/cmdline-opts/post302.d b/docs/cmdline-opts/post302.d
index d73cb9d..2c6d4b6 100644
--- a/docs/cmdline-opts/post302.d
+++ b/docs/cmdline-opts/post302.d
@@ -4,6 +4,7 @@
See-also: post301 post303 location
Added: 7.19.1
Category: http post
+Example: --post302 --location -d "data" $URL
---
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 behavior is ubiquitous
diff --git a/docs/cmdline-opts/post303.d b/docs/cmdline-opts/post303.d
index 1a67e13..a2fec18 100644
--- a/docs/cmdline-opts/post303.d
+++ b/docs/cmdline-opts/post303.d
@@ -4,6 +4,7 @@
See-also: post302 post301 location
Added: 7.26.0
Category: http post
+Example: --post303 --location -d "data" $URL
---
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
diff --git a/docs/cmdline-opts/preproxy.d b/docs/cmdline-opts/preproxy.d
index a917c16..c91565c 100644
--- a/docs/cmdline-opts/preproxy.d
+++ b/docs/cmdline-opts/preproxy.d
@@ -3,6 +3,7 @@
Help: Use this proxy first
Added: 7.52.0
Category: proxy
+Example: --preproxy socks5://proxy.example -x http://http.example $URL
---
Use the specified SOCKS proxy before connecting to an HTTP or HTTPS --proxy. In
such a case curl first connects to the SOCKS proxy and then connects (through
diff --git a/docs/cmdline-opts/progress-bar.d b/docs/cmdline-opts/progress-bar.d
index ad2f21b..96ac300 100644
--- a/docs/cmdline-opts/progress-bar.d
+++ b/docs/cmdline-opts/progress-bar.d
@@ -2,6 +2,7 @@
Long: progress-bar
Help: Display transfer progress as a bar
Category: verbose
+Example: -# -O $URL
---
Make curl display transfer progress as a simple progress bar instead of the
standard, more informational, meter.
diff --git a/docs/cmdline-opts/proto-default.d b/docs/cmdline-opts/proto-default.d
index 74d3932..a659b84 100644
--- a/docs/cmdline-opts/proto-default.d
+++ b/docs/cmdline-opts/proto-default.d
@@ -3,17 +3,14 @@
Arg: <protocol>
Added: 7.45.0
Category: connection curl
+Example: --proto-default https ftp.example.com
---
Tells curl to use *protocol* for any URL missing a scheme name.
-Example:
-
- curl --proto-default https ftp.mozilla.org
-
An unknown or unsupported protocol causes error
*CURLE_UNSUPPORTED_PROTOCOL* (1).
This option does not change the default proxy protocol (http).
-Without this option curl would make a guess based on the host, see --url for
-details.
+Without this option set, curl guesses protocol based on the host name, see
+--url for details.
diff --git a/docs/cmdline-opts/proto-redir.d b/docs/cmdline-opts/proto-redir.d
index 10580ad..81d495d 100644
--- a/docs/cmdline-opts/proto-redir.d
+++ b/docs/cmdline-opts/proto-redir.d
@@ -3,6 +3,7 @@
Help: Enable/disable PROTOCOLS on redirect
Added: 7.20.2
Category: connection curl
+Example: --proto-redir =http,https $URL
---
Tells curl to limit what protocols it may use on redirect. Protocols denied by
--proto are not overridden by this option. See --proto for how protocols are
diff --git a/docs/cmdline-opts/proto.d b/docs/cmdline-opts/proto.d
index 1e269a5..6ff52c4 100644
--- a/docs/cmdline-opts/proto.d
+++ b/docs/cmdline-opts/proto.d
@@ -4,6 +4,7 @@
See-also: proto-redir proto-default
Added: 7.20.2
Category: connection curl
+Example: --proto =http,https,sftp $URL
---
Tells curl to limit what protocols it may use for transfers. Protocols are
evaluated left to right, are comma separated, and are each a protocol name or
diff --git a/docs/cmdline-opts/proxy-anyauth.d b/docs/cmdline-opts/proxy-anyauth.d
index 6410c0e..80f2b97 100644
--- a/docs/cmdline-opts/proxy-anyauth.d
+++ b/docs/cmdline-opts/proxy-anyauth.d
@@ -3,6 +3,7 @@
Added: 7.13.2
See-also: proxy proxy-basic proxy-digest
Category: proxy auth
+Example: --proxy-anyauth --proxy-user user:passwd -x proxy $URL
---
Tells curl to pick a suitable authentication method when communicating with
the given HTTP proxy. This might cause an extra request/response round-trip.
diff --git a/docs/cmdline-opts/proxy-basic.d b/docs/cmdline-opts/proxy-basic.d
index e842f99..6d38c73 100644
--- a/docs/cmdline-opts/proxy-basic.d
+++ b/docs/cmdline-opts/proxy-basic.d
@@ -2,6 +2,7 @@
Help: Use Basic authentication on the proxy
See-also: proxy proxy-anyauth proxy-digest
Category: proxy auth
+Example: --proxy-basic --proxy-user user:passwd -x proxy $URL
---
Tells curl to use HTTP Basic authentication when communicating with the given
proxy. Use --basic for enabling HTTP Basic with a remote host. Basic is the
diff --git a/docs/cmdline-opts/proxy-cacert.d b/docs/cmdline-opts/proxy-cacert.d
index bbc731a..5c32944 100644
--- a/docs/cmdline-opts/proxy-cacert.d
+++ b/docs/cmdline-opts/proxy-cacert.d
@@ -4,5 +4,6 @@
Added: 7.52.0
See-also: proxy-capath cacert capath proxy
Category: proxy tls
+Example: --proxy-cacert CA-file.txt -x https://proxy $URL
---
Same as --cacert but used in HTTPS proxy context.
diff --git a/docs/cmdline-opts/proxy-capath.d b/docs/cmdline-opts/proxy-capath.d
index cc342b7..0429984 100644
--- a/docs/cmdline-opts/proxy-capath.d
+++ b/docs/cmdline-opts/proxy-capath.d
@@ -4,5 +4,6 @@
Added: 7.52.0
See-also: proxy-cacert proxy capath
Category: proxy tls
+Example: --proxy-capath /local/directory -x https://proxy $URL
---
Same as --capath but used in HTTPS proxy context.
diff --git a/docs/cmdline-opts/proxy-cert-type.d b/docs/cmdline-opts/proxy-cert-type.d
index fb7596c..2152f53 100644
--- a/docs/cmdline-opts/proxy-cert-type.d
+++ b/docs/cmdline-opts/proxy-cert-type.d
@@ -3,5 +3,6 @@
Added: 7.52.0
Help: Client certificate type for HTTPS proxy
Category: proxy tls
+Example: --proxy-cert-type PEM --proxy-cert file -x https://proxy $URL
---
Same as --cert-type but used in HTTPS proxy context.
diff --git a/docs/cmdline-opts/proxy-cert.d b/docs/cmdline-opts/proxy-cert.d
index 7df2712..3cf54b7 100644
--- a/docs/cmdline-opts/proxy-cert.d
+++ b/docs/cmdline-opts/proxy-cert.d
@@ -3,5 +3,6 @@
Help: Set client certificate for proxy
Added: 7.52.0
Category: proxy tls
+Example: --proxy-cert file -x https://proxy $URL
---
Same as --cert but used in HTTPS proxy context.
diff --git a/docs/cmdline-opts/proxy-ciphers.d b/docs/cmdline-opts/proxy-ciphers.d
index 3665556..b4c3580 100644
--- a/docs/cmdline-opts/proxy-ciphers.d
+++ b/docs/cmdline-opts/proxy-ciphers.d
@@ -3,5 +3,6 @@
Help: SSL ciphers to use for proxy
Added: 7.52.0
Category: proxy tls
+Example: --proxy-ciphers ECDHE-ECDSA-AES256-CCM8 -x https://proxy $URL
---
Same as --ciphers but used in HTTPS proxy context.
diff --git a/docs/cmdline-opts/proxy-crlfile.d b/docs/cmdline-opts/proxy-crlfile.d
index 580dc50..1ac1999 100644
--- a/docs/cmdline-opts/proxy-crlfile.d
+++ b/docs/cmdline-opts/proxy-crlfile.d
@@ -3,5 +3,6 @@
Help: Set a CRL list for proxy
Added: 7.52.0
Category: proxy tls
+Example: --proxy-crlfile rejects.txt -x https://proxy $URL
---
Same as --crlfile but used in HTTPS proxy context.
diff --git a/docs/cmdline-opts/proxy-digest.d b/docs/cmdline-opts/proxy-digest.d
index 52f1fcc..cc18702 100644
--- a/docs/cmdline-opts/proxy-digest.d
+++ b/docs/cmdline-opts/proxy-digest.d
@@ -2,6 +2,7 @@
Help: Use Digest authentication on the proxy
See-also: proxy proxy-anyauth proxy-basic
Category: proxy tls
+Example: --proxy-digest --proxy-user user:passwd -x proxy $URL
---
Tells curl to use HTTP Digest authentication when communicating with the given
proxy. Use --digest for enabling HTTP Digest with a remote host.
diff --git a/docs/cmdline-opts/proxy-header.d b/docs/cmdline-opts/proxy-header.d
index c2b0928..273a773 100644
--- a/docs/cmdline-opts/proxy-header.d
+++ b/docs/cmdline-opts/proxy-header.d
@@ -4,6 +4,9 @@
Protocols: HTTP
Added: 7.37.0
Category: proxy
+Example: --proxy-header "X-First-Name: Joe" -x http://proxy $URL
+Example: --proxy-header "User-Agent: surprise" -x http://proxy $URL
+Example: --proxy-header "Host:" -x http://proxy $URL
---
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 --header
diff --git a/docs/cmdline-opts/proxy-insecure.d b/docs/cmdline-opts/proxy-insecure.d
index e123f40..3f4f7c1 100644
--- a/docs/cmdline-opts/proxy-insecure.d
+++ b/docs/cmdline-opts/proxy-insecure.d
@@ -2,5 +2,6 @@
Help: Do HTTPS proxy connections without verifying the proxy
Added: 7.52.0
Category: proxy tls
+Example: --proxy-insecure -x https://proxy $URL
---
Same as --insecure but used in HTTPS proxy context.
diff --git a/docs/cmdline-opts/proxy-key-type.d b/docs/cmdline-opts/proxy-key-type.d
index 1906872..31f47af 100644
--- a/docs/cmdline-opts/proxy-key-type.d
+++ b/docs/cmdline-opts/proxy-key-type.d
@@ -3,5 +3,6 @@
Help: Private key file type for proxy
Added: 7.52.0
Category: proxy tls
+Example: --proxy-key-type DER --proxy-key here -x https://proxy $URL
---
Same as --key-type but used in HTTPS proxy context.
diff --git a/docs/cmdline-opts/proxy-key.d b/docs/cmdline-opts/proxy-key.d
index 57d469f..1b97973 100644
--- a/docs/cmdline-opts/proxy-key.d
+++ b/docs/cmdline-opts/proxy-key.d
@@ -2,5 +2,6 @@
Help: Private key for HTTPS proxy
Arg: <key>
Category: proxy tls
+Example: --proxy-key here -x https://proxy $URL
---
Same as --key but used in HTTPS proxy context.
diff --git a/docs/cmdline-opts/proxy-negotiate.d b/docs/cmdline-opts/proxy-negotiate.d
index 72f3596..5085a7c 100644
--- a/docs/cmdline-opts/proxy-negotiate.d
+++ b/docs/cmdline-opts/proxy-negotiate.d
@@ -3,6 +3,7 @@
Added: 7.17.1
See-also: proxy-anyauth proxy-basic
Category: proxy auth
+Example: --proxy-negotiate --proxy-user user:passwd -x proxy $URL
---
Tells curl to use HTTP Negotiate (SPNEGO) authentication when communicating
with the given proxy. Use --negotiate for enabling HTTP Negotiate (SPNEGO)
diff --git a/docs/cmdline-opts/proxy-ntlm.d b/docs/cmdline-opts/proxy-ntlm.d
index cb1ba7b..074b7df 100644
--- a/docs/cmdline-opts/proxy-ntlm.d
+++ b/docs/cmdline-opts/proxy-ntlm.d
@@ -2,6 +2,7 @@
Help: Use NTLM authentication on the proxy
See-also: proxy-negotiate proxy-anyauth
Category: proxy auth
+Example: --proxy-ntlm --proxy-user user:passwd -x http://proxy $URL
---
Tells curl to use HTTP NTLM authentication when communicating with the given
proxy. Use --ntlm for enabling NTLM with a remote host.
diff --git a/docs/cmdline-opts/proxy-pass.d b/docs/cmdline-opts/proxy-pass.d
index 627451b..b714684 100644
--- a/docs/cmdline-opts/proxy-pass.d
+++ b/docs/cmdline-opts/proxy-pass.d
@@ -3,5 +3,6 @@
Help: Pass phrase for the private key for HTTPS proxy
Added: 7.52.0
Category: proxy tls auth
+Example: --proxy-pass secret --proxy-key here -x https://proxy $URL
---
Same as --pass but used in HTTPS proxy context.
diff --git a/docs/cmdline-opts/proxy-pinnedpubkey.d b/docs/cmdline-opts/proxy-pinnedpubkey.d
index 2ab79f1..b7f50a7 100644
--- a/docs/cmdline-opts/proxy-pinnedpubkey.d
+++ b/docs/cmdline-opts/proxy-pinnedpubkey.d
@@ -3,6 +3,8 @@
Help: FILE/HASHES public key to verify proxy with
Protocols: TLS
Category: proxy tls
+Example: --proxy-pinnedpubkey keyfile $URL
+Example: --proxy-pinnedpubkey 'sha256//ce118b51897f4452dc' $URL
---
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
diff --git a/docs/cmdline-opts/proxy-service-name.d b/docs/cmdline-opts/proxy-service-name.d
index f780729..fbed175 100644
--- a/docs/cmdline-opts/proxy-service-name.d
+++ b/docs/cmdline-opts/proxy-service-name.d
@@ -3,5 +3,6 @@
Help: SPNEGO proxy service name
Added: 7.43.0
Category: proxy tls
+Example: --proxy-service-name "shrubbery" -x proxy $URL
---
This option allows you to change the service name for proxy negotiation.
diff --git a/docs/cmdline-opts/proxy-ssl-allow-beast.d b/docs/cmdline-opts/proxy-ssl-allow-beast.d
index 138001b..b3e701f 100644
--- a/docs/cmdline-opts/proxy-ssl-allow-beast.d
+++ b/docs/cmdline-opts/proxy-ssl-allow-beast.d
@@ -2,5 +2,6 @@
Help: Allow security flaw for interop for HTTPS proxy
Added: 7.52.0
Category: proxy tls
+Example: --proxy-ssl-allow-beast -x https://proxy $URL
---
Same as --ssl-allow-beast but used in HTTPS proxy context.
diff --git a/docs/cmdline-opts/proxy-ssl-auto-client-cert.d b/docs/cmdline-opts/proxy-ssl-auto-client-cert.d
index 0541754..7c071d7 100644
--- a/docs/cmdline-opts/proxy-ssl-auto-client-cert.d
+++ b/docs/cmdline-opts/proxy-ssl-auto-client-cert.d
@@ -2,5 +2,6 @@
Help: Use auto client certificate for proxy (Schannel)
Added: 7.77.0
Category: proxy tls
+Example: --proxy-ssl-auto-client-cert -x https://proxy $URL
---
Same as --ssl-auto-client-cert but used in HTTPS proxy context.
diff --git a/docs/cmdline-opts/proxy-tls13-ciphers.d b/docs/cmdline-opts/proxy-tls13-ciphers.d
index 9f03f13..62578f7 100644
--- a/docs/cmdline-opts/proxy-tls13-ciphers.d
+++ b/docs/cmdline-opts/proxy-tls13-ciphers.d
@@ -3,6 +3,7 @@
help: TLS 1.3 proxy cipher suites
Protocols: TLS
Category: proxy tls
+Example: --proxy-tls13-ciphers TLS_AES_128_GCM_SHA256 -x proxy $URL
---
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
diff --git a/docs/cmdline-opts/proxy-tlsauthtype.d b/docs/cmdline-opts/proxy-tlsauthtype.d
index 5649a0f..c00928e 100644
--- a/docs/cmdline-opts/proxy-tlsauthtype.d
+++ b/docs/cmdline-opts/proxy-tlsauthtype.d
@@ -3,5 +3,6 @@
Help: TLS authentication type for HTTPS proxy
Added: 7.52.0
Category: proxy tls auth
+Example: --proxy-tlsauthtype SRP -x https://proxy $URL
---
Same as --tlsauthtype but used in HTTPS proxy context.
diff --git a/docs/cmdline-opts/proxy-tlspassword.d b/docs/cmdline-opts/proxy-tlspassword.d
index 38a33d4..89b551d 100644
--- a/docs/cmdline-opts/proxy-tlspassword.d
+++ b/docs/cmdline-opts/proxy-tlspassword.d
@@ -3,5 +3,6 @@
Help: TLS password for HTTPS proxy
Added: 7.52.0
Category: proxy tls auth
+Example: --proxy-tlspassword passwd -x https://proxy $URL
---
Same as --tlspassword but used in HTTPS proxy context.
diff --git a/docs/cmdline-opts/proxy-tlsuser.d b/docs/cmdline-opts/proxy-tlsuser.d
index 587f7f5..b3c400e 100644
--- a/docs/cmdline-opts/proxy-tlsuser.d
+++ b/docs/cmdline-opts/proxy-tlsuser.d
@@ -3,5 +3,6 @@
Help: TLS username for HTTPS proxy
Added: 7.52.0
Category: proxy tls auth
+Example: --proxy-tlsuser smith -x https://proxy $URL
---
Same as --tlsuser but used in HTTPS proxy context.
diff --git a/docs/cmdline-opts/proxy-tlsv1.d b/docs/cmdline-opts/proxy-tlsv1.d
index 5003f5f..c54782e 100644
--- a/docs/cmdline-opts/proxy-tlsv1.d
+++ b/docs/cmdline-opts/proxy-tlsv1.d
@@ -2,5 +2,6 @@
Help: Use TLSv1 for HTTPS proxy
Added: 7.52.0
Category: proxy tls auth
+Example: --proxy-tlsv1 -x https://proxy $URL
---
Same as --tlsv1 but used in HTTPS proxy context.
diff --git a/docs/cmdline-opts/proxy-user.d b/docs/cmdline-opts/proxy-user.d
index 82fc517..81d29f2 100644
--- a/docs/cmdline-opts/proxy-user.d
+++ b/docs/cmdline-opts/proxy-user.d
@@ -3,6 +3,7 @@
Arg: <user:password>
Help: Proxy user and password
Category: proxy auth
+Example: --proxy-user name:pwd -x proxy $URL
---
Specify the user name and password to use for proxy authentication.
diff --git a/docs/cmdline-opts/proxy.d b/docs/cmdline-opts/proxy.d
index 0592f13..81d9bc9 100644
--- a/docs/cmdline-opts/proxy.d
+++ b/docs/cmdline-opts/proxy.d
@@ -3,6 +3,7 @@
Arg: [protocol://]host[:port]
Help: Use this proxy
Category: proxy
+Example: --proxy http://proxy.example $URL
---
Use the specified proxy.
diff --git a/docs/cmdline-opts/proxy1.0.d b/docs/cmdline-opts/proxy1.0.d
index b8a232b..f748345 100644
--- a/docs/cmdline-opts/proxy1.0.d
+++ b/docs/cmdline-opts/proxy1.0.d
@@ -2,6 +2,7 @@
Arg: <host[:port]>
Help: Use HTTP/1.0 proxy on given port
Category: proxy
+Example: --proxy1.0 -x http://proxy $URL
---
Use the specified HTTP 1.0 proxy. If the port number is not specified, it is
assumed at port 1080.
diff --git a/docs/cmdline-opts/proxytunnel.d b/docs/cmdline-opts/proxytunnel.d
index 94dae99..712c755 100644
--- a/docs/cmdline-opts/proxytunnel.d
+++ b/docs/cmdline-opts/proxytunnel.d
@@ -3,6 +3,7 @@
Help: Operate through an HTTP proxy tunnel (using CONNECT)
See-also: proxy
Category: proxy
+Example: --proxytunnel -x http://proxy $URL
---
When an HTTP proxy is used --proxy, this option will make curl tunnel through
the proxy. The tunnel approach is made with the HTTP proxy CONNECT request and
diff --git a/docs/cmdline-opts/pubkey.d b/docs/cmdline-opts/pubkey.d
index 692daf6..c1fb5d8 100644
--- a/docs/cmdline-opts/pubkey.d
+++ b/docs/cmdline-opts/pubkey.d
@@ -3,6 +3,7 @@
Protocols: SFTP SCP
Help: SSH Public key file name
Category: sftp scp auth
+Example: --pubkey file.pub sftp://example.com/
---
Public key file name. Allows you to provide your public key in this separate
file.
diff --git a/docs/cmdline-opts/quote.d b/docs/cmdline-opts/quote.d
index 3adb06f..2707c87 100644
--- a/docs/cmdline-opts/quote.d
+++ b/docs/cmdline-opts/quote.d
@@ -4,6 +4,7 @@
Help: Send command(s) to server before transfer
Protocols: FTP SFTP
Category: ftp sftp
+Example: --quote "DELE file" ftp://example.com/foo
---
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
diff --git a/docs/cmdline-opts/random-file.d b/docs/cmdline-opts/random-file.d
index c57f523..a207c1e 100644
--- a/docs/cmdline-opts/random-file.d
+++ b/docs/cmdline-opts/random-file.d
@@ -2,6 +2,7 @@
Arg: <file>
Help: File for reading random data from
Category: misc
+Example: --random-file rubbish $URL
---
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
diff --git a/docs/cmdline-opts/range.d b/docs/cmdline-opts/range.d
index e2d1f62..0637f8fc 100644
--- a/docs/cmdline-opts/range.d
+++ b/docs/cmdline-opts/range.d
@@ -4,6 +4,7 @@
Arg: <range>
Protocols: HTTP FTP SFTP FILE
Category: http ftp sftp file
+Example: --range 22-44 $URL
---
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.
diff --git a/docs/cmdline-opts/raw.d b/docs/cmdline-opts/raw.d
index 90e7772..c44d33f 100644
--- a/docs/cmdline-opts/raw.d
+++ b/docs/cmdline-opts/raw.d
@@ -3,6 +3,7 @@
Added: 7.16.2
Protocols: HTTP
Category: http
+Example: --raw $URL
---
When used, it disables all internal HTTP decoding of content or transfer
encodings and instead makes them passed on unaltered, raw.
diff --git a/docs/cmdline-opts/referer.d b/docs/cmdline-opts/referer.d
index 8b2057b..3f6b7c7 100644
--- a/docs/cmdline-opts/referer.d
+++ b/docs/cmdline-opts/referer.d
@@ -5,6 +5,9 @@
Help: Referrer URL
See-also: user-agent header
Category: http
+Example: --referer "https://fake.example" $URL
+Example: --referer "https://fake.example;auto" -L $URL
+Example: --referer ";auto" -L $URL
---
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
diff --git a/docs/cmdline-opts/remote-header-name.d b/docs/cmdline-opts/remote-header-name.d
index 325dade..6e0b98b 100644
--- a/docs/cmdline-opts/remote-header-name.d
+++ b/docs/cmdline-opts/remote-header-name.d
@@ -3,6 +3,7 @@
Protocols: HTTP
Help: Use the header-provided filename
Category: output
+Example: -OJ https://example.com/file
---
This option tells the --remote-name option to use the server-specified
Content-Disposition filename instead of extracting a filename from the URL.
diff --git a/docs/cmdline-opts/remote-name-all.d b/docs/cmdline-opts/remote-name-all.d
index 299684c..e27bd5f 100644
--- a/docs/cmdline-opts/remote-name-all.d
+++ b/docs/cmdline-opts/remote-name-all.d
@@ -2,6 +2,7 @@
Help: Use the remote file name for all URLs
Added: 7.19.0
Category: output
+Example: --remote-name-all ftp://example.com/file1 ftp://example.com/file2
---
This option changes the default action for all given URLs to be dealt with as
if --remote-name were used for each one. So if you want to disable that for a
diff --git a/docs/cmdline-opts/remote-name.d b/docs/cmdline-opts/remote-name.d
index 184c32e..6892879 100644
--- a/docs/cmdline-opts/remote-name.d
+++ b/docs/cmdline-opts/remote-name.d
@@ -2,6 +2,7 @@
Short: O
Help: Write output to a file named as the remote file
Category: important output
+Example: -O https://example.com/filename
---
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.)
diff --git a/docs/cmdline-opts/remote-time.d b/docs/cmdline-opts/remote-time.d
index 96fb4fb..9c463ae 100644
--- a/docs/cmdline-opts/remote-time.d
+++ b/docs/cmdline-opts/remote-time.d
@@ -2,6 +2,7 @@
Short: R
Help: Set the remote file's time on the local output
Category: output
+Example: --remote-time -o foo $URL
---
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
diff --git a/docs/cmdline-opts/request-target.d b/docs/cmdline-opts/request-target.d
index 4422611..5f9e475 100644
--- a/docs/cmdline-opts/request-target.d
+++ b/docs/cmdline-opts/request-target.d
@@ -4,6 +4,7 @@
Protocols: HTTP
Added: 7.55.0
Category: http
+Example: --request-target "*" -X OPTIONS $URL
---
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
diff --git a/docs/cmdline-opts/request.d b/docs/cmdline-opts/request.d
index 47c4c8b..0db0bc9 100644
--- a/docs/cmdline-opts/request.d
+++ b/docs/cmdline-opts/request.d
@@ -3,6 +3,8 @@
Arg: <command>
Help: Specify request command to use
Category: connection
+Example: -X "DELETE" $URL
+Example: -X NLST ftp://example.com/
---
(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
diff --git a/docs/cmdline-opts/resolve.d b/docs/cmdline-opts/resolve.d
index ff10f28..6464c42 100644
--- a/docs/cmdline-opts/resolve.d
+++ b/docs/cmdline-opts/resolve.d
@@ -3,6 +3,7 @@
Help: Resolve the host+port to this address
Added: 7.21.3
Category: connection
+Example: --resolve example.com:443:127.0.0.1 $URL
---
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
diff --git a/docs/cmdline-opts/retry-all-errors.d b/docs/cmdline-opts/retry-all-errors.d
index 5ad1da0..5cab5dd 100644
--- a/docs/cmdline-opts/retry-all-errors.d
+++ b/docs/cmdline-opts/retry-all-errors.d
@@ -2,6 +2,7 @@
Help: Retry all errors (use with --retry)
Added: 7.71.0
Category: curl
+Example: --retry-all-errors $URL
---
Retry on any error. This option is used together with --retry.
@@ -11,13 +12,14 @@
much better off handling your unique problems in shell script. Please read the
example below.
-Warning: For server compatibility curl attempts to retry failed flaky transfers
-as close as possible to how they were started, but this is not possible with
-redirected input or output. For example, before retrying it removes output data
-from a failed partial transfer that was written to an output file. However this
-is not true of data redirected to a | pipe or > file, which are not reset. We
-strongly suggest don't parse or record output via redirect in combination with
-this option, since you may receive duplicate data.
+**WARNING**: For server compatibility curl attempts to retry failed flaky
+transfers as close as possible to how they were started, but this is not
+possible with redirected input or output. For example, before retrying it
+removes output data from a failed partial transfer that was written to an
+output file. However this is not true of data redirected to a | pipe or >
+file, which are not reset. We strongly suggest don't parse or record output
+via redirect in combination with this option, since you may receive duplicate
+data.
By default curl will not error on an HTTP response code that indicates an HTTP
error, if the transfer was successful. For example, if a server replies 404
diff --git a/docs/cmdline-opts/retry-connrefused.d b/docs/cmdline-opts/retry-connrefused.d
index be34f97..ad079e0 100644
--- a/docs/cmdline-opts/retry-connrefused.d
+++ b/docs/cmdline-opts/retry-connrefused.d
@@ -2,6 +2,7 @@
Help: Retry on connection refused (use with --retry)
Added: 7.52.0
Category: curl
+Example: --retry-connrefused --retry $URL
---
In addition to the other conditions, consider ECONNREFUSED as a transient
error too for --retry. This option is used together with --retry.
diff --git a/docs/cmdline-opts/retry-delay.d b/docs/cmdline-opts/retry-delay.d
index 5645c0e..2839129 100644
--- a/docs/cmdline-opts/retry-delay.d
+++ b/docs/cmdline-opts/retry-delay.d
@@ -3,6 +3,7 @@
Help: Wait time between retries
Added: 7.12.3
Category: curl
+Example: --retry-delay 5 --retry $URL
---
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
diff --git a/docs/cmdline-opts/retry-max-time.d b/docs/cmdline-opts/retry-max-time.d
index 9d6faf3..acccff5 100644
--- a/docs/cmdline-opts/retry-max-time.d
+++ b/docs/cmdline-opts/retry-max-time.d
@@ -3,6 +3,7 @@
Help: Retry only within this period
Added: 7.12.3
Category: curl
+Example: --retry-max-time 30 --retry 10 $URL
---
The retry timer is reset before the first transfer attempt. Retries will be
done as usual (see --retry) as long as the timer hasn't reached this given
diff --git a/docs/cmdline-opts/retry.d b/docs/cmdline-opts/retry.d
index bff0ef2..6238383 100644
--- a/docs/cmdline-opts/retry.d
+++ b/docs/cmdline-opts/retry.d
@@ -3,6 +3,7 @@
Added: 7.12.3
Help: Retry request if transient problems occur
Category: curl
+Example: --retry 7 $URL
---
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
diff --git a/docs/cmdline-opts/sasl-authzid.d b/docs/cmdline-opts/sasl-authzid.d
index e802c80..9065bd5 100644
--- a/docs/cmdline-opts/sasl-authzid.d
+++ b/docs/cmdline-opts/sasl-authzid.d
@@ -3,6 +3,7 @@
Help: Identity for SASL PLAIN authentication
Added: 7.66.0
Category: auth
+Example: --sasl-authzid zid imap://example.com/
---
Use this authorisation identity (authzid), during SASL PLAIN authentication,
in addition to the authentication identity (authcid) as specified by --user.
diff --git a/docs/cmdline-opts/sasl-ir.d b/docs/cmdline-opts/sasl-ir.d
index 0041c3b..5004306 100644
--- a/docs/cmdline-opts/sasl-ir.d
+++ b/docs/cmdline-opts/sasl-ir.d
@@ -2,5 +2,6 @@
Help: Enable initial response in SASL authentication
Added: 7.31.0
Category: auth
+Example: --sasl-ir imap://example.com/
---
Enable initial response in SASL authentication.
diff --git a/docs/cmdline-opts/service-name.d b/docs/cmdline-opts/service-name.d
index c64496b..3a5559b 100644
--- a/docs/cmdline-opts/service-name.d
+++ b/docs/cmdline-opts/service-name.d
@@ -3,6 +3,7 @@
Arg: <name>
Added: 7.43.0
Category: misc
+Example: --service-name sockd/server $URL
---
This option allows you to change the service name for SPNEGO.
diff --git a/docs/cmdline-opts/show-error.d b/docs/cmdline-opts/show-error.d
index 258949a..e8b2177 100644
--- a/docs/cmdline-opts/show-error.d
+++ b/docs/cmdline-opts/show-error.d
@@ -3,6 +3,7 @@
Help: Show error even when -s is used
See-also: no-progress-meter
Category: curl
+Example: --show-error --silent $URL
---
When used with --silent, it makes curl show an error message if it fails.
diff --git a/docs/cmdline-opts/silent.d b/docs/cmdline-opts/silent.d
index 58a5223..7122c54 100644
--- a/docs/cmdline-opts/silent.d
+++ b/docs/cmdline-opts/silent.d
@@ -3,6 +3,7 @@
Help: Silent mode
See-also: verbose stderr no-progress-meter
Category: important verbose
+Example: -s $URL
---
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
diff --git a/docs/cmdline-opts/socks4.d b/docs/cmdline-opts/socks4.d
index 3cfb254..1cae1e1 100644
--- a/docs/cmdline-opts/socks4.d
+++ b/docs/cmdline-opts/socks4.d
@@ -3,6 +3,7 @@
Help: SOCKS4 proxy on given host + port
Added: 7.15.2
Category: proxy
+Example: --socks4 hostname:4096 $URL
---
Use the specified SOCKS4 proxy. If the port number is not specified, it is
assumed at port 1080. Using this socket type make curl resolve the host name
diff --git a/docs/cmdline-opts/socks4a.d b/docs/cmdline-opts/socks4a.d
index d820566..8edefdd 100644
--- a/docs/cmdline-opts/socks4a.d
+++ b/docs/cmdline-opts/socks4a.d
@@ -3,6 +3,7 @@
Help: SOCKS4a proxy on given host + port
Added: 7.18.0
Category: proxy
+Example: --socks4a hostname:4096 $URL
---
Use the specified SOCKS4a proxy. If the port number is not specified, it is
assumed at port 1080. This asks the proxy to resolve the host name.
diff --git a/docs/cmdline-opts/socks5-basic.d b/docs/cmdline-opts/socks5-basic.d
index 52d1e66..f32e0bf 100644
--- a/docs/cmdline-opts/socks5-basic.d
+++ b/docs/cmdline-opts/socks5-basic.d
@@ -2,6 +2,7 @@
Help: Enable username/password auth for SOCKS5 proxies
Added: 7.55.0
Category: proxy auth
+Example: --socks5-basic --socks5 hostname:4096 $URL
---
Tells curl to use username/password authentication when connecting to a SOCKS5
proxy. The username/password authentication is enabled by default. Use
diff --git a/docs/cmdline-opts/socks5-gssapi-nec.d b/docs/cmdline-opts/socks5-gssapi-nec.d
index b538f33..73cac7a 100644
--- a/docs/cmdline-opts/socks5-gssapi-nec.d
+++ b/docs/cmdline-opts/socks5-gssapi-nec.d
@@ -2,6 +2,7 @@
Help: Compatibility with NEC SOCKS5 server
Added: 7.19.4
Category: proxy auth
+Example: --socks5-gssapi-nec --socks5 hostname:4096 $URL
---
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
diff --git a/docs/cmdline-opts/socks5-gssapi-service.d b/docs/cmdline-opts/socks5-gssapi-service.d
index e61d0f5..451be8e 100644
--- a/docs/cmdline-opts/socks5-gssapi-service.d
+++ b/docs/cmdline-opts/socks5-gssapi-service.d
@@ -3,6 +3,7 @@
Help: SOCKS5 proxy service name for GSS-API
Added: 7.19.4
Category: proxy auth
+Example: --socks5-gssapi-service sockd --socks5 hostname:4096 $URL
---
The default service name for a socks server is rcmd/server-fqdn. This option
allows you to change it.
diff --git a/docs/cmdline-opts/socks5-gssapi.d b/docs/cmdline-opts/socks5-gssapi.d
index 72ae7ae..2ce8069 100644
--- a/docs/cmdline-opts/socks5-gssapi.d
+++ b/docs/cmdline-opts/socks5-gssapi.d
@@ -2,6 +2,7 @@
Help: Enable GSS-API auth for SOCKS5 proxies
Added: 7.55.0
Category: proxy auth
+Example: --socks5-gssapi --socks5 hostname:4096 $URL
---
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
diff --git a/docs/cmdline-opts/socks5-hostname.d b/docs/cmdline-opts/socks5-hostname.d
index 247d766..729a7bf 100644
--- a/docs/cmdline-opts/socks5-hostname.d
+++ b/docs/cmdline-opts/socks5-hostname.d
@@ -3,6 +3,7 @@
Help: SOCKS5 proxy, pass host name to proxy
Added: 7.18.0
Category: proxy
+Example: --socks5-hostname proxy.example:7000 $URL
---
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.
diff --git a/docs/cmdline-opts/socks5.d b/docs/cmdline-opts/socks5.d
index bbe92f0..99c740f 100644
--- a/docs/cmdline-opts/socks5.d
+++ b/docs/cmdline-opts/socks5.d
@@ -3,6 +3,7 @@
Help: SOCKS5 proxy on given host + port
Added: 7.18.0
Category: proxy
+Example: --socks5 proxy.example:7000 $URL
---
Use the specified SOCKS5 proxy - but resolve the host name locally. If the
port number is not specified, it is assumed at port 1080.
diff --git a/docs/cmdline-opts/speed-limit.d b/docs/cmdline-opts/speed-limit.d
index 3f9ad3a..7bf8d5f 100644
--- a/docs/cmdline-opts/speed-limit.d
+++ b/docs/cmdline-opts/speed-limit.d
@@ -3,6 +3,7 @@
Arg: <speed>
Help: Stop transfers slower than this
Category: connection
+Example: --speed-limit 300 --speed-time 10 $URL
---
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 --speed-time and is
diff --git a/docs/cmdline-opts/speed-time.d b/docs/cmdline-opts/speed-time.d
index 81acabe..6095214 100644
--- a/docs/cmdline-opts/speed-time.d
+++ b/docs/cmdline-opts/speed-time.d
@@ -3,6 +3,7 @@
Arg: <seconds>
Help: Trigger 'speed-limit' abort after this time
Category: connection
+Example: --speed-limit 300 --speed-time 10 $URL
---
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
diff --git a/docs/cmdline-opts/ssl-allow-beast.d b/docs/cmdline-opts/ssl-allow-beast.d
index f18fe74..f54cf64 100644
--- a/docs/cmdline-opts/ssl-allow-beast.d
+++ b/docs/cmdline-opts/ssl-allow-beast.d
@@ -2,9 +2,12 @@
Help: Allow security flaw to improve interop
Added: 7.25.0
Category: tls
+Example: --ssl-allow-beast $URL
---
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.
+implementations.
+
+**WARNING**: this option loosens the SSL security, and by using this flag you
+ask for exactly that.
diff --git a/docs/cmdline-opts/ssl-auto-client-cert.d b/docs/cmdline-opts/ssl-auto-client-cert.d
index 16108ae..7581bdf 100644
--- a/docs/cmdline-opts/ssl-auto-client-cert.d
+++ b/docs/cmdline-opts/ssl-auto-client-cert.d
@@ -3,6 +3,7 @@
Added: 7.77.0
See-also: proxy-ssl-auto-client-cert
Category: tls
+Example: --ssl-auto-client-cert $URL
---
Tell libcurl to automatically locate and use a client certificate for
authentication, when requested by the server. This option is only supported
diff --git a/docs/cmdline-opts/ssl-no-revoke.d b/docs/cmdline-opts/ssl-no-revoke.d
index 3b16142..dde77aa 100644
--- a/docs/cmdline-opts/ssl-no-revoke.d
+++ b/docs/cmdline-opts/ssl-no-revoke.d
@@ -2,6 +2,7 @@
Help: Disable cert revocation checks (Schannel)
Added: 7.44.0
Category: tls
+Example: --ssl-no-revoke $URL
---
(Schannel) This option tells curl to disable certificate revocation checks.
WARNING: this option loosens the SSL security, and by using this flag you ask
diff --git a/docs/cmdline-opts/ssl-reqd.d b/docs/cmdline-opts/ssl-reqd.d
index 2e573e3..489be00 100644
--- a/docs/cmdline-opts/ssl-reqd.d
+++ b/docs/cmdline-opts/ssl-reqd.d
@@ -3,6 +3,7 @@
Protocols: FTP IMAP POP3 SMTP
Added: 7.20.0
Category: tls
+Example: --ssl-reqd ftp://example.com
---
Require SSL/TLS for the connection. Terminates the connection if the server
doesn't support SSL/TLS.
diff --git a/docs/cmdline-opts/ssl-revoke-best-effort.d b/docs/cmdline-opts/ssl-revoke-best-effort.d
index af22da4..2db3219 100644
--- a/docs/cmdline-opts/ssl-revoke-best-effort.d
+++ b/docs/cmdline-opts/ssl-revoke-best-effort.d
@@ -2,6 +2,7 @@
Help: Ignore missing/offline cert CRL dist points
Added: 7.70.0
Category: tls
+Example: --ssl-revoke-best-effort $URL
---
(Schannel) This option tells curl to ignore certificate revocation checks when
they failed due to missing/offline distribution points for the revocation check
diff --git a/docs/cmdline-opts/ssl.d b/docs/cmdline-opts/ssl.d
index 39616bc..bc339fa 100644
--- a/docs/cmdline-opts/ssl.d
+++ b/docs/cmdline-opts/ssl.d
@@ -3,6 +3,7 @@
Protocols: FTP IMAP POP3 SMTP
Added: 7.20.0
Category: tls
+Example: --ssl pop3://example.com/
---
Try to use SSL/TLS for the connection. Reverts to a non-secure connection if
the server doesn't support SSL/TLS. See also --ftp-ssl-control and --ssl-reqd
diff --git a/docs/cmdline-opts/sslv2.d b/docs/cmdline-opts/sslv2.d
index f9ee99d..d96a6cc 100644
--- a/docs/cmdline-opts/sslv2.d
+++ b/docs/cmdline-opts/sslv2.d
@@ -8,6 +8,8 @@
See-also: http1.1 http2
Help: Use SSLv2
Category: tls
+Example: --sslv2 $URL
---
-This option previously asked curl to use SSLv2, but starting in curl 7.77.0 this
-instruction is ignored. SSLv2 is widely considered insecure (see RFC 6176).
+This option previously asked curl to use SSLv2, but starting in curl 7.77.0
+this instruction is ignored. SSLv2 is widely considered insecure (see RFC
+6176).
diff --git a/docs/cmdline-opts/sslv3.d b/docs/cmdline-opts/sslv3.d
index e8b2c35..3ee483d 100644
--- a/docs/cmdline-opts/sslv3.d
+++ b/docs/cmdline-opts/sslv3.d
@@ -8,6 +8,7 @@
See-also: http1.1 http2
Help: Use SSLv3
Category: tls
+Example: --sslv3 $URL
---
This option previously asked curl to use SSLv3, but starting in curl 7.77.0
this instruction is ignored. SSLv3 is widely considered insecure (see RFC
diff --git a/docs/cmdline-opts/stderr.d b/docs/cmdline-opts/stderr.d
index 737df63..c0f0efa 100644
--- a/docs/cmdline-opts/stderr.d
+++ b/docs/cmdline-opts/stderr.d
@@ -3,6 +3,7 @@
Help: Where to redirect stderr
See-also: verbose silent
Category: verbose
+Example: --stderr output.txt $URL
---
Redirect all writes to stderr to the specified file instead. If the file name
is a plain '-', it is instead written to stdout.
diff --git a/docs/cmdline-opts/styled-output.d b/docs/cmdline-opts/styled-output.d
index 91d36ec..bf63601 100644
--- a/docs/cmdline-opts/styled-output.d
+++ b/docs/cmdline-opts/styled-output.d
@@ -2,6 +2,7 @@
Help: Enable styled output for HTTP headers
Added: 7.61.0
Category: verbose
+Example: --styled-output -I $URL
---
Enables the automatic use of bold font styles when writing HTTP headers to the
terminal. Use --no-styled-output to switch them off.
diff --git a/docs/cmdline-opts/suppress-connect-headers.d b/docs/cmdline-opts/suppress-connect-headers.d
index b4e2a17..71078e8 100644
--- a/docs/cmdline-opts/suppress-connect-headers.d
+++ b/docs/cmdline-opts/suppress-connect-headers.d
@@ -2,6 +2,7 @@
Help: Suppress proxy CONNECT response headers
See-also: dump-header include proxytunnel
Category: proxy
+Example: --suppress-connect-headers --include -x proxy $URL
---
When --proxytunnel is used and a CONNECT request is made don't output proxy
CONNECT response headers. This option is meant to be used with --dump-header or
diff --git a/docs/cmdline-opts/tcp-fastopen.d b/docs/cmdline-opts/tcp-fastopen.d
index faef499..e7e9d2e 100644
--- a/docs/cmdline-opts/tcp-fastopen.d
+++ b/docs/cmdline-opts/tcp-fastopen.d
@@ -2,5 +2,6 @@
Added: 7.49.0
Help: Use TCP Fast Open
Category: connection
+Example: --tcp-fastopen $URL
---
Enable use of TCP Fast Open (RFC7413).
diff --git a/docs/cmdline-opts/tcp-nodelay.d b/docs/cmdline-opts/tcp-nodelay.d
index 90483d2..97cd30a 100644
--- a/docs/cmdline-opts/tcp-nodelay.d
+++ b/docs/cmdline-opts/tcp-nodelay.d
@@ -2,6 +2,7 @@
Help: Use the TCP_NODELAY option
Added: 7.11.2
Category: connection
+Example: --tcp-nodelay $URL
---
Turn on the TCP_NODELAY option. See the *curl_easy_setopt(3)* man page for
details about this option.
diff --git a/docs/cmdline-opts/telnet-option.d b/docs/cmdline-opts/telnet-option.d
index 789de3e..3475cb5 100644
--- a/docs/cmdline-opts/telnet-option.d
+++ b/docs/cmdline-opts/telnet-option.d
@@ -3,6 +3,7 @@
Arg: <opt=val>
Help: Set telnet option
Category: telnet
+Example: -t TTYPE=vt100 telnet://example.com/
---
Pass options to the telnet protocol. Supported options are:
diff --git a/docs/cmdline-opts/tftp-blksize.d b/docs/cmdline-opts/tftp-blksize.d
index 6e67ed2..3b19e5c 100644
--- a/docs/cmdline-opts/tftp-blksize.d
+++ b/docs/cmdline-opts/tftp-blksize.d
@@ -4,6 +4,7 @@
Protocols: TFTP
Added: 7.20.0
Category: tftp
+Example: --tftp-blksize 1024 tftp://example.com/file
---
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
diff --git a/docs/cmdline-opts/tftp-no-options.d b/docs/cmdline-opts/tftp-no-options.d
index 0233273..9ff334b 100644
--- a/docs/cmdline-opts/tftp-no-options.d
+++ b/docs/cmdline-opts/tftp-no-options.d
@@ -3,6 +3,7 @@
Protocols: TFTP
Added: 7.48.0
Category: tftp
+Example: --tftp-no-options tftp://192.168.0.1/
---
Tells curl not to send TFTP options requests.
diff --git a/docs/cmdline-opts/time-cond.d b/docs/cmdline-opts/time-cond.d
index 0b56c6e..f82f497 100644
--- a/docs/cmdline-opts/time-cond.d
+++ b/docs/cmdline-opts/time-cond.d
@@ -4,6 +4,9 @@
Help: Transfer based on a time condition
Protocols: HTTP FTP
Category: http ftp
+Example: -z "Wed 01 Sep 2021 12:18:00" $URL
+Example: -z "-Wed 01 Sep 2021 12:18:00" $URL
+Example: -z file $URL
---
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
diff --git a/docs/cmdline-opts/tls-max.d b/docs/cmdline-opts/tls-max.d
index 07eb654..54431ac 100644
--- a/docs/cmdline-opts/tls-max.d
+++ b/docs/cmdline-opts/tls-max.d
@@ -7,6 +7,8 @@
See-also: tlsv1.0 tlsv1.1 tlsv1.2 tlsv1.3
Help: Set maximum allowed TLS version
Category: tls
+Example: --tls-max 1.2 $URL
+Example: --tls-max 1.3 --tlsv1.2 $URL
---
VERSION defines maximum supported TLS version. The minimum acceptable version
is set by tlsv1.0, tlsv1.1, tlsv1.2 or tlsv1.3.
diff --git a/docs/cmdline-opts/tls13-ciphers.d b/docs/cmdline-opts/tls13-ciphers.d
index 0df1695..daf1c93 100644
--- a/docs/cmdline-opts/tls13-ciphers.d
+++ b/docs/cmdline-opts/tls13-ciphers.d
@@ -3,6 +3,7 @@
help: TLS 1.3 cipher suites to use
Protocols: TLS
Category: tls
+Example: --tls13-ciphers TLS_AES_128_GCM_SHA256 $URL
---
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
diff --git a/docs/cmdline-opts/tlsauthtype.d b/docs/cmdline-opts/tlsauthtype.d
index 5b283cf..57b6ab8 100644
--- a/docs/cmdline-opts/tlsauthtype.d
+++ b/docs/cmdline-opts/tlsauthtype.d
@@ -3,6 +3,7 @@
Help: TLS authentication type
Added: 7.21.4
Category: tls auth
+Example: --tlsauthtype SRP $URL
---
Set TLS authentication type. Currently, the only supported option is "SRP",
for TLS-SRP (RFC 5054). If --tlsuser and --tlspassword are specified but
diff --git a/docs/cmdline-opts/tlspassword.d b/docs/cmdline-opts/tlspassword.d
index e7e3780..80cf065 100644
--- a/docs/cmdline-opts/tlspassword.d
+++ b/docs/cmdline-opts/tlspassword.d
@@ -3,6 +3,7 @@
Help: TLS password
Added: 7.21.4
Category: tls auth
+Example: --tlspassword pwd --tlsuser user $URL
---
Set password for use with the TLS authentication method specified with
--tlsauthtype. Requires that --tlsuser also be set.
diff --git a/docs/cmdline-opts/tlsuser.d b/docs/cmdline-opts/tlsuser.d
index ada1526..2cfcd95 100644
--- a/docs/cmdline-opts/tlsuser.d
+++ b/docs/cmdline-opts/tlsuser.d
@@ -3,6 +3,7 @@
Help: TLS user name
Added: 7.21.4
Category: tls auth
+Example: --tlspassword pwd --tlsuser user $URL
---
Set username for use with the TLS authentication method specified with
--tlsauthtype. Requires that --tlspassword also is set.
diff --git a/docs/cmdline-opts/tlsv1.0.d b/docs/cmdline-opts/tlsv1.0.d
index 4f0176f..5fc18dc 100644
--- a/docs/cmdline-opts/tlsv1.0.d
+++ b/docs/cmdline-opts/tlsv1.0.d
@@ -3,6 +3,7 @@
Protocols: TLS
Added: 7.34.0
Category: tls
+Example: --tlsv1.0 $URL
---
Forces curl to use TLS version 1.0 or later when connecting to a remote TLS server.
diff --git a/docs/cmdline-opts/tlsv1.1.d b/docs/cmdline-opts/tlsv1.1.d
index b3649f7..6d169bf 100644
--- a/docs/cmdline-opts/tlsv1.1.d
+++ b/docs/cmdline-opts/tlsv1.1.d
@@ -3,6 +3,7 @@
Protocols: TLS
Added: 7.34.0
Category: tls
+Example: --tlsv1.1 $URL
---
Forces curl to use TLS version 1.1 or later when connecting to a remote TLS server.
diff --git a/docs/cmdline-opts/tlsv1.2.d b/docs/cmdline-opts/tlsv1.2.d
index dffbccb..5df843f 100644
--- a/docs/cmdline-opts/tlsv1.2.d
+++ b/docs/cmdline-opts/tlsv1.2.d
@@ -3,6 +3,7 @@
Protocols: TLS
Added: 7.34.0
Category: tls
+Example: --tlsv1.2 $URL
---
Forces curl to use TLS version 1.2 or later when connecting to a remote TLS server.
diff --git a/docs/cmdline-opts/tlsv1.3.d b/docs/cmdline-opts/tlsv1.3.d
index 37d9535..cc9a53b 100644
--- a/docs/cmdline-opts/tlsv1.3.d
+++ b/docs/cmdline-opts/tlsv1.3.d
@@ -3,6 +3,7 @@
Protocols: TLS
Added: 7.52.0
Category: tls
+Example: --tlsv1.3 $URL
---
Forces curl to use TLS version 1.3 or later when connecting to a remote TLS
server.
diff --git a/docs/cmdline-opts/tlsv1.d b/docs/cmdline-opts/tlsv1.d
index d4c0c51..b881c24 100644
--- a/docs/cmdline-opts/tlsv1.d
+++ b/docs/cmdline-opts/tlsv1.d
@@ -8,6 +8,7 @@
See-also: http1.1 http2
Help: Use TLSv1.0 or greater
Category: tls
+Example: --tlsv1 $URL
---
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
diff --git a/docs/cmdline-opts/tr-encoding.d b/docs/cmdline-opts/tr-encoding.d
index ce1d003..7fdf9e0 100644
--- a/docs/cmdline-opts/tr-encoding.d
+++ b/docs/cmdline-opts/tr-encoding.d
@@ -3,6 +3,7 @@
Help: Request compressed transfer encoding
Protocols: HTTP
Category: http
+Example: --tr-encoding $URL
---
Request a compressed Transfer-Encoding response using one of the algorithms
curl supports, and uncompress the data while receiving it.
diff --git a/docs/cmdline-opts/trace-ascii.d b/docs/cmdline-opts/trace-ascii.d
index 461ea6f..89fe588 100644
--- a/docs/cmdline-opts/trace-ascii.d
+++ b/docs/cmdline-opts/trace-ascii.d
@@ -3,6 +3,7 @@
Help: Like --trace, but without hex output
Mutexed: trace verbose
Category: verbose
+Example: --trace-ascii log.txt $URL
---
Enables a full trace dump of all incoming and outgoing data, including
descriptive information, to the given output file. Use "-" as filename to have
diff --git a/docs/cmdline-opts/trace-time.d b/docs/cmdline-opts/trace-time.d
index 81e28e3..083270d 100644
--- a/docs/cmdline-opts/trace-time.d
+++ b/docs/cmdline-opts/trace-time.d
@@ -2,6 +2,7 @@
Help: Add time stamps to trace/verbose output
Added: 7.14.0
Category: verbose
+Example: --trace-time --trace-ascii output $URL
---
Prepends a time stamp to each trace or verbose line that curl displays.
diff --git a/docs/cmdline-opts/trace.d b/docs/cmdline-opts/trace.d
index 5788f99..3e71545 100644
--- a/docs/cmdline-opts/trace.d
+++ b/docs/cmdline-opts/trace.d
@@ -3,6 +3,7 @@
Help: Write a debug trace to FILE
Mutexed: verbose trace-ascii
Category: verbose
+Example: --trace log.txt $URL
---
Enables a full trace dump of all incoming and outgoing data, including
descriptive information, to the given output file. Use "-" as filename to have
diff --git a/docs/cmdline-opts/unix-socket.d b/docs/cmdline-opts/unix-socket.d
index e4ea91d..c526ca6 100644
--- a/docs/cmdline-opts/unix-socket.d
+++ b/docs/cmdline-opts/unix-socket.d
@@ -4,5 +4,6 @@
Added: 7.40.0
Protocols: HTTP
Category: connection
+Example: --unix-socket socket-path $URL
---
Connect through this Unix domain socket, instead of using the network.
diff --git a/docs/cmdline-opts/upload-file.d b/docs/cmdline-opts/upload-file.d
index 63584b7..5cc5628 100644
--- a/docs/cmdline-opts/upload-file.d
+++ b/docs/cmdline-opts/upload-file.d
@@ -3,6 +3,9 @@
Arg: <file>
Help: Transfer local FILE to destination
Category: important upload
+Example: -T file $URL
+Example: -T "img[1-1000].png" ftp://ftp.example.com/
+Example: --upload-file "{file1,file2}" $URL
---
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
@@ -12,21 +15,15 @@
this is used on an HTTP(S) server, the PUT command will be used.
Use the file name "-" (a single dash) to use stdin instead of a given file.
-Alternately, the file name "." (a single period) may be specified instead
-of "-" to use stdin in non-blocking mode to allow reading server output
-while stdin is being uploaded.
+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.
You can specify one --upload-file for each URL on the command line. Each
--upload-file + URL pair specifies what to upload and to where. curl also
supports "globbing" of the --upload-file 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:
-
- curl --upload-file "{file1,file2}" http://www.example.com
-
-or even
-
- curl -T "img[1-1000].png" ftp://ftp.example.com/upload/
+in the URL.
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
diff --git a/docs/cmdline-opts/url.d b/docs/cmdline-opts/url.d
index 30f0bf7..ed1598a 100644
--- a/docs/cmdline-opts/url.d
+++ b/docs/cmdline-opts/url.d
@@ -2,6 +2,7 @@
Arg: <url>
Help: URL to work with
Category: curl
+Example: --url $URL
---
Specify a URL to fetch. This option is mostly handy when you want to specify
URL(s) in a config file.
@@ -15,5 +16,5 @@
This option may be used any number of times. To control where this URL is
written, use the --output or the --remote-name options.
-Warning: On Windows, particular file:// accesses can be converted to network
-accesses by the operating system. Beware!
+**WARNING**: On Windows, particular file:// accesses can be converted to
+network accesses by the operating system. Beware!
diff --git a/docs/cmdline-opts/use-ascii.d b/docs/cmdline-opts/use-ascii.d
index 3a5a6a4..79554c7 100644
--- a/docs/cmdline-opts/use-ascii.d
+++ b/docs/cmdline-opts/use-ascii.d
@@ -3,6 +3,7 @@
Help: Use ASCII/text transfer
Protocols: FTP LDAP
Category: misc
+Example: -B ftp://example.com/README
---
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
diff --git a/docs/cmdline-opts/user-agent.d b/docs/cmdline-opts/user-agent.d
index bcc3ddb..a322d14 100644
--- a/docs/cmdline-opts/user-agent.d
+++ b/docs/cmdline-opts/user-agent.d
@@ -4,6 +4,7 @@
Help: Send User-Agent <name> to server
Protocols: HTTP
Category: important http
+Example: -A "Agent 007" $URL
---
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
diff --git a/docs/cmdline-opts/user.d b/docs/cmdline-opts/user.d
index b588700..6ab3c64 100644
--- a/docs/cmdline-opts/user.d
+++ b/docs/cmdline-opts/user.d
@@ -3,6 +3,7 @@
Arg: <user:password>
Help: Server user and password
Category: important auth
+Example: -u user:secret $URL
---
Specify the user name and password to use for server authentication. Overrides
--netrc and --netrc-optional.
diff --git a/docs/cmdline-opts/verbose.d b/docs/cmdline-opts/verbose.d
index 497eeb6..f040d75 100644
--- a/docs/cmdline-opts/verbose.d
+++ b/docs/cmdline-opts/verbose.d
@@ -4,6 +4,7 @@
Help: Make the operation more talkative
See-also: include
Category: important verbose
+Example: --verbose $URL
---
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"
diff --git a/docs/cmdline-opts/version.d b/docs/cmdline-opts/version.d
index a257ebd..f3c5899 100644
--- a/docs/cmdline-opts/version.d
+++ b/docs/cmdline-opts/version.d
@@ -2,6 +2,7 @@
Short: V
Help: Show version number and quit
Category: important curl
+Example: --version
---
Displays information about curl and the libcurl version it uses.
diff --git a/docs/cmdline-opts/write-out.d b/docs/cmdline-opts/write-out.d
index df50c31..6c74ddc 100644
--- a/docs/cmdline-opts/write-out.d
+++ b/docs/cmdline-opts/write-out.d
@@ -3,6 +3,7 @@
Arg: <format>
Help: Use output FORMAT after completion
Category: verbose
+Example: -w '%{http_code}\\n' $URL
---
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
diff --git a/docs/cmdline-opts/xattr.d b/docs/cmdline-opts/xattr.d
index 4b64c6c..8011b79 100644
--- a/docs/cmdline-opts/xattr.d
+++ b/docs/cmdline-opts/xattr.d
@@ -1,6 +1,7 @@
Long: xattr
Help: Store metadata in extended file attributes
Category: misc
+Example: --xattr -o storage $URL
---
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
