← Commit list

8de37b8cda

Daniel Stenberg

2025-09-15

FAILED Duration: 206s

Subject

cmdline-docs: extended, clarified, refreshed

Binary

No binary (build failed)

Architecture & Compiler Flags

Architecture: x86_64-linux-gnu Compiler: gcc (Ubuntu 11.4.0-1ubuntu1~22.04.3) 11.4.0

—

Build Log

(log yok)

Commit Diff GitHub →

docs/cmdline-opts/abstract-unix-socket.md+3 -3

@@ -16,6 +16,6 @@ Example:

	# `--abstract-unix-socket`

-	Connect through an abstract Unix domain socket, instead of using the network.
-	Note: netstat shows the path of an abstract socket prefixed with `@`, however
-	the \<path\> argument should not have this leading character.
+	Connect to the server through an abstract Unix domain socket, instead of using
+	the network. Note: netstat shows the path of an abstract socket prefixed with
+	`@`, however the \<path\> argument should not have this leading character.

docs/cmdline-opts/compressed-ssh.md+2 -1

@@ -16,4 +16,5 @@ Example:
	# `--compressed-ssh`

	Enable SSH compression. This is a request, not an order; the server may or may
-	not do it.
+	not do it. This allows the data to be sent compressed over the wire, and
+	automatically decompressed in the receiving end, to save bandwidth.

docs/cmdline-opts/disallow-username-in-url.md+3 -0

@@ -16,3 +16,6 @@ Example:

	Exit with error if passed a URL containing a username. Probably most useful
	when the URL is being provided at runtime or similar.
+
+	Accepting and using credentials in a URL is normally considered a security
+	hazard as they are easily leaked that way.

docs/cmdline-opts/engine.md+5 -2

@@ -17,6 +17,9 @@ Example:

	# `--engine`

-	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
+	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
	possibly none) of the engines may be available at runtime.
+
+	The OpenSSL concept "engines" has been superseded by "providers" in OpenSSL 3,
+	and this option should work fine to specify such as well.

docs/cmdline-opts/follow.md+4 -0

@@ -9,6 +9,8 @@ Multi: boolean
	See-also:
	- request
	- location
+	- proto-redir
+	- max-redirs
	Example:
	- -X POST --follow $URL
	---
@@ -23,3 +25,5 @@ status codes 307 or 308, but may be reset to GET for 301, 302 and 303.

	This is subtly different than --location, as that option always set the custom
	method in all subsequent requests independent of response code.
+
+	Restrict which protocols a redirect is accepted to follow with --proto-redir.

docs/cmdline-opts/globoff.md+3 -0

@@ -20,3 +20,6 @@ Switch off the URL globbing function. When you set this option, you can
	specify URLs that contain the letters {}[] without having curl itself
	interpret them. Note that these letters are not normal legal URL contents but
	they should be encoded according to the URI standard.
+
+	curl detects numerical IPv6 addresses when used in URLs and excludes them from
+	the treatment, so they can still be used without having to disable globbing.

docs/cmdline-opts/http2.md+1 -0

@@ -14,6 +14,7 @@ See-also:
	- http1.1
	- http3
	- no-alpn
+	- proxy-http2
	Example:
	- --http2 $URL
	---

docs/cmdline-opts/http3.md+2 -0

@@ -33,3 +33,5 @@ still tries to proceed with an older HTTP version. The fallback performs the
	regular negotiation between HTTP/1 and HTTP/2.

	Use --http3-only for similar functionality without a fallback.
+
+	curl cannot do HTTP/3 over any proxy.

docs/cmdline-opts/junk-session-cookies.md+4 -1

@@ -18,5 +18,8 @@ Example:
	# `--junk-session-cookies`

	When curl is told to read cookies from a given file, this option makes it
-	discard all "session cookies". This has the same effect as if a new session is
+	discard all session cookies. This has the same effect as if a new session is
	started. Typical browsers discard session cookies when they are closed down.
+
+	Session cookies are cookies without a set expiry time. They are meant to only
+	last for "a session".

docs/cmdline-opts/location.md+4 -0

@@ -12,6 +12,8 @@ See-also:
	- resolve
	- alt-svc
	- follow
+	- proto-redir
+	- max-redirs
	Example:
	- -L $URL
	---
@@ -40,3 +42,5 @@ using the dedicated options for that: --post301, --post302 and --post303.

	The method set with --request overrides the method curl would otherwise select
	to use.
+
+	Restrict which protocols a redirect is accepted to follow with --proto-redir.

docs/cmdline-opts/max-redirs.md+5 -3

@@ -10,12 +10,14 @@ Added: 7.5
	Multi: single
	See-also:
	- location
+	- follow
	Example:
	- --max-redirs 3 --location $URL
	---

	# `--max-redirs`

-	Set the maximum number of redirections to follow. When --location is used, to
-	prevent curl from following too many redirects, by default, the limit is
-	set to 50 redirects. Set this option to -1 to make it unlimited.
+	Set the maximum number of redirections to follow. When --location or --follow
+	are used, this option prevents curl from following too many redirects. By
+	default the limit is set to 50 redirects. Set this option to -1 to make it
+	unlimited.

docs/cmdline-opts/proto-redir.md+3 -2

@@ -9,8 +9,9 @@ Category: connection curl
	Multi: single
	See-also:
	- proto
+	- follow
	Example:
-	- --proto-redir =http,https $URL
+	- --proto-redir =http,https --follow $URL
	---

	# `--proto-redir`
