15 ms·

Command line interface guidelines (2021)

• ho_schi 3y ago
  If you wonder about command-line argument parsing with C and C++, getopt() is built-in: https://www.gnu.org/software/libc/manual/html_node/Getopt.html That said. I think CLI programs are user friendly for professionals. Because they support input-process-output. Where input is STDOUT read by human, process is thinking by human and output is keyboard input to STDIN by human. UIs for the general audience? TUIs! TUIs are easily to parse, succinct in organization and fast input - all for humans. Humans can parse TUIs. And they can make up a mental modal. GUIs fail often with a lack of organization, information overflow and distractions by weird metaphors. The Windows 95 desktop metaphor is an example. It doesn’t make sense. Same for Windows 11 and its file-browser which makes it hard to recognize the filesystem or even just the home-directory. Now open Nautilus on Linux, it opens by default your home-directory (in most cases the place to be). I like the CLI but TUIs are my love. GUIs are okay if are like a TUI.
  • deleted 3y ago
    [deleted]
  • unwind 3y ago
    That is only true in some environments, since it's not in fact part of the language specification. See the manual page's [1] "STANDARDS" section, which reads: getopt() POSIX.1-2008. getopt_long() getopt_long_only() GNU. The use of '+' and '-' in optstring is a GNU extension. [1]: https://www.man7.org/linux/man-pages/man3/getopt.3.html https://www.man7.org/linux/man-pages/man3/getopt.3.html
    • ho_schi 3y ago
      Correct. It is probably a feature which isn’t necessary for the languages itself but Linux/POSIX.
  • kergonath 3y ago
    > UIs for the general audience? TUIs! TUIs are easily to parse, succinct in organization and fast input - all for humans. Humans can parse TUIs. And they can make up a mental modal. TUIs have the same drawbacks as GUIs and then some. Their big advantage is to work seamlessly over SSH but that’s pretty much it. They are not more discoverable and they are not more efficient than GUIs. There is nothing preventing you from having a decent GUI along the same lines as Midnight Commander to have a file manager without the metaphors you dislike, for example (as a matter of fact, there are several).
    • Linux-Fan 3y ago
      Working over SSH is not the only TUI advantage: IMHO one of the greatest benefits of TUIs is the usage of characters to display the UI. This way, the font size is always equal (no unreadably small fonts). When designing TUIs I found this to be limiting in a creative sense -- I have to really think about how I arrange the TUI elements and information because I cannot put as many elements as I can on a GUI in the same screen space. Also, TUIs seem to be mostely unaffected by the trend to make every GUI element “touch-friendly” large which is an advantage for me as a Desktop user. Full rant here: <https://masysma.net/37/why_terminal.xhtml https://masysma.net/37/why_terminal.xhtml>
  • IshKebab 3y ago
    getopt is not built in.
  • indymike 3y ago
    > UIs for the general audience? TUIs! TUIs are ideal (sometimes) where a command needs to be interactive. Many commands lend themselves well to batch processing or require no interactivity at all. In many cases, a script piped into a text editor (which is a TUI) is all that is needed, sparing apps from having to embed a text editor and deal with all of the design choices. Other times GUI will work a lot better.
• enriquto 3y ago
  > Most people today don’t know what the command line is, much less why they would want to bother with it. This is true today, and it was true as well "in the 1980s", to use the same time frame as TFA. The difference is that today there are more people than ever who know what the command line is, and who can use it. At least an order of magnitude more people; maybe two. We can certainly say that we live in the CLI golden age!
  • smohare 3y ago
    [dead]
  • nerdponx 3y ago
    Was that true as a % of computer users in the 80s?
    • enriquto 3y ago
      I guess not, but why does it matter? Let people enjoy other things.
  • atoav 3y ago
    Absolute vs relative numbers. If you want to judge the shift in quality in a thing that grew in quantity, then you should look at percentages — otherwise you end up creating statements that are true, but don't say anything meaningful. E.g. there are probably more absolute listeners of Jazz music today than back at the height of the cultural bloom of the genre. But that isn't because Jazz is more popular today than it once was, but because there are more absolute listeners of any kind of music. Would you say that Jazz in the US is now more important, influential etc. than it was at its peak?
    • hiAndrewQuinn 3y ago
      No, but there's so much great jazz these days that wouldn't have existed without those absolute numbers. Quantity (aggregate supply) is a quality (increases specialization of labor) all its own!
