#Standards — Seconds to Midnight

Post: CLI Checklist

damian.buho@proton.me (Damián Búho) — Wed, 22 Jul 2026 02:59:00 GMT

Sharing here my checklist that I use for CLI apps (was assembled manually and suffered by real usage). You can feed it to your agent (it will probably forget half of the rules, so use multiple passes or split it).

LLM was used only to fix ESL mistakes.

154 rules.

The key words MUST, MUST NOT, SHOULD and MAY are to be read as described in RFC 2119 and RFC 8174. A rule about a feature binds only a tool that has that feature: a tool without remote accounts needs no login.

Discovery and help

MUST have --help and -h on the top level and on every subcommand
MUST NOT overload -h with anything but help
MUST accept --help appended to any invocation, ignoring the rest of the arguments
MUST show a concise summary when invoked with no arguments, unless the tool reads stdin by default (cat, jq)
MUST keep the concise help to a one-line description of what the tool does, one or two example invocations, the most common flags, and a pointer to --help for the rest
MUST open the help text with the one-line description, then examples (with the real output when it clarifies), then the most common flags and commands
MUST group commands logically, each group in alphabetical order
MUST link to the web version of the documentation from the top-level help text, and link the exact page or anchor per subcommand
MUST link to the issue tracker or website so feedback and bug reports have a path
MUST NOT check for updates implicitly on a normal run, and MUST NOT block on it
MUST have a check-updates command the user invokes explicitly, reporting the current version against the latest released one, unless a package manager owns the tool’s updates
SHOULD also expose help as myapp help and myapp help <subcommand>
SHOULD provide tab completion for bash and zsh, documented in a format the shell understands
SHOULD keep exhaustive or advanced examples in a dedicated cheat-sheet command or web page instead of the help text

Output

MUST send primary and machine-readable output to stdout
MUST send logs, progress and errors to stderr
MUST return zero on success and non-zero on failure
MUST keep human-readable output paramount: humans first, machines second
MUST print output on success, but keep it brief
MUST tell the user when a command changed state, and show the current state
MUST NOT print developer-only information by default: it belongs behind verbose mode
MUST NOT use stderr as a log file: level labels (ERR, WARN) and extra context appear only in verbose mode
MUST have mutually exclusive --verbose and --quiet flags
MUST make -q suppress all non-essential output, so scripts need no 2>/dev/null
MUST offer --plain (one record per line, no wrapping or decoration: banners, ASCII art, table borders, divider rows, [+]/[-] status prefixes) whenever human-readable formatting breaks machine parsing or a screen reader
MUST display indented JSON when --json is passed, or one JSON object per line when the output is a stream of records
MUST NOT pack several records or sentences onto one long line
MUST make a TTY check per stream: colour and human decoration on stdout may go when piped while stderr keeps them
MUST respect NO_COLOR, FORCE_COLOR, TERM=dumb and --color=auto|always|never, and provide a <TOOL>_NO_COLOR override
MUST NOT carry meaning in colour alone, and MUST NOT impose a custom colour scheme over the terminal’s own palette
MUST have progress bars for long/network operations, with one bar per parallel task when possible
MUST NOT emit animations or progress bars on a stream that is not a TTY
MUST print the logs behind a progress bar when the run fails
MUST report the time spent and the external requests made (HTTP and others) at the end of a long or network operation
SHOULD keep the default output short enough to listen to through a screen reader, with filler behind --verbose
SHOULD use colour with intention and sparingly, since colour everywhere means colour nowhere
SHOULD suggest the next command to run when several commands form a workflow
SHOULD increase information density so a glance suffices, growing into detail on study
SHOULD offer a flag that prints only hits when a run reports one line per checked item
SHOULD page long output through $PAGER, defaulting to less -FIRX, only when stdin and stdout are both TTYs
SHOULD parallelise work where it helps, keeping concurrent output from interleaving confusingly
SHOULD show an estimated time remaining or at least an animated component on long operations
SHOULD use symbols where they clarify, without turning the output into a toy

Errors

