]> git.ipfire.org Git - thirdparty/curl.git/commitdiff
curl: help category cleanups master
authorDaniel Stenberg <daniel@haxx.se>
Thu, 30 Jul 2026 11:47:03 +0000 (13:47 +0200)
committerDaniel Stenberg <daniel@haxx.se>
Thu, 30 Jul 2026 14:17:55 +0000 (16:17 +0200)
- add 'mqtt' as a category
- add more protocol categories to several options
- make --data worded better to also cover MQTT

Closes #22447

26 files changed:
docs/cmdline-opts/abstract-unix-socket.md
docs/cmdline-opts/basic.md
docs/cmdline-opts/compressed-ssh.md
docs/cmdline-opts/data.md
docs/cmdline-opts/form-escape.md
docs/cmdline-opts/key.md
docs/cmdline-opts/knownhosts.md
docs/cmdline-opts/max-filesize.md
docs/cmdline-opts/oauth2-bearer.md
docs/cmdline-opts/pass.md
docs/cmdline-opts/proxy-header.md
docs/cmdline-opts/remote-header-name.md
docs/cmdline-opts/sasl-authzid.md
docs/cmdline-opts/sasl-ir.md
docs/cmdline-opts/show-headers.md
docs/cmdline-opts/ssl-reqd.md
docs/cmdline-opts/ssl.md
docs/cmdline-opts/unix-socket.md
docs/cmdline-opts/upload-file.md
docs/cmdline-opts/upload-flags.md
scripts/managen
src/tool_help.c
src/tool_help.h
src/tool_listhelp.c
tests/data/data1461.txt
tests/data/test1462

index b1b6100e1611a274827b64ad8d0a8398e04caa14..40ecce5cf699591ed47459e737292070ee29bc28 100644 (file)
@@ -6,7 +6,7 @@ Arg: <path>
 Help: Connect via abstract Unix domain socket
 Added: 7.53.0
 Protocols: HTTP
-Category: connection
+Category: connection http
 Multi: single
 See-also:
   - unix-socket
index 1c372fbc71386e3360cf4254fbfafdbcc673185f..4285e88a42b98b6a3fe0edb8219e2c30544f879b 100644 (file)
@@ -4,7 +4,7 @@ SPDX-License-Identifier: curl
 Long: basic
 Help: HTTP Basic Authentication
 Protocols: HTTP
-Category: auth
+Category: auth http
 Added: 7.10.6
 Multi: boolean
 See-also:
index 07d3981b484e7a19adcd7bdf805390b8c1a93c93..2c1fda9bdc4eed794afedca1d60264fbe81f626f 100644 (file)
@@ -5,7 +5,7 @@ Long: compressed-ssh
 Help: Enable SSH compression
 Protocols: SCP SFTP
 Added: 7.56.0
-Category: scp ssh
+Category: scp sftp ssh
 Multi: boolean
 See-also:
   - compressed
index d95b023953695dfff2ce04d70c5d1e44d8a0695b..6faaad628dde134b264b99528e9f38b88093afa6 100644 (file)
@@ -4,16 +4,17 @@ SPDX-License-Identifier: curl
 Long: data
 Short: d
 Arg: <data>
-Help: HTTP POST data
+Help: Post data
 Protocols: HTTP MQTT
 Mutexed: form head upload-file
-Category: important http post upload
+Category: important http post upload mqtt
 Added: 4.0
 Multi: append
 See-also:
   - data-binary
   - data-urlencode
   - data-raw
+  - form
 Example:
   - -d "name=curl" $URL
   - -d "name=curl" -d "tool=cmdline" $URL
@@ -22,10 +23,14 @@ Example:
 
 # `--data`
 
-Send the specified data in a POST request to the HTTP server, in the same way
-that a browser does when a user has filled in an HTML form and presses the
-submit button. This option makes curl pass the data to the server using the
-content-type application/x-www-form-urlencoded. Compared to --form.
+Send the specified data to a server.
+
+For HTTP(S), this is done with the POST method in the same way that a browser
+does when a user has filled in an HTML form and presses the submit button.
+This option makes curl pass the data to the server using the content-type
+application/x-www-form-urlencoded.
+
+For MQTT, the data is sent as a PUBLISH.
 
 --data-raw is almost the same but does not have a special interpretation of
 the @ character. To post data purely binary, you should instead use the
