“And the words slide into the slots ordained by syntax, and glitter as with atmospheric dust with those impurities which we call meaning.”
— Anthony Burgess, Enderby, 406
Naming a CLI command requires deep and careful deliberation. Yet most commands seem to have been named with playful insouciance at best, and foolish indifference at worst—with neither the forethought required to stand the test of time, nor the respect demanded of the long and venerable history of the command line. If naming things is one of the two most important and challenging tasks we face as programmers, why do many commands seem to have been named so arbitrarily?
A terrible command name is a curse, but a great command name has a poetic elegance. If you’re adding something to the command line spell book, I hope this post can help bring clarity and consideration to the process.
Command naming anti-patterns
Because the first step is to avoid catastrophe.
The following words should never be in any command name:
There’s no excuse for requiring the user engage the shift key. I’m looking at you,
If you spend enough time thinking about command names, you will discover with delight that it is technically possible to name your command
🐥_Tool. Please don’t.
How does it feel to type the command? Is it awkward or satisfying? How much finger travel is required? For example,
sha256sumfeels like gargling sand, but Wireshark’s
capinfoscommand is a soft breeze across the keys.
The version number should never appear in the command name. It’s 2020, and there is a command on my system called
python3.7m. Nothing reveals the erosion of our ancient and beloved command line ecosystem more clearly than this. In 50+ years of typing into terminals, we have not figured out how to have multiple versions of things coexist peacefully.
Don’t start your command name with the letter
geven though it’s a perfectly fine letter situated right in the center of the keyboard. All past and future
gcommands are the personal property of Richard Stallman, who in 1983 was granted an exclusive, perpetual, irrevocable, worldwide license to the entire
gnamespace. Although he grudgingly granted exceptions for
go, if you’re not Linus Torvalds or Google, don’t bother hitting him up.
The previous bullet point was a joke.
The more niche your command, the longer its name should be. Very short names should be reserved for utilities people use all the time, like
Unless your package consists of a suite of shell utilities, don’t pollute the namespace with dozens of commands. Install one or two commands, and use subcommands to reach different corners of your program. Of course, there are many reasons you may want the crisp boundaries afforded by separate executables. If you really need more than a few binaries, you can always make them callable from one or two central commands. Git does a great job here; you can extend Git by putting an executable in your
git-[command], and you’ll be able to reach it using
Don’t name your command after a new standard or a protocol or file format. These things go in and out of fashion, and they’re often too specific. If you would like your command to find its way into the Golden Spellbook of Timeless Unix Commands, don’t call it
openssl. Surely whoever named
opensslis regretting it to this day. Will they ever rename it to
opentls? No way. It’s too late. It’s in too many Bash scripts now. We have to live with
openssluntil the sun swallows us up. Same deal with
ffmpeg, which does far more than fast forward MPEG files.
Don’t name your command after the kind of user interface it provides. Example:
cfdiskis a version of a prior command (
fdisk) with a newer interface (Curses). This is a case where the developers spent so much time working on the Curses interface that they decided to celebrate their achievement in the name of the command itself. But from a user’s perspective, it really doesn’t matter. It’s moot. Imagine if Slack called itself
Don’t make broad claims on generic words. For years, ImageMagick provided the
convertcommand. Unless you have built a tool that is able to convert anything to anything—a Markdown file to a jpg, a salad spinner to a garlic press—you should not name your program
ImageMagick version 7 wisely gave up their claim on
convertin favor of the new
magickcommand, which has a
convertsubcommand. They were forced to give up
convertbecause Windows also has a
convertcommand. Do you know what the Windows
convertcommand does? I’m sure you don’t. And you’re a pretty smart person.
convertin Windows is used to convert a disk between different types of filesystems. 😒 What a perfect example of a command that claims a name way too broad for an incredibly small niche!
Don’t depend on your command’s name to determine its scope. Keep those decisions separate.
Imagination will get you far. You might get inspired with a favorite book of Filipino folk tales, some Norse mythology, Shakespearean sonnets. Just don’t get too into the Norse mythology, okay? Maybe the story of Yggdrasil gave you a deep sense of clarity in your life path. I don’t know, I haven’t read it. But I don’t need to read it to tell you that it’s a diabolical name for a shell command.
vim is a brilliant name because vim is exactly what you feel after pulling off a ninja substitution that turns your CSV into JSON, or a crafty multi-line edit that sorts a list of horror movie titles by descending Rotten Tomatoes score.
vim is the “improved”—now standard—version of
vi. I’m still not sure why the people of ancient Rome who invented
vi decided to name their text editor after the number 6?
curl might be the most cleverly named command of all time. It’s a verb. It brings to mind a beckoning finger. It does what it says it does, and when you spell it out loud it sounds like “see URL.”
Not all of the best 2-5 letter words have been used up. Please don’t make me tab complete the name of your command.
Consider how your command will be pronounced around the world. Kodak is a word that was designed to sound the same in many languages.
ikeamight be great command names too, if they weren’t already trademarked.
Can you type your command with one hand—like
cat—while your other hand is on the mouse?
Would your command read well in a poem?
Ah, bitter chill it was!
The owl, for all his
awk, was a-cold;
gunicornlimp’d trembling through the frozen grass,
And silent was the
—Paraphrased from John Keats, The Eve of St. Agnes
Hey it’s just a rule of thumb, but notice how the command
AssetCacheTetheratorUtil(added to macOS in 2017) would never fly here.
If you really want to be both literal and niche, you could signal the solution domain in your name for clarity. But you’re walking a fine line here. The ancient
mkfstries. It nestles well into the group of commands related to making things in the filesystem, like
mktemp, and even
mklost+found. It might be a bit of an overreach to use
mkas the commonality here, given that one could imagine lots of commands for making things not related to the filesystem. But, files are a primary abstraction provided by the operating system, so it’s not the worst thing to use
Thoughtful meaninglessness is completely fine and might even be your best option if you expect your command’s solution domain to evolve. I still don’t know what an emac is or why I need several of them to edit a file. Meaninglessness is the route we took here at smallstep, where we have humbly laid claim to the
step-cacommands for our public key encryption toolkit and certificate authority. The naming of
steppays homage in a small way to the Moon landing, but as a name it really has no connection to crypto, and that’s okay because it’s easy to type!
- None of the above matters if your command doesn’t actually do something useful.
Have you had the task of naming a CLI command? What was your approach? Hit us up on Twitter.