The Command Line Interface Guidelines (CLIG) is an open-source guide inspired by the traditional UNIX philosophy and aims to revisit the best practices and design principles behind command-line programs. InfoQ has taken the chance to speak with CLIG authors to learn more.
CLIG is based on a number of fundamental principles. Those include the idea that CLI programs should be designed for humans and be composed together to build more complex systems. Additionally, to improve usability, a command line interface should follow known patterns that have proved to work. In this respect, CLIs should attempt to make their functionality discoverable and aim to support a conversational interaction with the user, while also being robust. Two less common principles that should be followed, according to CLIG authors, are empathy and chaos.
The Command Line Interface Guidelines is full with examples and suggestions and covers areas such as arguments and flags, errors, output, subcommands, configuration, and more. Their content goes well beyond that which can be summarised here, but InfoQ has taken the chance to speak with CLIG authors to learn more.
InfoQ: Could you explain how you came to the idea of writing the Command Line Interface Guideline? What is its main purpose?
It started as a practical need. Ben’s company Replicate is building a CLI tool, and he couldn’t find a good resource for best practices. Carl started collaborating with him after he read a blog post Carl wrote, called The Poetics of CLI Command Names. Aanand joined because he and Ben were co-creators of Docker Compose, and they learned a lot from the experience of designing it that they wanted to share.
As we got more into writing it, we saw that it was an opportunity to give something back to the community. We hope CLIG will help in a small way to promote great CLI design.
InfoQ: CLIG puts forth the principle of "human-first design", following the idea that if "CLI programs are used primarily (or even exclusively) by humans", they should be designed for humans. Yet, a fundamental use case for CLI programs is to be used by other programs. Are these two purposes conflicting?
Yes. That’s the central challenge of CLI design, and much of the advice in CLIG is directly about methods we’ve learned for serving both purposes.
InfoQ: Among the philosophical principles at the foundations of CLIG, you include empathy and chaos, which could come as a surprise to some. Would you mind elaborating their importance and how should they affect the process of defining a tool's CLI?
We have all been driven to tears trying to use poorly-designed command-line programs. Nobody wants that. At one point when we were working on CLIG, we realized that we all really cared that command-line programs not just be functionally powerful, but delightful to use. That’s where empathy comes in.
As for chaos, that principle is really just a reminder of the freedom that exists within the constraints of the CLI. Consistency is good—it enables tools to be used in new and unexpected ways—but too much of it can breed stagnation. We want people to think for themselves about CLI design; that’s how we will innovate in a space where it seems like everything has already been done.
InfoQ: How was CLIG received by the developers' community? What's on its roadmap?
We were shocked by how much launch traffic CLIG got. It got 600 GitHub stars in the first week! That was amazing. It’s been very validating to hear people say they’ve wished for something like CLIG for a long time. Of course, there’s been some very vocal nitpicking—it would be weird if an audience of software engineers didn’t get their feathers ruffled by relatively unimportant details—but on the whole, people have been very kind. That said, the next step on the roadmap is to comb through and address all the feedback.
CLIG rules are not immutable, say the authors, who are open to listening to your suggestions.
The Command Line Interface Guidelines was created by Aanand Prasad, engineer at Squarespace; Ben Firshman, co-creator of Replicate and Docker Compose; Carl Tashian, developer advocate at Smallstep, first engineer at Zipcar, and co-founder of Trove; and Eva Parish, technical writer at Squarespace, and O’Reilly contributor.