░█▀▀░█▀█░░░░█▀▄░█▀█░█▀█░█▀▀░░░░█▀▀░█▀█░█▀█░█░░
░▀▀█░█░█░░░░█░█░█▀█░█░█░█░█░░░░█░░░█░█░█░█░█░░
░▀▀▀░▀▀▀░▀░░▀▀░░▀░▀░▀░▀░▀▀▀░▀░░▀▀▀░▀▀▀░▀▀▀░▀▀▀
        

CLI flags should be kebab cased :: 2024-01-24


This will be an obvious convention to anyone with even a passing familiarity with any (non-Windows) computer, but CLI flags with multiple words should be kebab-cased.

# kebab case
mycli --my-flag foo

If you have spent any time in a terminal, if you are at all familiar with how nearly all software has been designed (most software is not GUI software), if you have spent anything more than 10 minutes exploring the UI/UX of command-line software, you know this is true.

In fact, this convention is so assumed to not require elaboration that the CLIG's section on arguments and flags doesn't seem to even feel the need to specify it, but simply uses the convention in all the examples it provides.

One way this gets broken is with what I'll call "smushcase" flags:

# smushcase
mycli --myflag foo

This is where you smush all the letters together. You'll see it occasionally, and it makes zero sense, but you can't undo these kind of things without breaking the whole world. If you care about saving space so much that you'll omit intermediate dashes... just define a single-character flag.

The worse way I've seen this unwritten rule broken is a "camelCase" abomination. Not only do you see the senselessness of smushcase, but you introduce the equivalent number of keystrokes (but now there are chords!) for just a slightly less readable, harder-to-type, carpal-tunnel-inducing version of the kebab-case equivalent. You also get the added cognitive overhead and micro-toil of guessing/trying whether it's case-insensitive and allows "smushcase" anyway.

# camelCase
mycli --myFlag foo

Thankfully I've seen this very rarely. The place I saw it most prevalent was in Amazon's Builder Tools products. Many of these are hardened into time and baked into the ecosystem so deeply they can't be changed. Their continued use can be forgiven, chalked up to an unfortunate history that began decades ago with Perl-based conventions.

More worryingly is that some parts of Amazon can be so inbred[1], so isolated from the outside world, and so disconnected from 70 years of software and its conventions, that the pattern continues in Amazon internal products.

Thankfully, this seems to have not infected the AWS CLI or other developer products. That can be considered a dodged bullet, as tools like these influence the industry.

</rant>


P.S. If there is any option at all for a single word, use a single word. Naming is hard work; do that work, and choose good words.

P.P.S. Use a single dash for single character flags. Use two dashes for anything longer. Read the rest of the CLIG, 12-Factor CLIs, and also just use some CLIs. CLI Tools are not inherently user-hostile, so if your tool is user-hostile it's not the fact that it's a CLI, it's the design and implementation.


[1] I use inbred here as a biological analogy. Unlike humans, most animals, plants, and fungi rarely avoid inbreeding. While it can lead to genetic disorders, it more generally leads to the propagation of traits. This is how breeds within a species are established, for example, and Amazonians are certainly a breed.

In Amazon, I saw the propagation of both desirable and undesirable traits. The weird trait described above is a genetic disorder that's propagating. This post is not meant to imply Amazonians lack positive traits. Most Amazonians I met displayed sincere care for customers and an amazing work ethic. They also tended to be humble and open to feedback, and just generally very smart people.