Earlier quoted context omitted.
Powershell offers this I believe.
NuShell is also attempting this. Both are cross platform. https://github.com/nushell/nushell
Thanks for mentioning this! It looks super interesting, but I hadn't heard of it before.
CLI Guidelines – A guide to help you write better command-line programs
21–30 of 217 posts
Re: CLI Guidelines – A guide to help you write better command-line programs
#22Hello HN! We’re Ben, Aanand, Carl, Eva, and Mark, and we made the Command Line Interface Guidelines. Earlier this year, I was working on the Replicate CLI [0]. I had previously worked on Docker so I had a bunch of accumulated knowledge about what makes a good CLI, but I wanted to make Replicate really good, so I looked for some design guides or best practices. Turns out, nothing substantial had been published since t…
you're not the only ones who care! I've been collecting CLI design thoughts and nodejs utilities for a couple years: https://github.com/sw-yx/cli-cheatsheet/blob/master/README.m... just added yours!
Re: CLI Guidelines – A guide to help you write better command-line programs
#23It'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.
Yea, like, imagine if posix pipes and command-line flags could be typed.
The general problem is that typing for these sorts of systems suck. If it works it's a nice little safety feature, but when the types don't line up it's infuriating. Treating everything as a lowest common denominator makes compatibility trivial.
Re: CLI Guidelines – A guide to help you write better command-line programs
#24> The command line of the past was machine-first
> Traditionally, UNIX commands were written under the assumption they were going to be used primarily by other programs
Is there any real factual basis for these claims? I find them hard to believe, considering the origins of UNIX and the fact that shell was the primary (or even only) user interface for the system, and it was pretty much from day 1 designed as an interactive system (contrasted to the more batch/system oriented mainframes of IBM etc)
Re: CLI Guidelines – A guide to help you write better command-line programs
#25This is a great resource, thanks for the effort. I strongly disagree with the “ Don’t bother with man pages” advice. It’s extremely annoying when tools don’t provide a manpage. The overhead of opening up a browser to reference command is cumbersome and highly annoying. There are tools such as pandoc that make generating manpages from various source formats very easy. Perhaps it is just my grouchy old man syndrome…
Maybe I'm suffering from similar syndrome, but I'm under 30 in human Earth years. However, I very much agree with you and would take it a step further to say that programmatically opening the browser with the help flag is also very unwelcome (I'm looking at you, git >.> )
It is your choice, in Git:
git config --global help.format manRe: CLI Guidelines – A guide to help you write better command-line programs
#26Earlier quoted context omitted.
They're not saying you shouldn't provide command-line help. Just that you should deliver them through a `help` subcommand and/or through a `--help` flag (like `git` does) because people don't find man pages and because man pages don't work on every platform.
Right. I still prefer terse help text from the command line, and more in-depth in the man pages. I find commands with copious -h output and having to pipe that into a pager or using scroll back a far worse UX than just opening up a man page that’s easily searchable / scrollable.
Yea that's reasonable, but there are pros and cons and it's also definitely an opinion :).
I don't see the problem with piping help text through a pager (that's literally all `man` is doing). Alternatively, a tool can use a pager automatically (as `git help ...` does). So `man` isn't required to have a pager. Whether you should use a pager by default is a different argument.
That said, I find pagers annoying because it's hard to switch back and forth between typing a command and the docs. That's way easier to do with scrollback. Although someone in this comment thread also mentioned the `PAGER` env var, and that you can set `PAGER=cat`, which is a good pro-tip. So, TIL.
Still, if you're concerned with command-line ergonomics for a broad audience I think there are more people that either 1) know how to `| less` or 2) prefer or don't care about a pager than people who are gonna automatically just know they can do `PAGER=cat man `.
Plus, there's still the cross-platform argument.
Oh, and OP doesn't mention this, but man pages also complicate install, uninstall, versioning, and having multiple versions of a tool installed simultaneously. Built-in help is obviously just works and is distributed with the standalone binary. To use man pages you have to place additional artifacts on the system and make sure they're managed correctly (e.g., versioned). It's additional complexity with basically zero benefit.
So yea. Seems like, as a rule, their guidance is reasonable. I don't see a lot of benefit to using man pages other than "because that's how it's always been done".
Re: CLI Guidelines – A guide to help you write better command-line programs
#27> The command line of the past was machine-first > Traditionally, UNIX commands were written under the assumption they were going to be used primarily by other programs Is there any real factual basis for these claims? I find them hard to believe, considering the origins of UNIX and the fact that shell was the primary (or even only) user interface for the system, and it was pretty much from day 1 designed as an inter…
I'd say say there's some truth to it, but maybe in an accidental way.
Shell scripts have been part of UNIX since day 1. A lot of early UNIX commands were implemented as scripts, and shell was always intended to be one of the main extension mechanisms for users. Scripting is fundamentally based on the assumption that a script will run various commands, glued together in a user-specified way.
So it's true to say that most early UNIX commands were designed to be useful in a script, which implies that they were designed for use by programs. Maybe not designed _exclusively_ for use by programs, but definitely an important design consideration.
Re: CLI Guidelines – A guide to help you write better command-line programs
#28Earlier quoted context omitted.
Yea, like, imagine if posix pipes and command-line flags could be typed.
Powershell offers this I believe.
That's right. I recently wrote on this topic: https://jmmv.dev/2020/10/powershell-cmdlet-params.html
Re: CLI Guidelines – A guide to help you write better command-line programs
#29Loving this!
As a nit:
> Let the user escape. Make it clear how to get out. (Don’t do what vim does.) If your program hangs on network I/O etc, always make Ctrl-C still work. If it’s a wrapper around program execution where Ctrl-C can’t quit (SSH, tmux, telnet, etc), make it clear how to do that. For example, SSH allows escape sequences with the ~ escape character.
I find it confusing that vim is considered less discoverable here than SSH. In either case, you can find the information in the manual (not ideal, but a baseline). In the case of vim, when you hit ctrl-c it tells you how to leave for real. So far as I'm aware, there's no real way to discover the magic ~ invocations in SSH except resorting to the manual or exhaustively trying every key combo with no evidence that you're on the right track or that there's even a track to be on.
Also, vim is (in part) a wrapper around program execution.
Re: CLI Guidelines – A guide to help you write better command-line programs
#30This is a great resource, thanks for the effort. I strongly disagree with the “ Don’t bother with man pages” advice. It’s extremely annoying when tools don’t provide a manpage. The overhead of opening up a browser to reference command is cumbersome and highly annoying. There are tools such as pandoc that make generating manpages from various source formats very easy. Perhaps it is just my grouchy old man syndrome…
They're not saying you shouldn't provide command-line help. Just that you should deliver them through a `help` subcommand and/or through a `--help` flag (like `git` does) because people don't find man pages and because man pages don't work on every platform.
Man pages improve discoverability. You only find --help contents if you already know which command you want. Man pages are searchable (with `man -k` or `apropos`).
This is most relevant when it's a tool that isn't going to be immediately obvious anyway (if I'm trying to figure out how to do XYZ on heroku, it's not unreasonable to expect me to look at the heroku program I installed), and especially when it's a tool that might be installed by default or installed and forgotten about.