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

41–50 of 55 posts

Re: Command Line Interface Guidelines

#41

Post by jodrellblank »

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…

It's awful UX for a program to know that you used it wrong, to be able to print the help there and then, and instead to tell you off and instruct you to ask politely (with --help). People who think that's okay in CLI world hate that kind of uppity-C3PO-servant behaviour from an LLM.

    $ thing
    usage: -lscekm4urytmvjpq9i8u3o54ernymctpwi8eruymgv
    ah ah ah, , ask nicely for: --help

    $ thing -h
    ERROR! There is no option -h
    What could you possibly want?
    It's a mystery!
    What if -h was rm -rf /  did you even think of that?
    Could have printed actual help here,
    Filling up your screen with text anyway
and then you ask for --help and get five screens starting with "-a initialize line feed motor on electromechanical teletype output device from 1964" and on and on with options nobody uses mixed with the same priority amongst parameters everyone uses.

This is yet another area where GUI programs on Windows 98[1] were better than today's Linux state of the art: pressing F1 opening a separate window with HTML-based help with contents, colours, fonts, text styles, hyperlinks, tables, pictures, an index, a search, is so vastly superior that it's unbelievable[2] that here we are in 2026 and Linux world is still infighting over whether a pager is a sign of weakness and low status, or whether showing help by default is a sign of a low quality programmer, for a problem that was completely solved during the Clinton Administration! (And presumably solved in a similar way earlier by classic MacOS, earlier by Amiga OS, and earlier at Xerox PARC).

Having a single output stream and trying to do everything on it is just bad design. Having the program guess what you want, or a toggle to change between working and being informative, or an environment variable to trigger the toggle, are downstream problems that can never please everybody, to avoid facing the bad design and dealing with it.

[1] https://en.wikipedia.org/wiki/Microsoft_Compiled_HTML_Help

[2] it's completely believable

Re: Command Line Interface Guidelines

#42

Post by jpitz »

simon-b wrote: post #15
jpitz wrote: post #13

Earlier quoted context omitted.

I'm bothered by it because whatever git command that I'm executing will put its output in a pager and when I quit the pager it's not there anymore. I want the output on the screen when I start typing the next command. Oh my God, this is such a frustrating pattern.

This is indeed an annoying, but solvable, less default. You can eg use `export LESS="-XF"` to change behaviour.

That's useful, although I don't know if I will enable it for generally or specifically for git.

Re: Command Line Interface Guidelines

#43

Post by roundabout-host »

yjftsjthsd-h wrote: post #17
ventana wrote: post #12

Earlier quoted context omitted.

This is a common approach, CLI tools often use isatty [1] to check if the output fd is a TTY or not. Try running "git log" for example; if you have many commits, it will page through "less" or $PAGER only if it sees that you're on a real TTY; but if not, it will not. Try this: git log # PAGER undefined; uses less PAGER=/usr/bin/head git log # pages through head, you get 10 lines PAGER= git log # PAGER is empty; does…

Another example, which I find very annoying, is `systemctl status`; when the service has... either enough log lines or wide enough lines, idk, it will helpfully page them. So checking the status of a service randomly may or may not block your terminal. I cannot stress enough that I do not want to have to look at the screen and decide interactively whether or not I need to hit q before I can run another command.

It also annoys me very much, especially horizontally. Wrapped lines are much easier to copy, for example if you want to do a Web search.

Re: Command Line Interface Guidelines

#44

Post by roundabout-host »

jklowden wrote: post #39

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 “so…

Do they really not use the following patterns, which I find quite common?

    cat > file
    cat >> file
But really, if you feel that you're waiting too long, can't you just ^C? Isn't it better to teach people rather than making the programs "helpful" (i.e. sometimes helpful, but more often annoying)?

Re: Command Line Interface Guidelines

#45

Post by roundabout-host »

kps wrote: post #40

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.

If you use the 14 standard colours (the plain old colours minus black and white), shouldn't they be set to something readable in the terminal emulator configuration? Of course, the 256-colour mode should not be used. And how do you check the background?

Re: Command Line Interface Guidelines

#46

Post by roundabout-host »

hankbond wrote: post #5

> Whatever software you’re building, you can be absolutely certain that people will use it in ways you didn’t anticipate. Your software will become a part in a larger system—your only choice is over whether it will be a well-behaved part. good advice

It is, but then why does the "guide" contradict it tens of times?

Re: Command Line Interface Guidelines

#47

Post by roundabout-host » 

    Display output on success, but keep it brief. Traditionally, when nothing is wrong, UNIX commands display no output to the user. This makes sense when they’re being used in scripts, but can make commands appear to be hanging or broken when used by humans. For example, cp will not print anything, even if it takes a long time.
It starts with talking about no indication of success, then switches to no indication of progress. I think they are pretty different.

Also, what kind of "responsive" font sizing does this website have?

Re: Command Line Interface Guidelines

#48

Post by roundabout-host »

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…

Indeed, and the jq example invocation is way too trivial. It is better not to put it there.

Re: Command Line Interface Guidelines

#49

Post by roundabout-host »

jodrellblank wrote: post #41
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…

It's awful UX for a program to know that you used it wrong, to be able to print the help there and then, and instead to tell you off and instruct you to ask politely (with --help). People who think that's okay in CLI world hate that kind of uppity-C3PO-servant behaviour from an LLM. $ thing usage: -lscekm4urytmvjpq9i8u3o54ernymctpwi8eruymgv ah ah ah, , ask nicely for: --help $ thing -h ERROR! There is no option -h Wh…

You are comparing CLIs to GUIs. Anyways, there are GNU/Linux GUIs with the help manual (often still F1), but I would attribute the lack of manuals in some newer GUIs to a general trend against manuals, which can be seen well in Android/iOS apps, where everything has to be "engagement-optimised" and "flow-based" and with lots of blob illustrations, because otherwise people are too lazy to read even a page about how to use the app.

Re: Command Line Interface Guidelines

#50

Post by roundabout-host »

matheusmoreira wrote: post #35
procflora wrote: post #4

Earlier quoted context omitted.

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.

Or the "status" stream (you can still redirect it and it is useful sometimes).
Post reply on HN