• bluetomcat 3y ago
  > Traditionally, UNIX commands were written under the assumption they were going to be used primarily by other programs. They had more in common with functions in a programming language than with graphical applications. Not quite. They were primarily intended for interactive use within a login shell. There are the programs which generate output on stdout (ls, cat, find, tty, who, date), and there are the "silent" text filters (tr, grep, cut, uniq, sort, wc). A one-liner would enable you to do basic computing tasks in that era. Any complex program would be written in C. After the appearance of DSLs like sed and AWK, certain string-heavy programs were offloaded to the shell. The shell is not a sane programming environment and was never intended as such.
  • rollcat 3y ago
    > The shell is not a sane programming environment and was never intended as such. There are 10kloc C programs that could be 10 lines of shell and there are 1kloc shell programs that could've been 100 lines of C. Both kinds are nowadays probably better done in Python or Lua, but the shell and C are what's most universally available.
    • bluetomcat 3y ago
      > There are 10kloc C programs that could be 10 lines of shell Only when the shell calls other external C programs. Ten lines of calling ffmpeg or curl is not shell programming. > there are 1kloc shell programs that could've been 100 lines of C The 1kloc shell programs are fragile spaghetti that breaks in weird ways. Any invocation of an external program can fail for a variety of reasons, and the shell doesn't provide adequate mechanisms for dealing with it, apart from exit codes and filtering error text output.
      • shadowgovt 3y ago
        > Ten lines of calling ffmpeg or curl is not shell programming Ten lines of calling ffmpeg or curl is shell programming in precisely the same sense that 100 lines of C that `#include <sys/socket.h>` are C programming. If your code isn't standing on the shoulders of giants, you're probably wasting everyone's time.
• EasyMark 3y ago
  This document is far to large for "guidelines".
  • shrikant 3y ago
    Whart's this based on? If anything, this is among the more concise set of interface guidelines I've come across. Design guidelines typically run into hundreds of pages long when PDF'ed -- this page is just about thirty on default "Save as PDF" settings...
  • tester457 3y ago
    I thought so too until I ignored the philosophy section.
• ttyprintk 3y ago
  not much has changed since the prior comments: https://news.ycombinator.com/item?id=25304257 https://news.ycombinator.com/item?id=25304257
  • scbrg 3y ago
    Seems they took a small step back from their previous "don't bother with man pages" stance. Now it's "Consider providing man pages." I still find it a rather shocking order of priority, honestly. https://clig.dev/#documentation https://clig.dev/#documentation
    • ttyprintk 3y ago
      Good eye!
• jansan 3y ago
  What I find super irritating is that some terminals will automatically execute a command if you paste it from the clipboard and there is a newline char at the end. IMO command line interfaces should not do this.
  • bloopernova 3y ago
    On macOS, iTerm asks if you try to paste a string with a newline. You can disable it if you find it annoying.
  • riddley 3y ago
    You might try a clipboard manager. Most of these that I've used have an option to strip new lines from anything in the clipboard.
    • eviks 3y ago
      that would break multi-line commands, so not a good option
      • riddley 3y ago
        It just strips off the final one.
  • crlfcrlf 3y ago
    You find it irritating that terminals execute commands when they receive a newline, which is indistinguishable from pressing the enter key? The program is doing exactly as it should. Consider not copying newline characters, and you will solve the problem.
    • crlfcrlf 3y ago
      [dead]
    • mixmastamyk 3y ago
      Bracketed paste has been a thing for twenty years now: https://en.wikipedia.org/wiki/Bracketed-paste https://en.wikipedia.org/wiki/Bracketed-paste Put in .inputrc: https://wiki.archlinux.org/title/Readline#Bracketed_paste https://wiki.archlinux.org/title/Readline#Bracketed_paste