index 7cf1cb7403db74e85332c314c3cddc36304aaf2f..d9f4ad4aa16e168cfe075fa0c96e13c56a80d6d9 100644 (file)
@@ -5,7 +5,7 @@ Long: form-escape
 Help: Escape form fields using backslash
 Protocols: HTTP IMAP SMTP
 Added: 7.81.0
-Category: http upload post
+Category: http upload post imap smtp
 Multi: single
 See-also:
   - form
index cc4bc73fa5b32aeee3be0312f5f7c23825cb7055..c0d6f804c412f615c95a2abead30e97090e41d12 100644 (file)
@@ -5,7 +5,7 @@ Long: key
 Arg: <key>
 Protocols: TLS SCP SFTP
 Help: Private key filename
-Category: tls ssh
+Category: tls sftp scp ssh
 Added: 7.9.3
 Multi: single
 See-also:
index 4b6386dd24ec32d2f2da6b75ecb6968825b922ea..cb99fb910ab47f71d3d2508473d962a9d6987283 100644 (file)
@@ -5,7 +5,7 @@ Long: knownhosts
 Arg: <file>
 Protocols: SCP SFTP
 Help: Specify knownhosts path
-Category: ssh
+Category: sftp scp ssh
 Added: 8.17.0
 Multi: single
 See-also:
index 02b2293c56b27bc97bb20d795e55948cd24b790a..a3adcdebf47406d5a1075cc35a09f0f0b1b6b9dc 100644 (file)
@@ -5,7 +5,7 @@ Long: max-filesize
 Arg: <bytes>
 Help: Maximum file size to download
 Protocols: FTP HTTP MQTT
-Category: connection
+Category: connection ftp http mqtt
 Added: 7.10.8
 Multi: single
 See-also:
index b66477fc70c3d1e3a611bb3ccc57a5faa9c2b663..cf260e1b51c7f9f2db618583faca14358b511f5f 100644 (file)
@@ -5,7 +5,7 @@ Long: oauth2-bearer
 Help: OAuth 2 Bearer Token
 Arg: <token>
 Protocols: IMAP LDAP POP3 SMTP HTTP
-Category: auth imap pop3 smtp ldap
+Category: auth imap pop3 smtp ldap http
 Added: 7.33.0
 Multi: single
 See-also:
index 79c2f8738a13bd889f708f4b606f282fe6f7c7c4..39b60ebfd93c5208cbd25fb46fa6007ec45a07f8 100644 (file)
@@ -5,7 +5,7 @@ Long: pass
 Arg: <phrase>
 Help: Passphrase for the private key
 Protocols: TLS SCP SFTP
-Category: ssh tls auth
+Category: tls sftp scp ssh auth
 Added: 7.9.3
 Multi: single
 See-also:
index 459eb462f683cc74667509baa05635b776e79fa9..3cc179657b040f09ace58c0ccc2b400d7a2acd84 100644 (file)
@@ -6,7 +6,7 @@ Arg: <header/@file>
 Help: Pass custom header(s) to proxy
 Protocols: HTTP
 Added: 7.37.0
-Category: proxy
+Category: proxy http
 Multi: append
 See-also:
   - proxy
index 52ae98b01cffbe63a4357604ee20efbf5e17a3df..5faddaa79ad64fd14e5f42fec6c42aaf6ab3f51c 100644 (file)
@@ -5,7 +5,7 @@ Long: remote-header-name
 Short: J
 Protocols: HTTP
 Help: Use the header-provided filename
-Category: output
+Category: output http
 Added: 7.20.0
 Multi: boolean
 See-also:
index 4e92a20541525f240f88b6b25874a48bb2ac6137..4b1338866b4f8c84a223f9708469f69934f8eeda 100644 (file)
@@ -6,7 +6,7 @@ Arg: <identity>
 Help: Identity for SASL PLAIN authentication
 Protocols: LDAP IMAP POP3 SMTP
 Added: 7.66.0
