As I used to be sitting in a gathering room, talking with one in every of my teammates, our supervisor walked in with the remainder of the dev group. The door slammed shut and our supervisor revealed that he had an enormous announcement. What unfolded earlier than our eyes was the subsequent venture we had been going to develop—an open supply CLI (command line interface) utility.
In this text, I’d wish to share what I discovered throughout our growth course of, and particularly what I want I had recognized earlier than we started creating Datree’s CLI. Perhaps the subsequent individual can use these tricks to create a fantastic CLI utility sooner.
My title is Noaa Barki. I’ve been a full-stack developer for over six years, and I’ll allow you to in on slightly secret—I’ve a superpower: My curiosity and experience are evenly break up between back-end and front-end growth. I merely can’t select one with out the opposite.
So when my supervisor revealed the information about our future CLI, the back-end developer-me obtained very excited as a result of I’d by no means created a CLI (or any open supply venture, for that matter). A couple of seconds later, the front-end developer-me began to surprise, How can I construct an superior person expertise in a CLI utility?
Since Datree CLI helps engineers forestall Kubernetes misconfigurations, my customers are primarily DevOps and engineers, so I interviewed all my DevOps buddies and searched on-line in regards to the basic DevOps persona.
Here are the steps I got here up with:
- Design the instructions
- Design the UI
- Provide backward compatibility
Step 1: Design the instructions
Once you will have accomplished the strategic course of, it is time to design the instructions. I take into consideration CLI functions like magic bins—they maintain nice options that work in a magical approach, however provided that you know the way to make use of them. That means a CLI utility should be intuitive and straightforward to make use of.
My high six ideas for CLI instructions
Here are my high six ideas and finest practices for designing and creating CLI instructions:
1. Input flag vs. arguments
Use arguments for required fields, and for all the things else, use flags. Take, for instance, the datree take a look at command, which prints the coverage outcomes, and say that you just wish to allow the person to print the output into a selected file. If you employ datree take a look at {sample} {output-file}, it’s obscure from studying the executed command which argument is the sample and which argument is the file path.
For instance, this happens with the next command: datree take a look at **/* **.YAML. However, in the event you use datree take a look at {sample} -output {output-path}, it turns into a lot clearer.
Note: Reports present that the majority customers discover flags to be clearer.
2. Enum-style vs. Boolean flags
It’s preferable to make use of an enum-style flag over a Boolean-style flag as a result of you then (a developer and person) want to consider all combos of the presence or absence of the flags within the command. An enum-style flag is a flag that assumes a worth. Enum-style flags make it a lot simpler to implement tab completion.
3. Use acquainted language
Remember {that a} CLI is constructed extra for people than machines. Pick real-world language in your instructions and descriptions.
4. Naming conventions
Use CLI instructions which can be named in a SINGLE kind and VERB-NOUN format. This permits the command to be learn like an crucial or request, for instance: Computer, begin app!
Minimize with the overall variety of instructions you employ, and do not rush to introduce new verbs to new instructions. This makes it simpler for customers to recollect command names.
5. Prompts
Provide a bypass to the immediate possibility. The person can’t script the command if prompting is required to finish it. To keep away from irritating customers, a easy --output flag is usually a worthwhile answer to permit the person to parse the output and script the CLI.
6. Command descriptions
The root command ought to listing all of the instructions with their descriptions. Provide a command description to all instructions (or don’t supply descriptions in any respect), select the display width you need it to suit into (usually an 80-character width), and start with a lowercase character. Also, do not finish with a interval to keep away from unclear line breaks or misplaced intervals.
Step 2: Design the UI
Now you will have a strong definition in your customers. You have additionally deliberate and designed your instructions and outputs. Next it is time to consider making the CLI utility aesthetic, accessible, and straightforward to be taught.
If you concentrate on it, virtually each app should cope with UX (person expertise) challenges throughout the customers’ onboarding and journey. The how a part of UX for internet functions is way more apparent as a result of you will have many part libraries (comparable to material-UI and bootstrap) that make it simpler to undertake commonplace type guides and performance flows. But what about CLI functions? Are there any design conventions for CLI interfaces? How are you able to create an aesthetic design of the CLI performance that can also be accessible? Is there any method to make the CLI UI as pleasant as a GUI?
Top three UI and UX finest practices for CLI functions
1. Use colours
Colors are a good way to draw your person’s eyes and assist them learn instructions and outputs a lot sooner. The most really helpful font colours are magenta, cyan, blue, inexperienced, and grey, however remember that background colours can present extra selection. I encourage you to make use of yellow and purple colours however keep in mind that these are sometimes saved for errors and warnings.
2. Input-output consistency
Be in step with inputs and outputs throughout the applying; this encourages usability and permits the person to learn to work together with new instructions rapidly.
3. Ordering arguments
Choose an argument’s place based mostly on the way it correlates with the command’s motion. Consider NestJS’s generate command nest generate {schematic} {title}, which wants schematic and title as arguments. Notice that the motion generate refers on to the schematic, not title, so it makes extra sense for schematic to be the primary arg.
Step 3: Provide backward compatibility
Avoid modifying the output. Now that you know the way to create an ideal CLI utility, remember to maintain your customers behind your thoughts, particularly when enabling scripting the CLI. Remember that any change within the command’s outputs might break customers’ present scripts; subsequently, keep away from modifying the output.
Wrap up
Creating a brand new CLI is thrilling and difficult, and doing so with a useful and straightforward UX provides to the problem. My expertise reveals that three key components go right into a profitable UX for a CLI venture:
- Design the instructions
- Design the UI
- Provide backward compatibility
Each of those phases has its personal elements that assist the logic and make the lives of your customers simpler.
I hope these ideas are helpful and that you’ve got the chance to use them in your subsequent venture.