• BobBagwill 3y ago
  [flagged]
  • Cockbrand 3y ago
    I was going to comment in protest - "but the CLI has always been there, and it'll always be..." But then I realized that you're probably right. I'm kinda looking forward to looking back with bewilderment on those decades of doing CLI stuff with remembering all those commands and shell intricacies and whatnot.
    • kjs3 3y ago
      In my vision of the future I see one of my descendants 100 years from now cussing furiously that his AI avatar is borking up his request, and one of the local neckbeards walks up, does an obscure incantation that pops up a command window, types a few lines of text and fixes the problem right up. "Newbs...geeze" he says as he walks away. Maybe the proles will one day be permanently denied the CLI, but even if only as a lowest common denominator administration tool of last resort, I predict there will be a CLI somewhere.
  • marcosdumay 3y ago
    Wake me up when chat becomes deterministic. There is a lot of value on understanding the context and trying to parse what you meant in a mangled command. For the foreseeable future, that value will fall entirely on documentation and search procedures, and chat will keep a steady negative value for actual interaction.
    • BobBagwill 3y ago
      The current shells aren't deterministic either. Everything depends on history, context, environment. Early AI shells will ask for confirmation like "ansible --check" or "terraform plan". Running commands in a disposable virtual environment will inspire confidence. When they are trusted enough, direct execution. Soon after you're able to say "Set up a k8s cluster for me!" you'll decide you don't need k8s anymore, you'll just introduce your AI model to your data-lake and be done. The days of thinking about how many nodes do I need, which immutable linux distro, t5g vs m4.xlarge are almost gone. Read the lyrics to Graham Nash's "Teach Your Children", substituting "model" for "children" as necessary. :-)
• ceving 3y ago
  The current Unix command line situation is on the one hand "incredible useful" and on the other hand "broken by design". Why is it incredible useful? Just imagine how long it would take to write the following in C or Rust: curl -sS https://go.dev/doc/devel/release | html2text | grep -o -P '\bgo\d+\.\d+\.\d+\b' | sort -V | uniq | tail -1 Why is it broken by design? Read this: https://news.ycombinator.com/item?id=29747034 https://news.ycombinator.com/item?id=29747034 The problem: a command line interface must be human readable and machine readable at the same time. There is no canonical way to solve this problem.
  • shadowgovt 3y ago
    > Why is it broken by design? I think your example self-explains why it's broken by design. It's a good example. > a command line interface must be human readable and machine readable at the same time. There is no canonical way to solve this problem. And you know, there could be one. Apple has Human Interface Guidelines to reify the meaning of the visual abstractions in its desktop UI. The problem is that the command line didn't come from people who think like Apple designers; it came from people who think "How can I express what I want using the least code possible, because laziness, impatience, and hubris are virtues?" And they weren't wrong for the time (especially because every byte matters), but the design decisions they made got baked into tooling that can't now be moved. I think at this point we'd have to punt the POSIX toolchain to get something better; it's hard for me to imagine how we'd build discoverable, conceptually-consistent UX atop what we currently have.
    • ceving 3y ago
      I think graphical user interfaces are no high standard. They do not compose. How would you express a loop or a recursion in a graphical user interface?
      • shadowgovt 3y ago
        They are a challenge for composition, often. Great for discoverability though, and that doesn't require graphics, just context. There should be a button I can push in my shell that lets me ask "what does the token at cursor mean," and a button that lets me type a plain language search string that wires down to a contextual search (i.e. I'm in the middle of typing out "grep" I should be able to ask "how do I search folders?"). We didn't have the tools to build this when grep was invented; we have them now.