-Category: auth
+Category: auth imap smtp pop3 ldap
 Multi: single
 See-also:
   - login-options
index 206bf29317a82de6d5692835880e48229834e4a5..49f21c1b5b2449e81a76ce713dea63296d77b017 100644 (file)
@@ -5,7 +5,7 @@ Long: sasl-ir
 Help: Initial response in SASL authentication
 Protocols: LDAP IMAP POP3 SMTP
 Added: 7.31.0
-Category: auth
+Category: auth imap pop3 ldap smtp
 Multi: boolean
 See-also:
   - sasl-authzid
index 40c5ae790bec5b62ebc963f77639f674356131b7..7e181246be86f340bc56812726d1a8846d317ac5 100644 (file)
@@ -5,7 +5,7 @@ Long: show-headers
 Short: i
 Help: Show response headers in output
 Protocols: HTTP FTP
-Category: important verbose output
+Category: important verbose output http ftp
 Added: 4.8
 Multi: boolean
 See-also:
index f21c145f599357c6c08dddbd355afb0e488cb4c6..c48209676c7df617723c75cd4bd54ce3638c988e 100644 (file)
@@ -5,7 +5,7 @@ Long: ssl-reqd
 Help: Require SSL/TLS
 Protocols: FTP IMAP POP3 SMTP LDAP
 Added: 7.20.0
-Category: tls imap pop3 smtp ldap
+Category: tls imap pop3 smtp ldap ftp
 Multi: boolean
 See-also:
   - ssl
index b2345858091dee1976dd2386e3c10ca2bea2104b..9461cda4c72d1c96a52d9563f3ff345c824ef372 100644 (file)
@@ -5,7 +5,7 @@ Long: ssl
 Help: Try enabling TLS
 Protocols: FTP IMAP POP3 SMTP LDAP
 Added: 7.20.0
-Category: tls imap pop3 smtp ldap
+Category: tls imap pop3 smtp ldap ftp
 Multi: boolean
 See-also:
   - ssl-reqd
index 34cc714f79df15ae28cc886e861b3bda21278ba0..d448ad07721b63c83a1728ffb23e3025c586fcc5 100644 (file)
@@ -6,7 +6,7 @@ Arg: <path>
 Help: Connect through this Unix domain socket
 Added: 7.40.0
 Protocols: HTTP
-Category: connection
+Category: connection http
 Multi: single
 See-also:
   - abstract-unix-socket
index 1988d8afb728baf83a4f68ad73a8f9df537759d8..030fe96771c9ad725ec229faa025302a7422b650 100644 (file)
@@ -5,7 +5,7 @@ Long: upload-file
 Short: T
 Arg: <file>
 Help: Transfer local FILE to destination
-Category: important upload
+Category: important upload imap
 Added: 4.0
 Multi: per-URL
 See-also:
index 6c014d0895f3955418b768ac6974d3fbacaed8cc..c4321880224e2c5660456d9c7cc0495ceb63c4b8 100644 (file)
@@ -5,7 +5,7 @@ Long: upload-flags
 Arg: <flags>
 Help: IMAP upload behavior
 Protocols: IMAP
-Category: curl output
+Category: curl output imap upload
 Added: 8.13.0
 Multi: single
 See-also:
index 4e21474ea021442de37fb0bc9b202c3f780d8a3c..9eececee9aa2c701c65434539c205a9759f043f0 100755 (executable)
@@ -1127,7 +1127,7 @@ HEAD
                 $bitmask .= ' | ';
             }
         }