MUST rewrite expected errors for humans, in plain language, with the exact fix (Can’t write to file.txt. Run chmod +w file.txt.)
MUST NOT print scary stack traces for expected failures
MUST give debug output, a traceback and bug-report instructions on an unexpected error, preferably writing the detail to a file rather than the terminal
MUST use a distinct exit code for each important failure mode: checking an exit code is always easier than parsing output
MUST put the most important information last, where the eye lands
MUST group repeated errors of the same kind under one explanatory header instead of printing many similar lines
MUST NOT silently rewrite the user’s input: when it accepts an alternative syntax, it says so and documents both
SHOULD suggest the correction when user input is wrong and the intent is guessable
SHOULD ask before running the suggestion rather than forcing it
SHOULD make bug reports effortless by pre-filling as much context as possible into the issue URL

Arguments and flags

MUST use an argument-parsing library, the language built-in one or a good third-party one, instead of hand-rolling the parser
MUST validate every input early and bail out before anything bad happens
MUST give every flag a full-length form, and reserve single-letter flags for the common ones so the short namespace stays free
MUST use the conventional names for the well-known flags a tool has: -a/--all, -d/--debug, -f/--force, -h/--help, -n/--dry-run, -o/--output, -p/--port, -q/--quiet, -u/--user, -V/--version
MUST support a --version flag, and MUST NOT let -v mean both verbose and version
MUST allow - to read from stdin or write to stdout when the input or output is a file
SHOULD prefer flags to positional args: they read clearly and leave room to add input later
SHOULD make arguments, flags and subcommands order-independent, so appending a flag to a recalled line still works
SHOULD keep multiple positional args to one meaning, e.g. a list of same-typed files such as rm *.txt; the exception is a memorable primary action like cp <source> <destination>
SHOULD prompt for a missing argument when interactive, and never make the prompt mandatory
SHOULD accept an explicit none when a flag takes an optional value, rather than a blank value

Interactivity and destructive actions

MUST let the user escape: Ctrl-C always works, and a wrapper around a program that swallows Ctrl-C says how to escape
MUST only prompt when stdin is a TTY
MUST have --no-input to disable every prompt, and MUST fail with the flag to pass when input is required in that mode
MUST NOT print a password as it is typed
MUST confirm destructive actions interactively with y/yes, and require -f/--force when not interactive
MUST make severe operations (deleting a whole remote application or server) hard to confirm by accident, asking for the name of the thing being deleted or accepting --confirm="name"
MUST offer --dry-run for moderate operations (deleting a directory or a remote resource, a bulk change) so the user can see what would happen
SHOULD treat a config change that implicitly destroys something as severe

Subcommands

MUST be consistent across subcommands: same flag names for the same thing, similar output formatting
MUST use the same two-level noun verb shape across object types when the tool manages several, and the same verbs for the same operations
MUST NOT have a catch-all subcommand that swallows unknown input, since that makes any future subcommand name a breaking change
MUST NOT accept arbitrary subcommand prefixes as abbreviations; aliases are fine but must be explicit and stable
MUST NOT have ambiguous or similarly named subcommands: update and upgrade side by side is confusing
SHOULD split a complex tool into subcommands, and merge closely related tools into one command

Performance and robustness

MUST print something to the user within 100 ms; responsive beats fast
MUST print before a network request so the command never looks broken while waiting
MUST apply a timeout to every network operation, configurable, with a sane default
MUST say something immediately on Ctrl-C and exit as soon as possible; when a second Ctrl-C would be destructive, say what it will do
MUST be idempotent where possible, and MUST assume a previous run died before its clean-up
MUST be recoverable: after a transient failure the user re-runs the same command and it resumes where it left off
MUST apply a timeout to any clean-up code, so it cannot hang forever
SHOULD assume misuse: scripted invocation, bad connections, concurrent instances, untested environments
SHOULD retry transient failures with backoff and jitter
SHOULD be crash-only: defer clean-up to the next run or design it out, so a failure can exit immediately

Configuration and environment variables

