Command Line Interface Guidelines • Hacker News Board

Re: Command Line Interface Guidelines

#21

Post by cookiengineer » Thu, Jul 16, 2026, 4:41 AM UTC

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…

> It would be nice to have an agreed-upon protocol for progress reporting.

That was initially USR1 and USR2 as process signals, well, at least across binutils and coreutils.

I just wish that UNIX architecture or POSIX would have been modernized since then, like with JSONL based process communication or similar things.

In Go I usually end up building my own JSONL protocol to marshal/unmarshal states between long running processes. Wish that could've been a POSIX standard.

Re: Command Line Interface Guidelines

#22

Post by daitangio » Thu, Jul 16, 2026, 5:05 AM UTC

esalman wrote: post #11

I have used click/typer packages to build some python-based CLI programs. It's easy and user-friendly way to build, but the amount of time it takes for python to start the environment followed by the actual program to do anything is annoying.

I use python click too, and it helps me to focus on design before implementing.

I mean before asking AI to implement :)

Re: Command Line Interface Guidelines

#23

Post by hulitu » Thu, Jul 16, 2026, 5:17 AM UTC

inetknght wrote: post #16

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…

Yeah no. If I wanted to use a pager, I'd use a pager. I want the output visible on screen after I exit the pager. If I didn't want it on screen, I'd pipe it to a file and open that in a text editor. That will disappear when I close the file. As a bonus: I can then use grep without having to repeat whatever command I used. Even more importantly: I want the command to behave identically regardless of whether its stdin…

> Try writing a script when the tools themselves change how they behave whether they're running in a script or in a terminal

But we smart coders. We think everything. Remind me later.

Re: Command Line Interface Guidelines

#24

Post by eikenberry » Thu, Jul 16, 2026, 6:25 AM UTC

ventana wrote: post #12

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.

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…

Right. IMO this is bad behavior. I have `pager=cat` in my git config to deal with it there and several other aliases (include --no-pager) for systemd related stuff that do it to.

Re: Command Line Interface Guidelines

#25

Post by ithkuil » Thu, Jul 16, 2026, 6:27 AM UTC

inetknght wrote: post #16

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…

Yeah no. If I wanted to use a pager, I'd use a pager. I want the output visible on screen after I exit the pager. If I didn't want it on screen, I'd pipe it to a file and open that in a text editor. That will disappear when I close the file. As a bonus: I can then use grep without having to repeat whatever command I used. Even more importantly: I want the command to behave identically regardless of whether its stdin…

You make a reasonable point so I don't want to oppose it but just to offer more tricks in case some of you don't know them:

_less_ has a nice "&" command that is like "/" (search) but that filters instead like grep.

You can also pipe to an external command from less

Re: Command Line Interface Guidelines

#26

Post by atiedebee » Thu, Jul 16, 2026, 6:45 AM UTC

> 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 everything after the "Usage" section except for the message to run the command with --help.

Re: Command Line Interface Guidelines

#27

Post by asabla » Thu, Jul 16, 2026, 7:46 AM UTC

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.

It took me way too many years before I set this as a default in my profile files.

The funny thing is. I kept missing this detail every time I read through git. Feels like I was blind to the whole concept of it

Re: Command Line Interface Guidelines

#28

Post by Vingdoloras » Thu, Jul 16, 2026, 8:01 AM UTC

jpitz wrote: post #13

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…

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.

I had the same issue specifically with git, for the same reason. You can configure git to not use a pager by setting core.pager to an empty string.

Re: Command Line Interface Guidelines

#29

Post by mr_mitm » Thu, Jul 16, 2026, 8:36 AM UTC

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…

Maybe the PowerShell folks were onto something when they implemented seven different output streams [1]. But then again most users are utterly confused by this and just dump everything to the information stream when they should be using the output stream, making their code near impossible to reuse in an idiomatic way.

[1] https://learn.microsoft.com/en-us/powershell/module/microsof...

Re: Command Line Interface Guidelines

#30

Post by benrutter » Thu, Jul 16, 2026, 8:55 AM UTC

esalman wrote: post #11

I have used click/typer packages to build some python-based CLI programs. It's easy and user-friendly way to build, but the amount of time it takes for python to start the environment followed by the actual program to do anything is annoying.

Tangent, but anyone who's a fan of Typer, I'd massively recommend Cyclopts! It's essentially the same design, but takes advantage of some of the type features python introduced post Typer being written, to make things a little more consise.

https://cyclopts.readthedocs.io/en/stable/