-        $bitmask =~ s/(?=.{76}).{1,76}\|/$&\n   /g;
+        $bitmask =~ s/(?=.{75}).{1,75}\|/$&\n   /g;
         my $arg = $arglong{$long};
         if($arg) {
             $opt .= " $arg";
index c9d76d5d2072e779ff555b668a39949245efc9ac..597a6a554d3ff523492d5f902a09f559003ef132 100644 (file)
@@ -51,6 +51,7 @@ static const struct category_descriptors categories[] = {
   { "http", "HTTP and HTTPS protocol", CURLHELP_HTTP },
   { "imap", "IMAP protocol", CURLHELP_IMAP },
   { "ldap", "LDAP protocol", CURLHELP_LDAP },
+  { "mqtt", "MQTT protocol", CURLHELP_MQTT },
   { "output", "File system output", CURLHELP_OUTPUT },
   { "pop3", "POP3 protocol", CURLHELP_POP3 },
   { "post", "HTTP POST specific", CURLHELP_POST },
index 6a2ecdb0622e90fa34dcd01a74aa3354e0bcc670..d8562255d3c7150f1912fa4140d503b539dd8401 100644 (file)
@@ -85,6 +85,7 @@ struct helptxt {
 #define CURLHELP_TLS        (1 << 23)
 #define CURLHELP_UPLOAD     (1 << 24)
 #define CURLHELP_VERBOSE    (1 << 25)
+#define CURLHELP_MQTT       (1 << 26)
 
 #define CURLHELP_ALL        0xfffffffU
 
index 6232fa8b5270ab5da408b47e893110c9789a7575..b6d3ddfd1de9fce7fefb9f5e50ce0c39aaeea7a9 100644 (file)
@@ -36,7 +36,7 @@
 const struct helptxt helptext[] = {
   { "    --abstract-unix-socket <path>",
     "Connect via abstract Unix domain socket",
-    CURLHELP_CONNECTION },
+    CURLHELP_CONNECTION | CURLHELP_HTTP },
   { "    --alt-svc <filename>",
     "Enable alt-svc with this cache file",
     CURLHELP_HTTP },
@@ -51,7 +51,7 @@ const struct helptxt helptext[] = {
     CURLHELP_AUTH | CURLHELP_HTTP },
   { "    --basic",
     "HTTP Basic Authentication",
-    CURLHELP_AUTH },
+    CURLHELP_AUTH | CURLHELP_HTTP },
   { "    --ca-native",
     "Load CA certs from the OS",
     CURLHELP_TLS },
@@ -78,7 +78,7 @@ const struct helptxt helptext[] = {
     CURLHELP_HTTP },
   { "    --compressed-ssh",
     "Enable SSH compression",
-    CURLHELP_SCP | CURLHELP_SSH },
+    CURLHELP_SCP | CURLHELP_SFTP | CURLHELP_SSH },
   { "-K, --config <file>",
     "Read config from a file",
     CURLHELP_CURL },
@@ -113,8 +113,9 @@ const struct helptxt helptext[] = {
     "(EC) TLS key exchange algorithms to request",
     CURLHELP_TLS },
   { "-d, --data <data>",
-    "HTTP POST data",
-    CURLHELP_IMPORTANT | CURLHELP_HTTP | CURLHELP_POST | CURLHELP_UPLOAD },
+    "Post data",
+    CURLHELP_IMPORTANT | CURLHELP_HTTP | CURLHELP_POST | CURLHELP_UPLOAD |
+    CURLHELP_MQTT },
   { "    --data-ascii <data>",
     "HTTP POST ASCII data",
     CURLHELP_HTTP | CURLHELP_POST | CURLHELP_UPLOAD },
@@ -211,7 +212,8 @@ const struct helptxt helptext[] = {
     CURLHELP_SMTP },
   { "    --form-escape",
     "Escape form fields using backslash",
-    CURLHELP_HTTP | CURLHELP_UPLOAD | CURLHELP_POST },
+    CURLHELP_HTTP | CURLHELP_UPLOAD | CURLHELP_POST | CURLHELP_IMAP |
+    CURLHELP_SMTP },
   { "    --form-string <name=string>",
     "Specify multipart MIME data",
     CURLHELP_HTTP | CURLHELP_UPLOAD | CURLHELP_POST | CURLHELP_SMTP |
@@ -360,13 +362,13 @@ const struct helptxt helptext[] = {
     CURLHELP_CONNECTION | CURLHELP_TIMEOUT },
   { "    --key <key>",
     "Private key filename",
-    CURLHELP_TLS | CURLHELP_SSH },
+    CURLHELP_TLS | CURLHELP_SFTP | CURLHELP_SCP | CURLHELP_SSH },
   { "    --key-type <type>",
     "Private key file type (DER/PEM/ENG)",
     CURLHELP_TLS },
   { "    --knownhosts <file>",
     "Specify knownhosts path",
-    CURLHELP_SSH },
+    CURLHELP_SFTP | CURLHELP_SCP | CURLHELP_SSH },
   { "    --krb <level>",
     "Enable Kerberos with security <level>",
     CURLHELP_DEPRECATED },
