131–140 of 217 posts
It's kind of crazy that we still don't have a standard computer readable way for a program to describe it's argument structure in a computer readable way that could be used for command line autocomplete. E.g. something like an extra section in the binary that describes how arguments are processed.
Earlier quoted context omitted.
Thing is, being able to concatenate options together saves a lot of typing. (And honestly, —long-flags are rarely useful in practice. Unless you have no man page to figure out what the single letter options do.)
> honestly, —long-flags are rarely useful in practice. Unless you have no man page to figure out what the single letter options do I agree for the general case: typing commands in a terminal. But I often use long flags in scripts to improve readability.
These are some pretty good guidelines! Many thanks to the authors for writing them up. Some nitpicks (what would HN be without nitpicks?): > If your command is expecting to have something piped to it and stdin is an interactive terminal, display help immediately and quit. I disagree with this advice: being able to spoon-feed input into a program is extremely useful, and is part of the "conversational" CLI paradigm th…
> Use a command-line argument parsing library where you can.
> ...
> Python: Click, Typer
I would frown upon adding a dependency for such a core feature as argument parsing, unless it brings strong benefits. And even then, I'd recommend to use the standard lib and to switch to the other libs only when necessary.
Why are the font sizes so huge? The computed font size is 30px, compared to 12px for hn.
Earlier quoted context omitted.
If you are already using SSH in a situation where ‘exit’ doesn’t work, it becomes more reasonable to assume the user will know.
I don't understand what you're saying here; could you expand a bit?
> Display output on success, but keep it brief.
Strong disagree. If everything went OK, or something is in progress, I don't need to be notified; it's distracting and makes me instinctively think something has gone wrong and needs my attention. The Art of Unix Programming got it right, "Silence is golden."[1]
I'm disappointed that `git push` is their example of good CLI output, because I've truly hated git's entire CLI design and philosophy for years. Git's CLI is the opposite of what good CLI design should be in almost every way: a noisy, confusing, inconsistent, staggeringly complex misery. Do I really need to know that `git push` is enumerating obects? That it's using delta compression using 8 threads? That it's counting objects? That it's compressing objects? That information is useless plumbing output that clutters and distracts for no purpose. Just do the work and keep quiet, with at most a progress bar for a long-running command--and even then it should be optional.
If people really want chatty output, include an optional --verbose flag, or even levels of verbosity with -v, -vv, -vvv, etc.
> Use symbols and emoji where it makes things clearer.
Please, no. This is a fad right now and it's also really distracting. Symbols and emoji don't have common meanings and a symbol next to a header or plain text is not helpful, because the plain text already says what I need to know without the symbol. Does having an insect icon next to a header that says "Error" really improve clarity, or does a colorful icon in a sea of plain text needlessly distract? Should the icon have been an insect, or a stop sign? Or an exclamation mark in a circle? Or a traffic cone? Couldn't all of those mean "Error"?
Their example of good emoji use includes a red X next to informational--not error--text (leading me to believe that an error occurred or something stopped unexpectedly) and some kind of duck-beak icon next to the text "When the YubiKey blinks, touch it to authorize the login." Huh?
Despite what Unicode wants you to believe, emojis are not "plain text" and translate poorly to professional workstation-based communication. They are difficult to type on a regular keyboard, are tedious to copy and paste, and don't belong in other plain text contexts like data storage or CLI pipes. Additionally emojis render differently for different users so you never truly know what your CLI might be displaying.
[1] https://www.linuxtopia.org/online_books/programming_books/ar...
> Use a command-line argument parsing library where you can. > ... > Python: Click, Typer What's the problem with using the python standard library argparse? I would frown upon adding a dependency for such a core feature as argument parsing, unless it brings strong benefits. And even then, I'd recommend to use the standard lib and to switch to the other libs only when necessary.
Earlier quoted context omitted.
Your CLI should also have a man page, installed in the standard way. IMO, -? or --help should be fairly terse, ideally one screenful or less. More complete documentation should go in the man page. Edit: wrote this before I read "Don’t bother with man pages." Strongly disagree. Relying on web docs leaves your users in the lurch if they are working on a system with no external network.
While I regularly rely on `man` (and would agree with you for systems that have it), I'd also like to add that you should consider people on other systems, as well. I'm still stuck on Windows for work, and e.g. the way Git (at least the Windows version from git-scm.org) handles this is problematic. Something like `git --help` will open the URL to a help page (that also takes ages to load) in the browser. Manpages don…