diff --git a/content/posts/cli-best-practices.gmi b/content/posts/cli-best-practices.gmi index 2b43101..cb01bc3 100644 --- a/content/posts/cli-best-practices.gmi +++ b/content/posts/cli-best-practices.gmi @@ -2,6 +2,8 @@ This began as a reply to another article by Lucas F. Costa; it lists practices t => https://lucasfcosta.com/2022/06/01/ux-patterns-cli-tools.html Lucas' article +This is a "living article" that I plan on adding to indefinitely. If you like it, come back in a month or two and check the "changelog" link in the article header. + Note: this article specifically concerns CLIs, not full-blown textual user interfaces (TUIs). It also focuses on utilities for UNIX-like shells; other command-line environments may have different conventions. ## Problematic patterns @@ -82,6 +84,8 @@ Avoiding reliance on color and using whitespace and/or indentation for pseudo-he 11. Be predictable. Users expect "git log" to print a commit log. Users do not expect "git log" to make network connections, write something to their filesystem, etc. Try to only perform the minimum functionality suggested by the command. Naturally, this disqualifies opt-out telemetry. +12. Be safe. If a tool makes irreversible changes to the outside environment, add a "--dry-run" or equivalent option. + Code snippet 2 (console): This is what tab-completion for MOAC looks like with fzf-tab. ``` diff --git a/content/posts/cli-best-practices.md b/content/posts/cli-best-practices.md index 55f2ab3..bc6ec61 100644 --- a/content/posts/cli-best-practices.md +++ b/content/posts/cli-best-practices.md @@ -15,6 +15,8 @@ outputs: --- This began as a reply to another article by Lucas F. Costa; it lists practices to improve user-experience (UX) of command-line interfaces (CLIs). It comes from a good place, and has some good advice: I particularly like its advice on input-validation and understandable errors. Unfortunately, a number of its suggestions are problematic, particularly from an accessibility perspective. +This is a "living article" that I plan on adding to indefinitely. If you like it, come back in a month or two and check the "changelog" link in the article header. +

Note: this article specifically concerns CLIs, not full-blown textual user interfaces (TUIs). It also focuses on utilities for UNIX-like shells; other command-line environments may have different conventions.

Problematic patterns @@ -91,6 +93,8 @@ This is a non-exhaustive list of simple, baseline recommendations for designing 11. Be predictable. Users expect `git log` to print a commit log. Users do not expect `git log` to make network connections, write something to their filesystem, etc. Try to only perform the minimum functionality suggested by the command. Naturally, this disqualifies opt-out telemetry. +12. Be safe. If a tool makes irreversible changes to the outside environment, add a `--dry-run` or equivalent option. + {{}} {{< codecaption lang="console" >}} This is what tab-completion for [MOAC](https://sr.ht/~seirdy/moac) looks like with fzf-tab. {{< /codecaption >}} ```figure {samp=true}