@@ -409,7 +411,7 @@ const struct helptxt helptext[] = {
     CURLHELP_CURL },
   { "    --max-filesize <bytes>",
     "Maximum file size to download",
-    CURLHELP_CONNECTION },
+    CURLHELP_CONNECTION | CURLHELP_FTP | CURLHELP_HTTP | CURLHELP_MQTT },
   { "    --max-redirs <num>",
     "Maximum number of redirects allowed",
     CURLHELP_HTTP },
@@ -470,7 +472,7 @@ const struct helptxt helptext[] = {
   { "    --oauth2-bearer <token>",
     "OAuth 2 Bearer Token",
     CURLHELP_AUTH | CURLHELP_IMAP | CURLHELP_POP3 | CURLHELP_SMTP |
-    CURLHELP_LDAP },
+    CURLHELP_LDAP | CURLHELP_HTTP },
   { "    --out-null",
     "Discard response data into the void",
     CURLHELP_OUTPUT },
@@ -494,7 +496,8 @@ const struct helptxt helptext[] = {
     CURLHELP_CONNECTION | CURLHELP_CURL | CURLHELP_GLOBAL },
   { "    --pass <phrase>",
     "Passphrase for the private key",
-    CURLHELP_SSH | CURLHELP_TLS | CURLHELP_AUTH },
+    CURLHELP_TLS | CURLHELP_SFTP | CURLHELP_SCP | CURLHELP_SSH |
+    CURLHELP_AUTH },
   { "    --path-as-is",
     "Do not squash .. sequences in URL path",
     CURLHELP_CURL },
@@ -560,7 +563,7 @@ const struct helptxt helptext[] = {
     CURLHELP_PROXY | CURLHELP_TLS },
   { "    --proxy-header <header/@file>",
     "Pass custom header(s) to proxy",
-    CURLHELP_PROXY },
+    CURLHELP_PROXY | CURLHELP_HTTP },
   { "    --proxy-http2",
     "Use HTTP/2 with HTTPS proxy",
     CURLHELP_HTTP | CURLHELP_PROXY },
@@ -644,7 +647,7 @@ const struct helptxt helptext[] = {
     CURLHELP_HTTP },
   { "-J, --remote-header-name",
     "Use the header-provided filename",
-    CURLHELP_OUTPUT },
+    CURLHELP_OUTPUT | CURLHELP_HTTP },
   { "-O, --remote-name",
     "Write output to file named as remote file",
     CURLHELP_IMPORTANT | CURLHELP_OUTPUT },
@@ -684,10 +687,12 @@ const struct helptxt helptext[] = {
     CURLHELP_CURL | CURLHELP_TIMEOUT },
   { "    --sasl-authzid <identity>",
     "Identity for SASL PLAIN authentication",
-    CURLHELP_AUTH },
+    CURLHELP_AUTH | CURLHELP_IMAP | CURLHELP_SMTP | CURLHELP_POP3 |
+    CURLHELP_LDAP },
   { "    --sasl-ir",
     "Initial response in SASL authentication",
-    CURLHELP_AUTH },
+    CURLHELP_AUTH | CURLHELP_IMAP | CURLHELP_POP3 | CURLHELP_LDAP |
+    CURLHELP_SMTP },
   { "    --service-name <name>",
     "SPNEGO service name",
     CURLHELP_AUTH },
