"Rules" that terminal programs follow

Additional suggestions:<p>* Respect the user&#x27;s default foreground and background color. Don&#x27;t change them without good reason.<p>* If you use colors, make them legible regardless of what the default background and foreground colors are, and regardless of the terminal&#x27;s color map.<p>* Don&#x27;t use color as the only indication of something. The user&#x27;s terminal might not display it, and it probably won&#x27;t be preserved in copy&amp;paste into notes.<p>* Use emoji only judiciously, if at all. Similar with gratuitous non-ASCII characters. It doesn&#x27;t display everywhere, it doesn&#x27;t paste well everywhere, and emoji can be a bit much when copy&amp;pasted into some notes.<p>* In a scrolling (non-full-screen) stdout-ish output, don&#x27;t delete important information that you showed temporarily. For example, hiding warnings or filenames compiled, to display a green checkmark for done. For another example, clearing the screen of Web app build information (including package security warnings!), to display a message that it&#x27;s running in dev mode, is also not wanted. People might want to see that information, or copy&amp;paste it into notes.<p>* If you went full angry fruit salad with your command line program, because it&#x27;s your baby, and you&#x27;re having fun hamming it up, that&#x27;s fine, but please provide an easy preference setting for people to opt out of that. Your program is probably only one of many things on user&#x27;s workstation display, where other programs might be using color and visuals more meaningfully, so animated throbbing red explosions for the code reformatter is a bit much.

Nice writeup. Since she mentioned how hard it is to learn these conventions, I&#x27;ll plug my preferred reference when thinking about CLIs specifically (rather than TUIs and REPLs) - the Command Line Interface Guidelines <a href="https:&#x2F;&#x2F;clig.dev" rel="nofollow">https:&#x2F;&#x2F;clig.dev</a><p>It does include the blog post&#x27;s rules on exiting on Ctrl-C, accepting `-` for stdin, disabling color in pipes, and much more.

&gt; programs should print “regular” output to stdout and errors to stderr<p>This is really important. I&#x27;d like to expand on this.<p>Standard output is for the data the program was asked to produce, no more and no less. If user asked for some JSON data, standard output should contain that exact JSON object and absolutely nothing else.<p>Standard &quot;error&quot; is actually a misnomer. It should have been called the standard user stream. Anything meant for the user to read on the terminal is supposed to go there. Error messages are of course included in that set but so are status messages and verbose output.<p>This ensures the output of programs can be piped into other programs seamlessly. Non-output data still gets sent to the terminal or redirected somewhere else.<p>Would have been great if programs were able to easily create new terminal-connected file descriptors for specific purposes. They could document those numbers in their manuals just like they document exit codes. Then users would get &quot;ports&quot; for every output. Could cut down on parsing significantly.<p>For compatibility, they could all redirect to either standard output or standard error by default... I think I&#x27;m gonna experiment with this a bit.

Some more notes:<p>- If this is your first time hearing about the readline&#x2F;emacs keybindings like Ctrl-E and Ctrl-W, you&#x27;ll be pleased to know that most macOS input sources use these keybindings. If you&#x27;re on macOS, feel free to try Ctrl-E, Ctrl-W, or Ctrl-U in your browser&#x27;s address bar right now<p>- If you&#x27;re using a command line program that doesn&#x27;t support _any_ line editing (e.g. no readline keybindings, and no other keybindings), you can install the `rlwrap` program and launch the REPL under rlwrap. For example Standard ML of New Jersey has a REPL but no line editing functionality, but you can recover that via `rlwrap smlnj`<p>- &quot;don’t use more than 16 colours&quot; — I would go so far as to say &quot;don&#x27;t use more than 8 colors, or at least make your colors configurable.&quot; Many popular color schemes, including Solaraized and the default Base 16 color scheme, use the &quot;bright&quot; colors to hold various shades of gray. What you think is &quot;bright green&quot; might actually be the same shade of gray that normal text is colored.

Ctrl-D for REPLs always bites me with GHCi. My usual approach to quitting GHCi is:<p>- Press Ctrl-D, like normal<p>- Get confused when nothing happens<p>- Remember that it doesn&#x27;t work in GHCi, so run `:q` instead<p>- Get an error message about &quot;lexical error at character &#x27;\EOT&#x27;&quot;, due to Ctrl-D inserting an invisible char at the start of the input<p>- Try `:q` again, without any invisible prefix<p>- GHCi successfully quits