• pmig 3y ago
  We recently chose cobra[1] to create a cli application. It comes with so many best practices already packaged like autocompletions, help texts etc. etc. [1]: https://github.com/spf13/cobra https://github.com/spf13/cobra
• candiddevmike 3y ago
  I get that some CLIs are absolutely huge and require nesting (like aws), but it really drives me nuts traversing nested CLIs. I'd rather most apps spit out all their options in the help and let me use less to find what I need instead of going into each level and running help.
  • frontalier 3y ago
    isn't that what man(ual) is for?
    • otteromkram 3y ago
      You mean manpage? Yes.
  • wjdp 3y ago
    I find it depends on the number of subcommands and if those subcommands are clear. It's rather useful to have the options whittled down to just the ones you need if you know which subcommand you need but otherwise can be painful. Grepping through a large list of options is also painful, seems ther needs to be a balance here.
    • candiddevmike 3y ago
      No need to grep, just use less and vi commands like forward slash to search through things/move about a long list.
      • hk__2 3y ago
        It’s the task of searching in a long list that’s painful, not the tool to do it.
        • cellularmitosis 3y ago
          But we are comparing the pain of searching vs the pain of having to re-run the help command for each possible subcommand, and parsing through all of that. Much easier to just have one command invocation and search through it. There is a web analogy for this in how people organize FAQs. Some have a list of section links, and you have to click on a section to get the FAQs for that topic. Others just put everything on one giant page. Here's the problem scenario with splitting things up into section pages: You think you see the appropriate section, but then you don't see your concern answered. There are two possibilities: either the organization was counter-intuitive and your concern was answered in one of the other sections, or your concern wasn't answered anywhere. And what's the only way to be sure? Visit every single section page and search through all of them. Much, much less painful to just have it all on one page and search it.