@@ -696,7 +701,8 @@ const struct helptxt helptext[] = {
     CURLHELP_CURL | CURLHELP_GLOBAL },
   { "-i, --show-headers",
     "Show response headers in output",
-    CURLHELP_IMPORTANT | CURLHELP_VERBOSE | CURLHELP_OUTPUT },
+    CURLHELP_IMPORTANT | CURLHELP_VERBOSE | CURLHELP_OUTPUT | CURLHELP_HTTP |
+    CURLHELP_FTP },
   { "    --sigalgs <list>",
     "TLS signature algorithms to use",
     CURLHELP_TLS },
@@ -739,7 +745,7 @@ const struct helptxt helptext[] = {
   { "    --ssl",
     "Try enabling TLS",
     CURLHELP_TLS | CURLHELP_IMAP | CURLHELP_POP3 | CURLHELP_SMTP |
-    CURLHELP_LDAP },
+    CURLHELP_LDAP | CURLHELP_FTP },
   { "    --ssl-allow-beast",
     "Allow security flaw to improve interop",
     CURLHELP_TLS },
@@ -752,7 +758,7 @@ const struct helptxt helptext[] = {
   { "    --ssl-reqd",
     "Require SSL/TLS",
     CURLHELP_TLS | CURLHELP_IMAP | CURLHELP_POP3 | CURLHELP_SMTP |
-    CURLHELP_LDAP },
+    CURLHELP_LDAP | CURLHELP_FTP },
   { "    --ssl-revoke-best-effort",
     "Ignore missing cert CRL dist points",
     CURLHELP_TLS },
@@ -845,13 +851,13 @@ const struct helptxt helptext[] = {
     CURLHELP_VERBOSE | CURLHELP_GLOBAL },
   { "    --unix-socket <path>",
     "Connect through this Unix domain socket",
-    CURLHELP_CONNECTION },
+    CURLHELP_CONNECTION | CURLHELP_HTTP },
   { "-T, --upload-file <file>",
     "Transfer local FILE to destination",
-    CURLHELP_IMPORTANT | CURLHELP_UPLOAD },
+    CURLHELP_IMPORTANT | CURLHELP_UPLOAD | CURLHELP_IMAP },
   { "    --upload-flags <flags>",
     "IMAP upload behavior",
-    CURLHELP_CURL | CURLHELP_OUTPUT },
+    CURLHELP_CURL | CURLHELP_OUTPUT | CURLHELP_IMAP | CURLHELP_UPLOAD },
   { "    --url <url/file>",
     "URL(s) to work with",
     CURLHELP_CURL },
index 286be7c344346570d7cf034347f09671378555b6..5ddb4e1edda0c73178da2ca64230f605597c3c7b 100644 (file)
@@ -1,5 +1,5 @@
 Usage: curl [options...] <url>
- -d, --data <data>            HTTP POST data
+ -d, --data <data>            Post data
  -f, --fail                   Fail fast with no output on HTTP errors
  -I, --head                   Show document info only
  -H, --header <header/@file>  Pass custom header(s) to server
@@ -17,7 +17,7 @@ Usage: curl [options...] <url>
 This is not the full help; this menu is split into categories.
 Use "--help category" to get an overview of all categories, which are:
 auth, connection, curl, deprecated, dns, file, ftp, global, http, imap, ldap,%SP
-output, pop3, post, proxy, scp, sftp, smtp, ssh, telnet, tftp, timeout, tls,%SP
-upload, verbose.
+mqtt, output, pop3, post, proxy, scp, sftp, smtp, ssh, telnet, tftp, timeout,%SP
+tls, upload, verbose.
 Use "--help all" to list all options
 Use "--help [option]" to view documentation for a given option
index 9e68c6b447f1ae68270bcd5943ec5fceed87e324..240eca4ab2a64225da60d216c70d2f4c5a9cb03f 100644 (file)
@@ -39,6 +39,7 @@ Unknown category provided, here is a list of all categories:
  http        HTTP and HTTPS protocol
  imap        IMAP protocol
  ldap        LDAP protocol
+ mqtt        MQTT protocol
  output      File system output
  pop3        POP3 protocol
  post        HTTP POST specific