One that&#x27;s missing is treating ~ as the home directory. This appears to be a shell thing and not a POSIX API thing. For example, this doesn&#x27;t work:<p><pre><code> func main() { if _, err := os.ReadFile(&quot;~&#x2F;.bashrc&quot;); err != nil { log.Fatal(err) } fmt.Println(&quot;ok&quot;) } </code></pre> Meanwhile over in shell land:<p><pre><code> $ echo ~&#x2F;~&#x2F;~ &#x2F;home&#x2F;jrockway&#x2F;~&#x2F;~ </code></pre> The behavior is actually kind of amazing.<p>I mention it because while &quot;yourprogram ~&#x2F;path&#x2F;to&#x2F;file&quot; always works, having a repl that asks for a filename might not work. I&#x27;ve seen a lot of software where this DOES work, so I think it counts as a &quot;most TUI programs do this&quot; thing.

The main reason I enjoy CLIs so much more than GUIs (or eves TUIs sometimes) is that it feels so consistent.<p>There are conventions, but following all the conventions in a CLI is a lot easier than designing a good GUI. So they tend to be higher quality as a result.<p>I spend a lot of time thinking how to bring this property to GUIs, but my best answers are still &quot;lots of effort&quot; or &quot;lower your expectations&quot;.

I’d like to add: Programs should not add files to your home directory and should respect XDG_CONFIG_HOME and friends.

“rule 5.1: Ctrl-W should delete the last word […] I can’t think of any exceptions to this other than text editors but if there are I’d love to hear about them!”<p>mysql(1) only links to editline instead of readline, where Ctrl-W by default deletes everything to the start of the line, not just the last word. It drove me mad in the period where I had to use it; you just see your entire nice query disappear. :-)

I&#x27;d add &quot;long-running processes should reload their configuration on SIGHUP&quot;. :)

Other rules for command line tools:<p>1. Don’t assume a terminal type. Look at `TERM` and use termcap&#x2F;terminfo or a library built atop them for anything beyond line-oriented plain text output, or least assume a plain teletype unless you specifically recognize the user’s terminal type.<p>2. Don’t assume the presence of a terminal at all. Check `isatty()` before doing anything fancy, and be sure to work without a terminal so your tool can be used in pipelines and called by other programs via `exec()`.<p>3. Follow the common conventions in your arguments and output structure. For example, if your tool takes an open-ended set of arguments, support specifying a response file with `@path&#x2F;to&#x2F;file` to avoid argument limits. If your tool supports record-oriented output, support a `-0` argument to `NUL`-separate the output for use with `xargs` in pipelines.<p>4. Use the standard `&lt;sysexits.h&gt;` exit codes. They exist for a reason and they make use of your tool within pipelines and programs more straightforward because they make it easier to trace why a failure occurred.<p>5. Include both in-binary `--help`&#x2F;usage information <i>and</i> a man page. Often a user will just need a quick refresher on argument syntax, which is what the built-in help text is for; the man page should be a comprehensive reference with examples. It should *never* defer to a web page or GNU `info`—it’s fine if those exist too and are pointed out, but they should not be the primary user reference.<p>Lots of Linux-oriented tools have one or more of these failure modes, and behave poorly on real terminals that aren’t VT100 derivatives or are awkward to use in anything but an interactive setting.

One thing I&#x27;m wondering about is what text encoding the program should use to output. I tend to write scripts that output exclusively in UTF-8, but I realise this might not be a given. (And, of course, the user&#x27;s terminal expected encoding setting doesn&#x27;t necessarily mean that files should be written in that encoding.)<p>Presumably, you would ideally output text in whatever encoding is specified by the LANG environment variable, but this seems like something that only comes with full i18n&#x2F;l10n support, since it also specifies the actual language to use.<p>Are there any actual established guidelines on this?

If you are a young sysadmin, take the time to.learn Emacs. Not because Emacs is good (but it is) but because deadline keys are Emacs keys, so once you know Emacs you know shell, MySQL, etc.<p>Play your terminal like a piano . Your livelihood depends on it.

