Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Command Line Interface Guidelines

clig.dev

Post reply on HN
Print view View original

31–40 of 55 posts

Re: Command Line Interface Guidelines

#31

Post by oneeyedpigeon »

keithnz wrote: post #9
eikenberry wrote: post #8

> Use a pager (e.g. less) if you are outputting a lot of text. If I wanted to use a pager I'd pipe the output to a pager, no pipe to pager means I want it all dumped to STDOUT. So annoying.

100% - I want to use whatever pager I might prefer at the moment, this advice violates their core principle "you make programs that are modular enough to be recombined as needed"

I find it far more convenient for tools to take options to use a pager, rather than to having to manually type "| less" for every command that I want to behave nicely. Just behave nicely by default; if I want you to behave awkwardly, I'll let you know!

Re: Command Line Interface Guidelines

#32

Post by oneeyedpigeon »

atiedebee wrote: post #26

> The concise help text should only include: > - A description of what your program does. > - One or two example invocations. > - Descriptions of flags, unless there are lots of them. > - An instruction to pass the --help flag for more information. I disagree with this. The first 3 points should all unconditionally be in the man page of the program. In my ideal scenario, the jq short help message would omit everythin…

Yup, I agree. There seems to have been a trend recently to output a LOT on `cmd` (poor), even more on `cmd --help` (unpaged too: bad), and to not have a man page (terrible!). Every program should have a man page, a bare command should give usage (ideally, a single line), and --help should give a decent short overview (ideally less than a screen height or, failing that, automatically paged).

Re: Command Line Interface Guidelines

#34

Post by chriswarbo »

oneeyedpigeon wrote: post #31
keithnz wrote: post #9

Earlier quoted context omitted.

100% - I want to use whatever pager I might prefer at the moment, this advice violates their core principle "you make programs that are modular enough to be recombined as needed"

I find it far more convenient for tools to take options to use a pager, rather than to having to manually type "| less" for every command that I want to behave nicely. Just behave nicely by default; if I want you to behave awkwardly, I'll let you know!

Define "nicely".

For example, many pagers don't work well when stdin is line-buffered (they assume they'll see individual key presses as they happen)

Pagers can also conflict with keys that the terminal emulator is using for a different purpose. This is especially annoying when the terminal emulator is using those keys for pager-like functionality in the first place!

An example of both of these is Emacs `shell-mode`.

(I personally set `PAGER=cat` in my Bash profile, which avoids most of these shenanigans)

Re: Command Line Interface Guidelines

#35

Post by matheusmoreira »

procflora wrote: post #4
kazinator wrote: post #2

> A command is saying too little when it hangs for several minutes and the user starts to wonder if it’s broken. Nope. For debugging the program, it is nice to have some debug tracing option, but if it's not the program's specification to produce output, it should not produce any. If the program's specification is that it produces a certain output after a certain calculation, then it shall not produce any other outpu…

Isn't this basically how more modern "chatty" CLIs use stderr? Put all the nice progress bars and emojis behind `if isatty(2)`? I thought so anyway, but I'll admit I've never actually looked at what npm, uv, etc. do.

That's the right approach. Output goes to standard output, and user facing messages go to standard error. That way output can still be piped or redirected while the program talks to the user, and messages can also be suppressed by redirecting to the null device.

I've always been annoyed by the fact file descriptor 2 is called the "error" stream. Should have been called the "user" stream.

Re: Command Line Interface Guidelines

#36

Post by chriswarbo »

oneeyedpigeon wrote: post #32
atiedebee wrote: post #26

> The concise help text should only include: > - A description of what your program does. > - One or two example invocations. > - Descriptions of flags, unless there are lots of them. > - An instruction to pass the --help flag for more information. I disagree with this. The first 3 points should all unconditionally be in the man page of the program. In my ideal scenario, the jq short help message would omit everythin…

Yup, I agree. There seems to have been a trend recently to output a LOT on `cmd` (poor), even more on `cmd --help` (unpaged too: bad), and to not have a man page (terrible!). Every program should have a man page, a bare command should give usage (ideally, a single line), and --help should give a decent short overview (ideally less than a screen height or, failing that, automatically paged).

The Nix commands have a decent approach: passing `--help` will invoke `man` on the relevant manual (sub-commands tend to have individual man pages).

Re: Command Line Interface Guidelines

#38

Post by user3939382 »

chriswarbo wrote: post #36
oneeyedpigeon wrote: post #32

Earlier quoted context omitted.

Yup, I agree. There seems to have been a trend recently to output a LOT on `cmd` (poor), even more on `cmd --help` (unpaged too: bad), and to not have a man page (terrible!). Every program should have a man page, a bare command should give usage (ideally, a single line), and --help should give a decent short overview (ideally less than a screen height or, failing that, automatically paged).

The Nix commands have a decent approach: passing `--help` will invoke `man` on the relevant manual (sub-commands tend to have individual man pages).

This is my design as well, didn’t realize Nix arrived at it. Help renders the man page.

Re: Command Line Interface Guidelines

#39

Post by jklowden »

Geez, what a lot of vague self-contradictory self-regarding opinionated advice.

Is terminal a world of “pure information’ or “a mess”? Both, it seems. Don’t dump “pages and pages of debug” text? Check. But do use boldface fonts “in a terminal independent way” and “try” to provide man pages. But because “some people” don’t know about them and “some platforms” don’t support them, provide help text by default.

Those “some” by the way are one: Windows. Do please enlighten us on the terminal-independent font control system that includes CMD.EXE.

How much is too much? Their showcase examples are more than 25 lines, more than the default size of a terminal window. The authors don’t give much weight to context, to the ability to look back on over the history of the interactive session. No, much better to splat the screen with 50 lines the user didn’t request, because helpful.

Oh, and don’t write a filter like cat(1). How the system is supposed to distinguish between reading from standard input and reading from standard input by mistake, they don’t say. Just quit and print a help message.

I have different advice: please don’t help. Please be quiet. Don’t suggest, don’t guess, dont offer, don’t assume. Just do. Do what the user said. If he wants something else, he’ll say so in time.

If you want —help to do something useful because you think your user is too dense to find the manual (condescension much?) then invoke it for him. Just maybe put a hint somewhere to press “q” to quit.

Virtually all the “help” I get on the command line is unasked-for and unwanted and unhelpful. If I fat-finger “ls”, I don’t need a suggestion to install lsof. The very last thing I want is 50 lines of noise obscuring what I was looking at before you so helpfully interrupted.

Re: Command Line Interface Guidelines

#40

Post by kps »

Colour addendum: If the user hasn't configured anything, don't use a colour other than red without checking whether the terminal has a light or dark background. Don't hardcode colours.
Post reply on HN