I remember being tasked to build a git workflow CLI tool for my team; I was getting called everyday to remind them some command of what was suppose to be shortcut and faster to remember. If i had paid attention to the UX as well as how funtional the tool should be it would have been more productive.
When building CLI tools for automating tasks for your team there are some free guidelines that are important to take note of. The famous workshop written and delivered by Steve Francia and Ashley McNamara at OSCON 2017 outlined the techniques, principles, and libraries you need to create user-friendly command-line interfaces and command suites.
This article will be covering and summarizing the human interface guidelines for CLI.
The Unix Philosophy
By adhering to the Unix philosophy in CLI design, developers can create tools that are simple to use, easy to understand, and capable of being integrated with other tools seamlessly. These principles promote the development of powerful, flexible, and user-friendly command-line interfaces.
The Unix philosophy is a set of design principles that originated from the Unix operating system and has been influential in the development of various software tools and command-line interfaces (CLIs). These principles emphasize simplicity, clarity, composability, extensibility, modularity, and keeping programs small. Let's explore each of these aspects in relation to CLI design:
- Simple
CLIs should strive for simplicity by focusing on a single task or purpose. Each command or tool should do one thing well and have a clear and concise interface. This simplicity makes it easier for users to understand and remember how to use the CLI effectively.
- Clear:
CLIs should provide clear and understandable output to users. Error messages and help documentation should be concise and provide relevant information to guide users in their interactions with the CLI. Clear output and intuitive command syntax contribute to a positive user experience.
- Composable:
Unix philosophy encourages the building of small, single-purpose tools that can be combined to perform more complex tasks. CLIs should be designed to be composable, allowing users to chain together commands or tools using pipes or redirection. This composability enables users to create powerful workflows by leveraging the strengths of individual tools.
- Extensible:
CLIs should be designed with extensibility in mind, allowing users to add or modify functionality to suit their specific needs. This can be achieved by providing extension points or supporting plugins. An extensible CLI ecosystem fosters community contributions and enables users to tailor the CLI to their workflow.
- Modular:
Modular design involves breaking down a complex system into smaller, independent modules or components. In the context of CLIs, this means structuring the codebase into separate modules that can be developed, tested, and maintained independently. Each module should have a well-defined responsibility and interface, making it easier to understand, modify, and reuse.
- Small:
The Unix philosophy advocates for keeping programs small and focused. Similarly, CLIs should avoid unnecessary complexity and aim to provide concise, targeted functionality. Small programs are easier to understand, test, and maintain. Additionally, they tend to have fewer dependencies, leading to more lightweight and efficient execution.
Some rules to follow in writing commands while building CLI tools include
It should be short and clear
#List files and directories in the current directory
ls
# Copy files and directories
cp source_file destination_file
# Display the contents of a file
cat file_name
# Change the current directory
cd directory_name
Always use verbs for commands that will carry out an action. Example
# remove file
rm name_of_file
# Bad example of removing a file
erase
When writing many args in command, order matters. Example
#correct way
cp [file] [new_file]
#bad way
cp [new_file] [file]
CLI commands are often designed to be composable, allowing users to chain multiple commands together. Consistent argument order facilitates composing commands by enabling users to easily pass the output of one command as input to another.
Commands should be pronounceable. Example
cp [file] [new_file]
Can be read aloud as copy file to new_file
When shortening commands, use the first letter as a prefix. Example;
rm –force
Should be shortened as...
rm -f
Multiple options should be stackable. Example;
rm -r -f
Should be able to be written as...
rm -rf
Adding a flag should follow the sequence “verb -> adverb -> noun”. Example;
rm –force [file]
This is pronounceable as "remove file forcefully".
Another example is...
ls –color /home/codedfinger
The naming of CLI apps should be in noun form. Example;
Cat
Vi
httpd
emacs
git