@@ -20,7 +21,7 @@ not overridden by this option. See --proto for how protocols are represented.

	Example, allow only HTTP and HTTPS on redirect:

-	curl --proto-redir -all,http,https http://example.com
+	curl --proto-redir -all,http,https --follow http://example.com

	By default curl only allows HTTP, HTTPS, FTP and FTPS on redirects
	(added in 7.65.2). Specifying all or +all enables all protocols on

docs/cmdline-opts/proxy.md+1 -2

@@ -31,8 +31,7 @@ HTTPS proxy support works with the https:// protocol prefix for OpenSSL and
	GnuTLS (added in 7.52.0). It also works for mbedTLS, Rustls, Schannel and
	wolfSSL (added in 7.87.0).

-	Unrecognized and unsupported proxy protocols cause an error (added in 7.52.0).
-	Ancient curl versions ignored unknown schemes and used http:// instead.
+	Unrecognized and unsupported proxy protocol schemes cause an error.

	If the port number is not specified in the proxy string, it is assumed to be
	1080.

docs/cmdline-opts/request.md+6 -5

@@ -10,8 +10,9 @@ Added: 6.0
	Multi: single
	See-also:
	- request-target
+	- follow
	Example:
-	- -X "DELETE" $URL
+	- --request "DELETE" $URL
	- -X NLST ftp://example.com/
	---

@@ -37,10 +38,10 @@ This option only changes the actual word used in the HTTP request, it does not
	alter the way curl behaves. For example if you want to make a proper HEAD
	request, using -X HEAD does not suffice. You need to use the --head option.

-	The method string you set with --request is used for all requests, which
-	if you for example use --location may cause unintended side-effects when curl
-	does not change request method according to the HTTP 30x response codes - and
-	similar.
+	If --location is used, the method string you set with --request is used for
+	all requests, which may cause unintended side-effects when curl does not
+	change request method according to the HTTP 30x response codes - and similar.
+	Consider using --follow instead in combination with --request.

	## FTP
	Specifies a custom FTP command to use instead of LIST when doing file lists

docs/cmdline-opts/retry-connrefused.md+4 -2

@@ -15,5 +15,7 @@ Example:

	# `--retry-connrefused`

-	In addition to the other conditions, consider ECONNREFUSED as a transient
-	error too for --retry. This option is used together with --retry.
+	In addition to the other conditions, also consider ECONNREFUSED as a transient
+	error for --retry. This option is used together with --retry. Normally, a
+	confused connection is not considered a transient error and therefore thus not
+	otherwise trigger a retry.

docs/cmdline-opts/retry.md+8 -5

@@ -9,6 +9,8 @@ Category: curl
	Multi: single
	See-also:
	- retry-max-time
+	- retry-connrefused
+	- retry-delay
	Example:
	- --retry 7 $URL
	---
@@ -16,16 +18,17 @@ Example:
	# `--retry`

	If a transient error is returned when curl tries to perform a transfer, it
-	retries this number of times before giving up. Setting the number to 0
-	makes curl do no retries (which is the default). Transient error means either:
-	a timeout, an FTP 4xx response code or an HTTP 408, 429, 500, 502, 503 or 504
+	retries this number of times before giving up. Setting the number to 0 makes
+	curl do no retries (which is the default). Transient error means either: a
+	timeout, an FTP 4xx response code or an HTTP 408, 429, 500, 502, 503 or 504
	response code.

	When curl is about to retry a transfer, it first waits one second and then for
	all forthcoming retries it doubles the waiting time until it reaches 10
	minutes, which then remains the set fixed delay time between the rest of the
-	retries. By using --retry-delay you disable this exponential backoff algorithm.
-	See also --retry-max-time to limit the total time allowed for retries.
+	retries. By using --retry-delay you disable this exponential backoff
+	algorithm. See also --retry-max-time to limit the total time allowed for
+	retries.

	curl complies with the Retry-After: response header if one was present to know
	when to issue the next retry (added in 7.66.0).

docs/cmdline-opts/sasl-ir.md+3 -1

@@ -14,4 +14,6 @@ Example:

	# `--sasl-ir`

-	Enable initial response in SASL authentication.
+	Enable initial response in SASL authentication. Such an "initial response" is
+	a message sent by the client to the server after the client selects an
+	authentication mechanism.

docs/cmdline-opts/tr-encoding.md+5 -0

@@ -17,3 +17,8 @@ Example:

	Request a compressed Transfer-Encoding response using one of the algorithms
	curl supports, and uncompress the data while receiving it.
+
+	This method was once intended to be the way to do automatic data compression
+	for HTTP but for all practical purposes using Content-Encoding as done with
+	--compressed has superseded transfer encoding. The --tr-encoding option is
+	therefore often not be one you want.

docs/cmdline-opts/trace-ids.md+4 -0

@@ -18,3 +18,7 @@ Example:

	Prepend the transfer and connection identifiers to each trace or verbose line
	that curl displays.
+
+	The identifiers are unique numbers assigned to each connection and transfer to
+	allow a user to better understand which transfer and connection each verbose
+	output line refers to.

docs/cmdline-opts/unix-socket.md+4 -1

@@ -16,4 +16,7 @@ Example:

	# `--unix-socket`

-	Connect through this Unix domain socket, instead of using the network.
+	Connect to the server through this Unix domain socket, instead of using the
+	network.
+
+	To connect to a proxy over Unix domain socket, see --proxy.