MUST make the default the right thing for most users; a setting nobody knows to pass has failed
MUST apply configuration in precedence order: flags → running shell environment → project config (such as .env) → user config → system config
MUST follow the XDG Base Directory spec for user config (~/.config/<tool>/) rather than scattering dotfiles in $HOME
MUST let any default be overridden in a config file, so an argument is not repeated on every call
MUST ask for consent before automatically modifying configuration the tool does not own, and say exactly what it does
MUST NOT commandeer widely used variable names
MUST name environment variables with uppercase letters, digits and underscores only, never starting with a digit
SHOULD use a flag for per-invocation settings (debug level, dry run) and a version-controlled file for settings stable across a project
SHOULD honour the general-purpose variables: DEBUG, EDITOR, HTTP_PROXY/HTTPS_PROXY/ALL_PROXY/NO_PROXY, TERM/TERMINFO/TERMCAP, TMPDIR, HOME, PAGER, LINES/COLUMNS
SHOULD read .env where appropriate for settings tied to a directory
SHOULD create a new config file rather than appending to an existing one, and delimit additions with a dated comment
SHOULD aim for single-line environment variable values

Security and privacy

MUST NOT read secrets from flags, where they leak into ps and shell history
MUST NOT rely on environment variables for secrets
MUST accept secrets from a file (--password-file) or from stdin
MUST NOT read or write files the user did not pass as arguments (internal state such as a cache excepted), or call a remote server, without saying so
MUST offer a login command for a tool with remote accounts, and treat the CLI’s API calls with the same security practices as the rest of the application
MUST store a token or key, never raw credentials, in the OS keyring or a 0600 file under ~/.config/<tool>/, so it can be revoked without touching the user’s primary login

Telemetry

MUST NOT phone home usage or crash data without consent
MUST respect DO_NOT_TRACK
MUST state what is collected, why, how it is anonymised and how long it is retained
MUST NOT block on analytics
SHOULD prefer instrumenting the docs and the downloads over instrumenting the binary
SHOULD ask for consent once, at first run, and make withdrawing it as easy as giving it

Naming and distribution

MUST give the program a short, memorable, lowercase name that is not too generic and does not collide with an existing command
MUST be easy to uninstall, with the instruction at the bottom of the install instructions
SHOULD keep the name easy to type for something people run all day
SHOULD distribute as a single binary when the language allows it
SHOULD otherwise use the platform’s native package installer over scattering files that cannot easily be removed

Compatibility and future-proofing

MUST treat subcommands, args, flags, config files and env vars as interfaces, and keep changes additive where possible
MUST warn in the program itself before a non-additive change, telling the user how to make their usage future-proof, and stop warning once they have
MUST document deprecations with a version number and a replacement
MUST test on every platform the tool claims to support, and list them in the docs
MUST note platform-specific install steps and behavioural differences rather than leaving users to guess
SHOULD pin what the tool depends on
MAY change human-readable output freely; that is why --plain and --json exist for scripts

Documentation

MUST define the CLI’s purpose in one sentence
MUST list every command with a one-line explanation
MUST give each command a syntax block before anything else
MUST give every key command at least one copy-paste-ready example
MUST explain every flag: what it does, when to use it, what happens if it is skipped
MUST state default values and show the output format with a sample
MUST document the errors users will hit and the exact command that fixes each
MUST outline the setup requirements: authentication, environment variables, system prerequisites, minimum versions
MUST cross-reference related commands, pointing to the next logical step
MUST use one term per concept and keep it identical to the product’s own wording
MUST show commands and their output as text, never as images
MUST run every example command in the docs as written before publishing
MUST state the CLI version the docs match, and note features that only exist from a given version
MUST keep the docs in version control and update them in the same commit as the CLI change
MUST use the same public docs for internal developers
SHOULD outline real-world use cases, not just the command list

Testing and feedback

