Support development of well-behaved CLI apps

[jonblack]

CLI applications are expected to behave in a certain way. This is especially important when those applications are used in scripts.

• Exit status should reflect success or failure (see also: Stabilize main with non-() return types rust-lang/rust#48453)
• Correct use of standard out and standard error
• Accept input from standard in (optional)
• Command-line option consistency
• Exit gracefully when a "broken pipe" error occurs
• Enable/disable ANSI color escapes (see also: https://github.com/rust-lang-nursery/cli-wg/issues/15)
• Structured output (log files, json, etc)
• Correctly handles signals (SIGHUP, SIGINT, SIGCHLD, etc)
• Respect hard/soft resource limits (e.g. max open files)

I can always add more from the comments.

[epage]

Someone else brought up consistency in command line flags. These resources might be useful

• http://www.faqs.org/docs/artu/ch10s05.html
• https://www.gnu.org/prep/standards/html_node/Option-Table.html#Option-Table

[BurntSushi]

Another to add to the list:

• CLI tools should exit gracefully when a "broken pipe" error occurs.

[killercup]

Thanks for opening this! One of the goals of this WG should be to have a best-pratice list like this including source code example in Rust :)

[uazu]

Another suggestion:

• It should be possible to enable a log-file friendly output mode where only permitted output is printable text, tab, LF (or CRLF for Windows) plus optionally ANSI colour escapes
• It should be possible to disable use of ANSI colour escapes

The intention is to allow the log-files to be viewed sensibly in a pager or when converted to HTML in a browser.

[killercup]

More advanced/obscure:

• If the tool is meant to be consumed by other tools (instead of/in addition to humans), provide specified, machine readable output (e.g., --message-formate=json which prints one JSON document per line and nothing else to stdout)

[lzybkr]

@killercup - I think structured output will not be obscure in the future.

PowerShell has demonstrated the usefulness of structured output, but that usefulness quickly disappears stepping outside of PowerShell's cmdlets and scripts.

CLI tools are using language specific frameworks more and more which helps a lot with offering UI benefits like common command line parsing, generating command completions. I really hope structured output is one of these future benefits.

ripgrep --vimgrep is one immediate non-shell example where structured output is super useful, I envision a future where there are multiple shells other than PowerShell that would benefit from structured output as well.

[kbknapp]

I have the start of the "book" (I use that term loosely) I started which was meant to going over these exact points. CLI consistency is something I'm very interested in and would like to work on.

If I get some spare time, perhaps I can start this back up and open it up to the community for edits.

The book started as a clap reference, but the more I've thought about it I what I really want to do is sections that are more parser agnostic and goes over building command line applications and best practices such as the ones listed above.

Ultimately I'd like the book to be broken up into three parts:

• Command Line Guidelines/UX (Not necessarily Rust specific)
• Building command line applications in Rust (would focus on Rust centric work, so some parts are specific idiosyncrasy of Rust (println! panicing on a broken pipe, error handling, etc.)
• Using clap (more friendly than the API docs, and more of a reference)

[jonblack]

@kbknapp I like the proposed layout for the book and would love to help out. A lot of what's being proposed I suspect will end up in the first section since they are guidelines. I also think some of these behaviors are optional (e.g. structured output) while others should be politely enforced (e.g. exit status, graceful exit, ansi colors) with a crate or two.

[jonblack]

I found the following quotes about the UNIX philosophy which I think outline our cause, too:

Many UNIX programs do quite trivial things in isolation, but, combined with other programs, become general and useful tools. - Brian Kernighan, 1984

This is the UNIX philosophy: write programs that do one thing and do it well. Write programs to work together. Write programs to handle text streams, because that is a universal interface. - Doug McIllroy, 1978

[jonblack]

I copied the following items from the here: https://www.slideshare.net/bigfishdesign/well-behaved-unix:

• Correctly handle signals (SIGHUP, SIGINT, SIGCHLD)
• Respect hard/soft resource limits (e.g. max open files)

[kalefranz]

I’m a rust n00b, coming from python. So could be a non-issue for rust, but w.r.t. signal handling... a tricky part seems to be correctly passing those signals to subprocesses. Basically making sure users ultimately get the expected behavior from a sent signal even if the primary process has happened to fork a subprocess or three.

[XAMPPRocky]

For some of items mentioned at the top could a utility be built that lints against binaries in general? For example you give it a list of commands, ones that should succeed & fail and check against the status code, read the —help format check that each short option has a long option equivalent, etc.

[Screwtapello]

For more potential suggestions about "well-behaved CLI apps", you could look at the GNU Coding Standards. Highlights include:

• Error messages from compilers should look like this: sourcefile:lineno: message [...] Error messages from other noninteractive programs should look like this: program:sourcefile:lineno: message when there is an appropriate source file, or like this: program: message when there is no relevant source file.
• Please don’t make the behavior of a utility depend on the name used to invoke it. It is useful sometimes to make a link to a utility with a different name, and that should not change what it does.
• Likewise, please don’t make the behavior of a command-line program depend on the type of output device it gets as standard output or standard input. Device independence is an important principle of the system’s design; do not compromise it merely to save someone from typing an option now and then.
• It is usually a good idea for file names given as ordinary arguments to be input files only; any output files would be specified using options (preferably -o or --output).
• Near the end of the --help options output please place lines giving the email address for bug reports [and] the package’s home page
• A big long list of long-option names you can choose from, to make it more likely that users will guess the right options for your program

There's a bunch of other guidance too, some of it more or less specific to GNU projects and/or C projects.

I can't find an equivalent document for OpenBSD or FreeBSD, except that style(9) mentions "Usage statements should look like the manual page's SYNOPSIS."

[luser]

Likewise, please don’t make the behavior of a command-line program depend on the type of output device it gets as standard output or standard input. Device independence is an important principle of the system’s design; do not compromise it merely to save someone from typing an option now and then.

As a counterpoint, I do think detecting a terminal for automatic color output is sensible and widely adopted.

I don't love the GNU standards, but there are certainly some good things in there. Supporting --help and --version has become widely accepted, for example.