From 5eb2f0757ebe9fa0328acc2bdb4df155a40942cf Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 30 Jul 2026 13:47:03 +0200 Subject: [PATCH] curl: help category cleanups - add 'mqtt' as a category - add more protocol categories to several options - make --data worded better to also cover MQTT Closes #22447 --- docs/cmdline-opts/abstract-unix-socket.md | 2 +- docs/cmdline-opts/basic.md | 2 +- docs/cmdline-opts/compressed-ssh.md | 2 +- docs/cmdline-opts/data.md | 17 +++++--- docs/cmdline-opts/form-escape.md | 2 +- docs/cmdline-opts/key.md | 2 +- docs/cmdline-opts/knownhosts.md | 2 +- docs/cmdline-opts/max-filesize.md | 2 +- docs/cmdline-opts/oauth2-bearer.md | 2 +- docs/cmdline-opts/pass.md | 2 +- docs/cmdline-opts/proxy-header.md | 2 +- docs/cmdline-opts/remote-header-name.md | 2 +- docs/cmdline-opts/sasl-authzid.md | 2 +- docs/cmdline-opts/sasl-ir.md | 2 +- docs/cmdline-opts/show-headers.md | 2 +- docs/cmdline-opts/ssl-reqd.md | 2 +- docs/cmdline-opts/ssl.md | 2 +- docs/cmdline-opts/unix-socket.md | 2 +- docs/cmdline-opts/upload-file.md | 2 +- docs/cmdline-opts/upload-flags.md | 2 +- scripts/managen | 2 +- src/tool_help.c | 1 + src/tool_help.h | 1 + src/tool_listhelp.c | 48 +++++++++++++---------- tests/data/data1461.txt | 6 +-- tests/data/test1462 | 1 + 26 files changed, 64 insertions(+), 50 deletions(-) diff --git a/docs/cmdline-opts/abstract-unix-socket.md b/docs/cmdline-opts/abstract-unix-socket.md index b1b6100e16..40ecce5cf6 100644 --- a/docs/cmdline-opts/abstract-unix-socket.md +++ b/docs/cmdline-opts/abstract-unix-socket.md @@ -6,7 +6,7 @@ Arg: Help: Connect via abstract Unix domain socket Added: 7.53.0 Protocols: HTTP -Category: connection +Category: connection http Multi: single See-also: - unix-socket diff --git a/docs/cmdline-opts/basic.md b/docs/cmdline-opts/basic.md index 1c372fbc71..4285e88a42 100644 --- a/docs/cmdline-opts/basic.md +++ b/docs/cmdline-opts/basic.md @@ -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: diff --git a/docs/cmdline-opts/compressed-ssh.md b/docs/cmdline-opts/compressed-ssh.md index 07d3981b48..2c1fda9bdc 100644 --- a/docs/cmdline-opts/compressed-ssh.md +++ b/docs/cmdline-opts/compressed-ssh.md @@ -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 diff --git a/docs/cmdline-opts/data.md b/docs/cmdline-opts/data.md index d95b023953..6faaad628d 100644 --- a/docs/cmdline-opts/data.md +++ b/docs/cmdline-opts/data.md @@ -4,16 +4,17 @@ SPDX-License-Identifier: curl Long: data Short: d Arg: -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 diff --git a/docs/cmdline-opts/form-escape.md b/docs/cmdline-opts/form-escape.md index 7cf1cb7403..d9f4ad4aa1 100644 --- a/docs/cmdline-opts/form-escape.md +++ b/docs/cmdline-opts/form-escape.md @@ -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 diff --git a/docs/cmdline-opts/key.md b/docs/cmdline-opts/key.md index cc4bc73fa5..c0d6f804c4 100644 --- a/docs/cmdline-opts/key.md +++ b/docs/cmdline-opts/key.md @@ -5,7 +5,7 @@ Long: key Arg: Protocols: TLS SCP SFTP Help: Private key filename -Category: tls ssh +Category: tls sftp scp ssh Added: 7.9.3 Multi: single See-also: diff --git a/docs/cmdline-opts/knownhosts.md b/docs/cmdline-opts/knownhosts.md index 4b6386dd24..cb99fb910a 100644 --- a/docs/cmdline-opts/knownhosts.md +++ b/docs/cmdline-opts/knownhosts.md @@ -5,7 +5,7 @@ Long: knownhosts Arg: Protocols: SCP SFTP Help: Specify knownhosts path -Category: ssh +Category: sftp scp ssh Added: 8.17.0 Multi: single See-also: diff --git a/docs/cmdline-opts/max-filesize.md b/docs/cmdline-opts/max-filesize.md index 02b2293c56..a3adcdebf4 100644 --- a/docs/cmdline-opts/max-filesize.md +++ b/docs/cmdline-opts/max-filesize.md @@ -5,7 +5,7 @@ Long: max-filesize Arg: 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: diff --git a/docs/cmdline-opts/oauth2-bearer.md b/docs/cmdline-opts/oauth2-bearer.md index b66477fc70..cf260e1b51 100644 --- a/docs/cmdline-opts/oauth2-bearer.md +++ b/docs/cmdline-opts/oauth2-bearer.md @@ -5,7 +5,7 @@ Long: oauth2-bearer Help: OAuth 2 Bearer Token Arg: 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: diff --git a/docs/cmdline-opts/pass.md b/docs/cmdline-opts/pass.md index 79c2f8738a..39b60ebfd9 100644 --- a/docs/cmdline-opts/pass.md +++ b/docs/cmdline-opts/pass.md @@ -5,7 +5,7 @@ Long: pass Arg: 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: diff --git a/docs/cmdline-opts/proxy-header.md b/docs/cmdline-opts/proxy-header.md index 459eb462f6..3cc179657b 100644 --- a/docs/cmdline-opts/proxy-header.md +++ b/docs/cmdline-opts/proxy-header.md @@ -6,7 +6,7 @@ Arg:
Help: Pass custom header(s) to proxy Protocols: HTTP Added: 7.37.0 -Category: proxy +Category: proxy http Multi: append See-also: - proxy diff --git a/docs/cmdline-opts/remote-header-name.md b/docs/cmdline-opts/remote-header-name.md index 52ae98b01c..5faddaa79a 100644 --- a/docs/cmdline-opts/remote-header-name.md +++ b/docs/cmdline-opts/remote-header-name.md @@ -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: diff --git a/docs/cmdline-opts/sasl-authzid.md b/docs/cmdline-opts/sasl-authzid.md index 4e92a20541..4b1338866b 100644 --- a/docs/cmdline-opts/sasl-authzid.md +++ b/docs/cmdline-opts/sasl-authzid.md @@ -6,7 +6,7 @@ Arg: 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 diff --git a/docs/cmdline-opts/sasl-ir.md b/docs/cmdline-opts/sasl-ir.md index 206bf29317..49f21c1b5b 100644 --- a/docs/cmdline-opts/sasl-ir.md +++ b/docs/cmdline-opts/sasl-ir.md @@ -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 diff --git a/docs/cmdline-opts/show-headers.md b/docs/cmdline-opts/show-headers.md index 40c5ae790b..7e181246be 100644 --- a/docs/cmdline-opts/show-headers.md +++ b/docs/cmdline-opts/show-headers.md @@ -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: diff --git a/docs/cmdline-opts/ssl-reqd.md b/docs/cmdline-opts/ssl-reqd.md index f21c145f59..c48209676c 100644 --- a/docs/cmdline-opts/ssl-reqd.md +++ b/docs/cmdline-opts/ssl-reqd.md @@ -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 diff --git a/docs/cmdline-opts/ssl.md b/docs/cmdline-opts/ssl.md index b234585809..9461cda4c7 100644 --- a/docs/cmdline-opts/ssl.md +++ b/docs/cmdline-opts/ssl.md @@ -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 diff --git a/docs/cmdline-opts/unix-socket.md b/docs/cmdline-opts/unix-socket.md index 34cc714f79..d448ad0772 100644 --- a/docs/cmdline-opts/unix-socket.md +++ b/docs/cmdline-opts/unix-socket.md @@ -6,7 +6,7 @@ Arg: 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 diff --git a/docs/cmdline-opts/upload-file.md b/docs/cmdline-opts/upload-file.md index 1988d8afb7..030fe96771 100644 --- a/docs/cmdline-opts/upload-file.md +++ b/docs/cmdline-opts/upload-file.md @@ -5,7 +5,7 @@ Long: upload-file Short: T Arg: Help: Transfer local FILE to destination -Category: important upload +Category: important upload imap Added: 4.0 Multi: per-URL See-also: diff --git a/docs/cmdline-opts/upload-flags.md b/docs/cmdline-opts/upload-flags.md index 6c014d0895..c432188022 100644 --- a/docs/cmdline-opts/upload-flags.md +++ b/docs/cmdline-opts/upload-flags.md @@ -5,7 +5,7 @@ Long: upload-flags Arg: Help: IMAP upload behavior Protocols: IMAP -Category: curl output +Category: curl output imap upload Added: 8.13.0 Multi: single See-also: diff --git a/scripts/managen b/scripts/managen index 4e21474ea0..9eececee9a 100755 --- a/scripts/managen +++ b/scripts/managen @@ -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"; diff --git a/src/tool_help.c b/src/tool_help.c index c9d76d5d20..597a6a554d 100644 --- a/src/tool_help.c +++ b/src/tool_help.c @@ -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 }, diff --git a/src/tool_help.h b/src/tool_help.h index 6a2ecdb062..d8562255d3 100644 --- a/src/tool_help.h +++ b/src/tool_help.h @@ -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 diff --git a/src/tool_listhelp.c b/src/tool_listhelp.c index 6232fa8b52..b6d3ddfd1d 100644 --- a/src/tool_listhelp.c +++ b/src/tool_listhelp.c @@ -36,7 +36,7 @@ const struct helptxt helptext[] = { { " --abstract-unix-socket ", "Connect via abstract Unix domain socket", - CURLHELP_CONNECTION }, + CURLHELP_CONNECTION | CURLHELP_HTTP }, { " --alt-svc ", "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 ", "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 ", - "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 ", "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 ", "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 ", "Private key filename", - CURLHELP_TLS | CURLHELP_SSH }, + CURLHELP_TLS | CURLHELP_SFTP | CURLHELP_SCP | CURLHELP_SSH }, { " --key-type ", "Private key file type (DER/PEM/ENG)", CURLHELP_TLS }, { " --knownhosts ", "Specify knownhosts path", - CURLHELP_SSH }, + CURLHELP_SFTP | CURLHELP_SCP | CURLHELP_SSH }, { " --krb ", "Enable Kerberos with security ", CURLHELP_DEPRECATED }, @@ -409,7 +411,7 @@ const struct helptxt helptext[] = { CURLHELP_CURL }, { " --max-filesize ", "Maximum file size to download", - CURLHELP_CONNECTION }, + CURLHELP_CONNECTION | CURLHELP_FTP | CURLHELP_HTTP | CURLHELP_MQTT }, { " --max-redirs ", "Maximum number of redirects allowed", CURLHELP_HTTP }, @@ -470,7 +472,7 @@ const struct helptxt helptext[] = { { " --oauth2-bearer ", "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 ", "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
", "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 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 ", "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 ", "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 ", "Connect through this Unix domain socket", - CURLHELP_CONNECTION }, + CURLHELP_CONNECTION | CURLHELP_HTTP }, { "-T, --upload-file ", "Transfer local FILE to destination", - CURLHELP_IMPORTANT | CURLHELP_UPLOAD }, + CURLHELP_IMPORTANT | CURLHELP_UPLOAD | CURLHELP_IMAP }, { " --upload-flags ", "IMAP upload behavior", - CURLHELP_CURL | CURLHELP_OUTPUT }, + CURLHELP_CURL | CURLHELP_OUTPUT | CURLHELP_IMAP | CURLHELP_UPLOAD }, { " --url ", "URL(s) to work with", CURLHELP_CURL }, diff --git a/tests/data/data1461.txt b/tests/data/data1461.txt index 286be7c344..5ddb4e1edd 100644 --- a/tests/data/data1461.txt +++ b/tests/data/data1461.txt @@ -1,5 +1,5 @@ Usage: curl [options...] - -d, --data HTTP POST data + -d, --data Post data -f, --fail Fail fast with no output on HTTP errors -I, --head Show document info only -H, --header
Pass custom header(s) to server @@ -17,7 +17,7 @@ Usage: curl [options...] 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 diff --git a/tests/data/test1462 b/tests/data/test1462 index 9e68c6b447..240eca4ab2 100644 --- a/tests/data/test1462 +++ b/tests/data/test1462 @@ -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 -- 2.47.3