MUST get the CLI in front of developers who did not write it, including outsiders and newcomers
MUST have someone outside the team read the docs for the first time and follow them without guessing
MUST listen to the default and --plain output end to end through a screen reader (Orca, or espeak-ng at the least)
SHOULD let users report usability problems easily, and invite usability feedback from newcomers
SHOULD be explicit with testers about what feedback is wanted, and accept the spontaneous kind

Sources

Command Line Interface Guidelines by Aanand Prasad, Ben Firshman, Carl Tashian and Eva Parish, CC BY-SA 4.0: many rules here are adapted from it
Heroku CLI Style Guide
12 Factor CLI Apps by Jeff Dickey
GNU Coding Standards: Standards for Command Line Interfaces
POSIX Utility Conventions
RFC 2119 and RFC 8174: requirement key words
XDG Base Directory Specification
NO_COLOR and FORCE_COLOR
Console Do Not Track: the DO_NOT_TRACK variable

Post: AI Stance

damian.buho@proton.me (Damián Búho) — Tue, 23 Jun 2026 02:59:00 GMT

Inspired by Armin Ronacher's AI Transparency Statement

I use coding agents every day, but never use LLMs for writing or anything that's meant to be read by humans. I occasionally make a throwaway picture (like an avatar).

I do use them to fix idiotic ESL mistakes I sometimes make. I use … and — via the Compose key in Linux since the 2010s. I have a background in traditional publishing and believe that three dots (...) are not an ellipsis (…) and never will be.

Ground rules

Disclose for humans

Every human deserves to know the source of your information, and has the right to ignore an LLM answer without reading it. It's a good rule even for non-AI applications; I am not reading your "russia today" quote, mate.

So, an LLM response should be marked with the same effort as "trigger warnings" or at least use some quoting standard like APA.

I make an exception for code, because the clanker that did some menial task doesn't deserve a "Co-Authored" byline. Also, no one reads your code anyway (sad, but true).

Accepting full responsibility

An agent/model didn't fuck up. You did.

Never give up control

Don't trust them fully; always have a deterministic pipeline to check their work.

More personally

I dislike the misleading "AI" term and people who are really into it.

Although, I believe any technology can produce obnoxious zealots. Just look at crypto.

Maybe people should look into who raised all of those assholes, instead of screaming at a chain of hashes or matrix multipliers.

I accept LLMs as a genie that can't be put back into the bottle. Holy wars about LLMs are boring.

I do believe that companies behind so-called "SOTA models" are not to be trusted and LLMs should be self-hosted and sovereign.

At the same time, the whole "they drink all our water" trope is a good way to detect virtue-signalling idiots. Most of them can't distinguish an artesian well from an Abyssinian one and have zero interest in the state of local aquifers.

Projectfile

I use the "org.projectfile.ai" extension in my projectfile schema, which generates an "AI POLICY.md" document in all my projects.

Post: Spotlight: human.json

damian.buho@proton.me (Damián Búho) — Mon, 25 May 2026 02:59:00 GMT

I have human.json on this site.

human.json is a lightweight protocol for humans to assert authorship of their site content and vouch for the humanity of others. It uses URL ownership as identity, and trust propagates through a crawlable web of vouches between sites. https://codeberg.org/robida/human.json

I like the idea of establishing trust between people in this slop era.

I always felt like such conventions and standards are something that only a bunch of important grayscrotums in very important commitees can do, and human.json actually inspired me to design projectfile, first and foremost for myself, but also to put it out there.

Although, I believe that any kind of commentless JSON should be only used by Catholic nuns as punishment tool, I also believe we need more initiatives like this one. Not only because it's a legitimate attempt to solve a problem, but also because we lately gave up a lot of ground to committees of aforementioned grayscrotums (corporate or pseudocorporate), and the world kinda sucks because of it.

You can fuck the right off with your new vibe-coded habit tracker, but if you have an idea for a protocol or a scheme that empowers other people to build, I salute you. Even if it's weird or obscure, any such idea is an open invitation to work together, and that's cool.

P.S. Technically it was just a "Vouch" collection in my Payload CMS backend, and a little renderer for my Astro frontend, so I am not sure that I'll open a human.json consulting agency anytime soon.