{"id":14601,"date":"2020-09-04T16:27:44","date_gmt":"2020-09-04T14:27:44","guid":{"rendered":"https:\/\/daniel.haxx.se\/blog\/?p=14601"},"modified":"2020-09-04T16:27:44","modified_gmt":"2020-09-04T14:27:44","slug":"curl-help-remodeled","status":"publish","type":"post","link":"https:\/\/daniel.haxx.se\/blog\/2020\/09\/04\/curl-help-remodeled\/","title":{"rendered":"curl help remodeled"},"content":{"rendered":"\n

curl 4.8 was released in 1998 and contained 46 command line options. curl --help<\/code> would list them all. A decent set of options.<\/p>\n\n\n\n

When we released curl 7.72.0<\/a> a few weeks ago, it contained 232 options… and curl --help<\/code> still listed all available options.<\/p>\n\n\n\n

What was once a long list of options grew over the decades into a crazy long wall of text shock to users who would enter this command and option, thinking they would figure out what command line options to try next.<\/p>\n\n\n\n

–help me if you can<\/h2>\n\n\n\n

We’ve known about this usability flaw for a while but it took us some time to figure out how to approach it and decide what the best next step would be. Until this year when long time curl veteran Dan Fandrich did his presentation at curl up 2020 titled –help me if you can<\/a>.<\/p>\n\n\n\n

Emil Engler subsequently picked up the challenge and converted ideas surfaced by Dan into reality and proper code. Today we merged the refreshed and improved --help<\/code> behavior in curl.<\/p>\n\n\n\n

Perhaps the most notable change in curl for many users in a long time. Targeted for inclusion in the pending 7.73.0 release.<\/p>\n\n\n\n

help categories<\/h2>\n\n\n\n

First out, curl --help<\/code> will now by default only list a small subset of the most “important” and frequently used options. No massive wall, no shock. Not even necessary to pipe to more<\/code> or less<\/code> to see proper.<\/p>\n\n\n\n

Then: each curl command line option now has one or more categories, and the help system can be asked to just show command line options belonging to the particular category that you’re interested in.<\/p>\n\n\n\n

For example, let’s imagine you’re interested in seeing what curl options provide for your HTTP operations:<\/p>\n\n\n\n

$ curl --help http\nUsage: curl [options\u2026]\nhttp: HTTP and HTTPS protocol options\n--alt-svc Enable alt-svc with this cache file\n--anyauth Pick any authentication method\n--compressed Request compressed response\n-b, --cookie Send cookies from string\/file\n-c, --cookie-jar Write cookies to after operation\n-d, --data HTTP POST data\n--data-ascii HTTP POST ASCII data\n--data-binary HTTP POST binary data\n--data-raw HTTP POST data, '@' allowed\n--data-urlencode HTTP POST data url encoded\n--digest Use HTTP Digest Authentication\n[...]<\/pre>\n\n\n\n
list categories<\/h2>\n\n\n\n
To figure out what help categories that exists, just ask with curl --help category<\/code>, which will show you a list of the current twenty-two categories: auth, connection, curl, dns, file, ftp, http, imap, misc, output, pop3, post, proxy, scp, sftp, smtp, ssh, telnet ,tftp, tls, upload and verbose.<\/strong> It will also display a brief description of each category.<\/p>\n\n\n\n
Each command line option can be put into multiple categories, so the same one may be displayed in both in the “http” category as well as in “upload” or “auth” etc.<\/p>\n\n\n\n
--help all<\/code><\/h2>\n\n\n\n
You can of course still get the old list of every single command line option by issuing curl --help all<\/code>. Handy for grepping the list and more.<\/p>\n\n\n\n
“important”<\/h2>\n\n\n\n
The meta category “important” is what we use for the options that we show when just curl --help<\/code> is issued. Presumably those options should be the most important, in some ways.<\/p>\n\n\n\n
Credits<\/h2>\n\n\n\n
Code by Emil Engler. Ideas and research by Dan Fandrich.<\/p>\n","protected":false},"excerpt":{"rendered":"
curl 4.8 was released in 1998 and contained 46 command line options. curl –help would list them all. A decent set of options. When we released curl 7.72.0 a few weeks ago, it contained 232 options… and curl –help still listed all available options. What was once a long list of options grew over the … Continue reading curl help remodeled<\/span> →<\/span><\/a><\/p>\n","protected":false},"author":5,"featured_media":13959,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[7],"tags":[214,33,455],"class_list":["post-14601","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-curl","tag-command-line","tag-curl-and-libcurl","tag-documentation"],"_links":{"self":[{"href":"https:\/\/daniel.haxx.se\/blog\/wp-json\/wp\/v2\/posts\/14601","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/daniel.haxx.se\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/daniel.haxx.se\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/daniel.haxx.se\/blog\/wp-json\/wp\/v2\/users\/5"}],"replies":[{"embeddable":true,"href":"https:\/\/daniel.haxx.se\/blog\/wp-json\/wp\/v2\/comments?post=14601"}],"version-history":[{"count":15,"href":"https:\/\/daniel.haxx.se\/blog\/wp-json\/wp\/v2\/posts\/14601\/revisions"}],"predecessor-version":[{"id":14644,"href":"https:\/\/daniel.haxx.se\/blog\/wp-json\/wp\/v2\/posts\/14601\/revisions\/14644"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/daniel.haxx.se\/blog\/wp-json\/wp\/v2\/media\/13959"}],"wp:attachment":[{"href":"https:\/\/daniel.haxx.se\/blog\/wp-json\/wp\/v2\/media?parent=14601"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/daniel.haxx.se\/blog\/wp-json\/wp\/v2\/categories?post=14601"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/daniel.haxx.se\/blog\/wp-json\/wp\/v2\/tags?post=14601"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}