• shadowgovt 3y ago
  Of all the challenges with using CLIs, the one that bites me consistently is capitalization of flags. Really wish we'd standardized on being capital-agnostic (or even demanding lowercase only). ... but we didn't, so now you have to memorize whether recursion is capital or lowercase R, restart is capital or lowercase R, poweroff is capital or lowercase P, etc.
  • thworp 3y ago
    Most utilities I use daily have --long-flags for all of these. Using completion (prferrably https://github.com/unixorn/fzf-zsh-plugin https://github.com/unixorn/fzf-zsh-plugin) you can complete them pretty quickly and without knowing the precise name.
• flykespice 3y ago
  POSIX standard had its own command line interface guide already, didn't it?
  • 0cf8612b2e1e 3y ago
    Doesn’t POSIX comment more on what programs did vs what they should do? More a manual of backwards compatibility. Like, why does tar get to be so special that it takes command line flags with or without leading dashes?
    • Sprocklem 3y ago
      tar isn't a POSIX command, and retains its argument format from before the POSIX CLI guidelines were standardized (as does the POSIX ar command). pax, the POSIX-specified (but rarely implemented/used) equivalent of tar does follow the POSIX CLI guidelines.
  • rascul 3y ago
    Yes. https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1...
• xixixao 3y ago
  These are great. Most frustrating to me is that the basic commands: rm, mv, cp, touch, mkdir do not follow some of the basic guidelines, such as “ask before destructive action”. I have been reimplemting them in Rust for myself to fix this (although a wrapper would have been perhaps better, it’s hard to write it and have the program work in any shell).
  • stephenr 3y ago
    It's pretty easy to have shell aliases for commands like rm, cp, etc to use the "safe" mode (the `-i` option) by default. Writing a replacement utility seems a bit like overkill.
• pimlottc 3y ago
  Please also consider a --dry-run option that gives a preview of what actions would be taken without actually making any changes. This is really helpful for learning a tool and making sure you got complex options and fileglobs correct before committing to potentially irreversible changes.
  • samstave 3y ago
    dry-run should be a pipable | function for any command; > do_thing.py | dry-run -- Think of it as "explain your work, step by step" as one would prompt... also, its a food-for-thought you muppets. --- @jasonjmcghee ; ( $ ) . ( $ ) great justice.
    • deleted 3y ago
      [deleted]
    • jasonjmcghee 3y ago
      How could that work? The script on the left executes first, piping its output to another command won’t prevent that
      • saghm 3y ago
        I think there are ways to detect if stdout is a pipe and operate differently (e.g. by using different defaults for coloring output), but I'm not sure if there are ways to detect what the other side of the pipe is, much less what `dry-run` would actually be expected to be in this case
        • jasonjmcghee 3y ago
          Maybe I’m misunderstanding but sounds like you’re proposing the modifying the command on the left to detect whether it’s piping it’s output (curious how you do that btw sounds pretty cool / useful) But at that point you could just handle —dry-run directly
          • 3y ago
• tester457 3y ago
  > Do not read secrets from environment variables > Secrets should only be accepted via credential files, pipes, AF_UNIX sockets, secret management services, or another IPC mechanism. Which one of these is the most convenient and portable to use? Do you use secret management services for work only, or do you use them in your personal projects too?
  • AlwaysNewb23 3y ago
    A secrets management service would be most convenient. Documentation makes them easy to set up without having to build anything extra yourself. A secrets manager like Doppler (https://Doppler.com https://Doppler.com) or AWS Secrets Manager (https://aws.amazon.com/secrets-manager/ https://aws.amazon.com/secrets-manager/) has the advantage of protecting your secrets in a secure place and the advantage of minimizing exposure of those secrets - even to your own developers. That way, you don't end up with a data breach that could have easily been avoided. These types of leaks can cost companies everything and are becoming way more common.
  • flgstnd 3y ago
    I like it when programs have a way to specify a command to retrieve secrets. mbsync (https://isync.sourceforge.io/mbsync.html https://isync.sourceforge.io/mbsync.html) e.g. has afaik 3 options to provide a password for IMAP authentication: If you don't configure a password, you'll be prompted on execution. You can also put the plain text password in the configuration (impractical if you want to share your configuration). But there is also a configuration option to provide a command to retrieve the password. That way you can delegate the password handling to another program, e.g. a password manager like pass(1) (https://www.passwordstore.org/ https://www.passwordstore.org/) or some interactive graphical prompt.
  • tashian 3y ago
    Hi, I'm one of the authors of CLI Guidelines. See my post https://smallstep.com/blog/command-line-secrets/ https://smallstep.com/blog/command-line-secrets/ for a bit more of a deep dive about using secrets on the command line. Credential files are a good, simple, portable option. Files have permissions already. They don't depend on an external service or a proprietary API. And, if your program accepts a credential file, it will be compatible with systemd credentials. systemd credentials offer more security than an unencrypted credential file. They are encrypted and can be TPM-bound, but they don't require the software using the credential to have native TPM support.
• avgcorrection 3y ago
  The worst part about terminal programs is that they can’t be deprecated. Or I don’t know of a way to do it. Because once you release something someone might immediately put it into a script somewhere instead of running it interactively. Now what do you do? Display a “hint” about the deprecation? Well no one’s gonna read that because it’s a script which is run non-interactively. So you just have to design the UI perfectly on the first try. That’s possible for small tools but what about larger ones? Past a certain point it becomes a truism that do-it-once perfectly without iteration is impossible.
  • fleischhauf 3y ago
    how is this different from some library somewhere?
    • avgcorrection 3y ago
      How is it similar? I get deprecation warnings if I update the library. I can pin the version of the library. A library is something I work with, unlike a terminal program which might be written and forgotten. Then those terminal programs get upgraded on the next system update because hey, you’re supposed to the get latest version right? Terminal programs can do the same (`-v1`) in principle. Few do.
      • samatman 3y ago
        A terminal program is quite easy to pin, though, just do this: - $package-manager install $program - which $program - cp $program ~/my/own/directories - $package-manager uninstall $program done. It won't ever change by accident.
        • avgcorrection 3y ago
          Nice. Then I will not hesitate to break the UI in my upcoming terminal program releases. (... they are quite well designed in my head.)
        • 3y ago
• arrakeen 3y ago
  > Use symbols and emoji where it makes things clearer. for the love of god please don't. the yubikey-agent example provided exemplifies everything i dislike about github READMEs and whimsical user interfaces. on the technical side, symbols and emojis can render inconsistently among terminals, leading to potentially confusing messaging. on the artistic side, personal tolerances towards whimsy and playfulness vary wildly and should only be used very sparingly and ONLY if you know what you're doing (if you have to ask, you probably don't)
  • nerdponx 3y ago
    I like it as an optional feature. Some people enjoy it, some people don't. Turn it off by default, but let users choose.
    • kevindamm 3y ago
      like a --verbosity=cute level, perhaps
  • Linux-Fan 3y ago
    Strongly resonates. The first time I saw the CLI Guidelines I even stopped reading them upon reaching that section. This time I read through the remainder and found it quite OK.
  • samatman 3y ago
    I like it. I like colored terminal output, and emoji are colorful, which helps me rapidly form a gestalt of what's going on. I like syntax highlighting too, and find code quite a bit more difficult to read without it. Not everyone is like that, and that's ok. I don't expect my whims to be catered to, and you shouldn't either.
  • zestyping 3y ago
    I'd be good with the guidelines: 1. Use a vocabulary of at most two emojis in output (e.g. one for success, one for failure). 2. Any information conveyed by an emoji should be redundantly conveyed by text.
• wang_li 3y ago
  If your program detects -? and tells the user to use -h or --help or --long-help or --full-help you should be kicked in the crotch. Just show me the help.
  • rascul 3y ago
    I often show help if an unknown option was given but in the cases I don't I am not going through a list of special cases that I don't even know of to try and determine that someone wants the help text. I've never even seen -? before that I can recall.
    • account42 3y ago
      /? is common for help on Windows and some programs translate that to -? elsewhere or just accept both / and - for their arguments.
  • SAI_Peregrinus 3y ago
    I'd say -h and --help should return 0 & print help to stdout. Any unknown option should return EINVAL and output an error message and help text to stderr.
• eterps 3y ago
  The most comprehensive CLI guidelines in the past have been in this book by Eric Raymond: https://www.goodreads.com/book/show/104745.The_Art_of_UNIX_Programming https://www.goodreads.com/book/show/104745.The_Art_of_UNIX_P... https://www.catb.org/esr/writings/taoup/ https://www.catb.org/esr/writings/taoup/ It has been a while since I read that book, but after skimming through clig.dev I gather opinions have changed over time quite a bit.
  • hiAndrewQuinn 3y ago
    I thought much the same thing when I read CLIG. I'm a big fan of the 17 Unix rules he puts down, though, and I think a lot of really good equilibria exist on the spectrum between the two.
• nmz 3y ago
  There's something I wish command lines would not adopt that is should not be as a CLI flag, and that's --json or --csv. Instead this should be offered as an environment variable that runs through all the commands like IOFORMAT=JSON { cmd1|cmd2|cmd3 } if they support the environment variable, they can all read input in a safe way and behave appropriately, if they don't, then they just print as normal
  • gumby 3y ago
    (BTW sometimes ENV vars are bug removers and sometimes a terrible source of mysterious bugs as well as a possible injection vector.) A good option package should support long options being both command line flags and environment variables. The really good ones support them in init files as well (I'm partial to the JSON-ish HOCON format, though .INI works too). I always spec (later overrides previous settings): - system default (/etc/foo.conf) - user defaults (~/.foo.conf) - local defaults (${CWD}/foo.conf) - user-specified init file (overrides local default) - environment vars (FOO_OUTPUT=JSON) - command line var (--output=json) As well as --no-init and --no-env
    • nmz 3y ago
      I disagree of having programs use env vars, ENV propagates, now every single program has an env var for that single program that you barely use, a good example is LSCOLORS, or nnn, all programs now consume extra memory. Which isn't a lot. but it adds up if every single program decides to use ENV.
      • gumby 3y ago
        I wouldn't worry about memory. As I noted, the propagation value of environment vars can be very handy (make sure the programs are communicating via JSON, from an upstream example) and can also lead to confusing bugs (why is this generating JSON output???)
        • nmz 3y ago
          I don't see the problem, you're just making something explicit what used to be implicit, unix is implicitly tsv, well now its a variable that you can change.
• klodolph 3y ago
  If you have -r / --recursive, I would rather just have -recursive work as the others. POSIX be damned, the double hyphen is just an opportunity to make more mistakes, and the combined -rptgo single-hyphen flags are more opportunities to make mistakes. Let some legacy programs like ls and sync keep their single-hyphen combinations. Most new programs should just accept separate flags, and allow either single or double hyphens. Edit: Yeah, this opinion collects downvotes, doesn’t it? Y’all love it when you accidentally type -recursive instead of --recursive, and it turns out that it means the same thing as -r -e -c -u -s -i -v? That never made any sense to me, for the vast majority of tools out there. It sucks, to be honest.
  • OJFord 3y ago
    I don't like combined single-hyphens for a different reason: sometimes they accept arguments, and it seems strange to me that `-a0` can variously mean `-a 0` and `-a -0`. (I think some insist that argument-having options are long, and short options can only be flags, which sort of solves it, except for the existence of the others which makes it still confusing.) That said, in a script, which is the main time I'd have to read the way someone else has written it anyway, I favour everything being --long --anyway --to-make-it=really-clear. (Though there are a few that are so common I won't insist on, `cut -dX -fY` say.) You must like `find`.
    • klodolph 3y ago
      >I don't like combined single-hyphens for a different reason: sometimes they accept arguments, and it seems strange to me that `-a0` can variously mean `-a 0` and `-a -0`. I think the answer to that is just to stop designing argument parsers that way—if you want -a 0 then maybe -a 0 is acceptable, maybe -a=0 is acceptable, but -a0 should not be. I don’t see how this part is controversial. For the same reason, -all should not be parsed as -a -l -l. >I favour everything being --long --anyway --to-make-it=really-clear. Yeah—I think it would be equally clear to write it like -long -anyway -to-make-it=really-clear, if we decided to make more parsers that worked that way. Some parsers do work that way. >You must like `find`. I have to assume that this is just sarcasm. The `find` command gives you a DSL for writing queries, and for some reason, the tokens in that DSL are option flags starting with -. Bizarre. I don’t think anybody wants to design something like that, and I don’t think there’s really anything to learn from find except maybe “sometimes, for historical reasons, the command-line arguments for standardized tools just plain suck.”
• gumby 3y ago
  > It is assumed that command-line interfaces are the opposite of this—that you have to remember how to do everything. The original Macintosh Human Interface Guidelines, published in 1987, recommend “See-and-point (instead of remember-and-type),” as if you could only choose one or the other. I find that guis have worse discoverability and cli better. It's pretty hard to search for a gui affordance. Plus they are essentially unscriptable.
• OJFord 3y ago
  > If stdout is not an interactive terminal, don’t display any animations. This will stop progress bars turning into Christmas trees in CI log output Never display animations in stdout! I quite liked TFA in general, but I was skimming around looking for where they were going to advise on the difference between stderr & stdout until I saw that and realised they weren't. stderr should be all (not just 'errors') of your logging, informational type stuff, the bits that maybe you might animate (and some people will hate) if tty, etc. stdout should be the useful output - which you may or may not have - regardless of whether tty or not, primarily because an inconsistency like that is just confusing. e.g. echo foo | mysed 's/oo/aa/' | cat # mysed should: # stdout: faa # stderr: mysed version 1 here hello\nfound oo\nprinting aa (or whatever) I don't want to have to fight your tool with grep to get the 'actual' output lines. And I don't want to struggle to debug it because if I remove `| cat` above (as a silly example) it behaves differently than with it.
  • samatman 3y ago
    That's a good rule, pity about the name. If we could go back in time and make it stdin, stdout, and stdext (because UNIX so six letters, but standard_extra, or standard_extended), we might have a prayer of getting people to follow that convention. But it's called stderr, so devs think, quite reasonably, that it should be used for error reporting, and conversely, if it isn't an error, it goes in stdout. But I agree with you that this is the better way to structure a program. You might confuse more people with it, but they'll be able to do more useful things with its output, so that's a win.
    • OJFord 3y ago
      I think if I could go back in time, my fix would be to make stderr the default. i.e. everything written 'out' goes to stderr until you explicitly write it as an output to stdout (or another descriptor/file), the inverse of the current situation. (Ok, sure, I'd probably change the name too!)
    • nerdponx 3y ago
      Powershell has something like 5 or 6 different output streams.
• dang 3y ago
  Related: Command Line Interface Guidelines - https://news.ycombinator.com/item?id=38053692 https://news.ycombinator.com/item?id=38053692 - Oct 2023 (1 comment) Command Line Interface Guidelines - https://news.ycombinator.com/item?id=31651161 https://news.ycombinator.com/item?id=31651161 - June 2022 (1 comment) Command Line Interface Guidelines - https://news.ycombinator.com/item?id=25492119 https://news.ycombinator.com/item?id=25492119 - Dec 2020 (5 comments)
• MichaelMoser123 3y ago
  whatever happened to "Make each program do one thing well. To do a new job, build afresh rather than complicate old programs by adding new 'features'"? now we got lots of mega-cli programs, each one with its own distinct option language. Examples: kubectl, docker, openssl, git - (git got two command line languages: plumbing and porcelain) https://danluu.com/cli-complexity/ https://danluu.com/cli-complexity/ ... ls had 11 command line options in 1979, in 2017 it got 58.
  • numeromancer 3y ago
    We ran so much faster when we didn't have to run with shoes on.
• hiAndrewQuinn 3y ago
  I know it goes without saying for most of us here, but actually being a heavy terminal user yourself is one of the most important things to understand how to design CLIs. It helps a ton to understand the ecosystem you live in, not just your own organism. Example: Something I did a few months back ago for a tiny personal project @ https://github.com/hiAndrewQuinn/finstem https://github.com/hiAndrewQuinn/finstem was implement `--format CSV`, `TSV` and `JSON` flags. I haven't had need for any of these myself, but they exist so any future people who want to use `csvkit`, `awk` and `jq` respectively to wrap around my program have easy ways to do so. That's not stuff I would have had the instincts to do if I wasn't myself a user of all 3 of those programs.
  • hollerith 3y ago
    >being a heavy terminal user . . . is one of the most important things I wish people wouldn't conflate CLIs with terminals. I run (shell) command lines all day, but try hard to avoid terminals / apps that emulate terminals. (To run command lines, I use Emacs, which I never run inside a terminal.)
• egberts1 3y ago
  systemd fails badly with the CLI guideline. My biggest beef is total lack of CLI exit code. Makes it useless for bash programming with systemd utils.
• restalis 3y ago
  "Don’t allow arbitrary abbreviations of subcommands. [...] you allowed them to type any non-ambiguous prefix, like mycmd ins, or even just mycmd i, and have it be an alias for mycmd install. Now you’re stuck: you can’t add any more commands beginning with i, because there are scripts out there that assume i means install." Please avoid the use of short arguments in scripts. It makes the least sense there. The short arguments (along with aliases, abbreviations, and whatnot) are a convenience for human usage, to reduce the amount of manual typing. In scripts you can be explicit with minimal cost (and you also should, considering the ratio of writes vs. reads).
• peterisza 3y ago
  One of my favorite CL use-case is pizza ordering. We had a script for it in college, something like this: # pizza --cheese Ordering... Success. #
  • 3abiton 3y ago
    Before the age of captcha. You'll have to tip your captcha solcer nowadays.