&gt; then the operating system will return an EOF when you press Ctrl-D on an empty line.<p>This is akshully not correct. Control-D makes the read(2) return with the data currently in the input buffer. If there&#x27;s no data in the buffer, that results in a 0-length read, which is how EOF is signaled.<p>Try this: run cat, type foo, press control-D. &quot;foo&quot; will be echoed, without any newline.

Non-interactive programs that emit informational output should <i>only</i> do so to stderr or a log file so that they may be used in a pipe line.

It&#x27;s also important to know which rules are &quot;hard&quot;, i.e. implemented or enforced by the first three (or implemented by the program, but would be a complete nonstarter to break) and which rules are just &quot;conventions&quot;, like the &quot;short options&#x2F;long options&quot; rules in POSIX.<p>In particular, those can change between OSes: On all linuxes, programs already get a pre-parsed array of command line args on start, so parsing and quoting behavior depend on the shell, not individual programs.<p>On Windows, programs get passed the entire command line invocation as a string and have to do the parsing themselves. While all &quot;well-behaved&quot; programs let the libc do this, it&#x27;s perfectly possible for a program to break the rules here.

One thing that I’ve noticed:<p>On UNIX, expanding globs (*.txt) is the shell’s job.<p>On Windows, expanding globs is the program’s job.<p>I used to have a bunch of four-line Python programs to, essentially, run `flac --best --replay-gain *.wav`.

<i>&gt; don’t use more than 16 colours</i><p>We aren&#x27;t in the &#x27;80s. Use true color if you want to, modern terminals should support it (built in Linux tty is a weird outlier that should have supported true color years ago).<p>But that also depends on the context. For example if something implements its own TUI with a lot of elements - it makes more sense to use more colors than the barebones set.<p>Most programs that do care about colors, check what terminal capabilities are before using them.

In the same category of command line program guidelines: <a href="https:&#x2F;&#x2F;clig.dev&#x2F;" rel="nofollow">https:&#x2F;&#x2F;clig.dev&#x2F;</a>

As an addendum to Rule 7, `cd -` takes you to the last opened directory. Or is `cd` considered part of the terminal emulator&#x27;s job, as a built-in?

How did copy-pasting text between programs fit in the initial shell design ? You can&#x27;t paste from a remote tmux to a local one, you can&#x27;t mouse-copy multiple lines from a vim vertical split, etc. Where&#x27;s the terminal clipboard that works across programs ?

I can use Ctrl-A, Ctrl-E, and Ctrl-U in text fields in the lynx browser, but not Ctrl-W.<p>I just checked to see if Ctrl-F and Ctrl-B work, and found that the former kills one word forward and the latter acts like Ctrl-W ought to?

&gt; rule 3: REPLs should quit when you press Ctrl-D on an empty line<p>If memory serves, this behavior depends on the OS. On Windows I believe the norm there is to type &quot;&lt;Ctrl-Z&gt;&lt;Enter&gt;&quot;

What does &quot;cooked&quot; mode mean in the context of this article?

I can&#x27;t be the only one that accidentally closes tabs in my browser when I want to delete a word with Ctrl+W

For forcing colorized output: I personally prefer pipetty (from the colorized-logs package on Debian) to unbuffer, since unbuffer merges stdout and stdin.

Another one that comes in really handy for ssh connections:<p>hit -&gt; [return] ~ .<p>to break a jammed up ssh session. A lot of people don&#x27;t seem to know that one.

Don&#x27;t hardcode readline keybindings.

Some of the rules codify many bad practices, from poor color support to unergonomic keybindings. Given that the support isn&#x27;t universal and breaks in parts anyway, it&#x27;s better to break it competely and use something more ergonomic

See also <i>The Art of Unix Programming</i>: &lt;<a href="http:&#x2F;&#x2F;www.catb.org&#x2F;~esr&#x2F;writings&#x2F;taoup&#x2F;html&#x2F;" rel="nofollow">http:&#x2F;&#x2F;www.catb.org&#x2F;~esr&#x2F;writings&#x2F;taoup&#x2F;html&#x2F;</a>&gt;