MAAS new CLI iteration 2
Last week, we have been testing out the CLI prototype with 6 MAAS CLI users to collect feedback on what we can do to improve our current CLI experience.
The first thing we tested out was the concept of the initial help or what our testers mostly referred to as “cheat sheet”.
When a user types maas or maas --help , you will see a cheat sheet as a guideline to help you do basic operations. In the first prototype, we introduced the concept of a primary object (machine), so by default, MAAS interprets an action against machines as an object when no object is indicated.
We received a lot of positive feedback for this concept and our testers wanted to see what other objects are available in the CLI. So to provide learnability, we added “Hints” to this page and indicate the current version of MAAS as well as other useful information.
One use case was frequently mentioned during the test regarding how to operate bulk actions for multiple MAASes or data centers.
Breaking down MAAS objects. In the current CLI, we have both singular and plural forms of object as a way to indicate collection services VS individual services. In this version, we stripped down all plural objects and broke them down into different categories for readability. We’ve also added a link to the documentation page for further readings.
Highlight: 5 out of 6 users mentioned that they don’t like reading the documentation and would not bother to read them because when they are working with the CLI they feel like they have to start the search over again in the documentation page. It felt like they have to do a double search to get to the point where they get the answer. So to reduce that hassle, we attached the right documentation link to the relevant commands help page.
In this prototype, we also introduced the concept of primary profile, which is reflected on the current prompt. A user may login to multiple profiles and set one of the profiles as their primary profile. When a user wants to take actions on multiple profiles such as deploying 10 identical machines 3 MAAS profiles, they just need to apply a profile flag to their deployment action.
The user will always see their current profile when they take action. This is to help prevent our users from making mistakes and that they are aware of their current environment.
To enhance the experience for learnability, we also try to break down the help page to be more meaningful. This is an example of the new help page. It will show you a brief description of the action, options, different ways to customise the outputs, examples, and related commands. For instance, maas list will list multiple or individual node description in a compact format as an overview. Whereas a related command is
maas show, where a user can drill down detailed information of a particular machine in an elaborate manner.
After going through this user test, our team has agreed to make the default experience in the CLI compatible with our scripting users because we have a separate MAAS UI that can achieve the same purpose. However, if a user prefers to do things in MAAS using the CLI and expecting a beginner’s experience, they can use the” --interactive “ flag or “ -i” to use the interactive prompt.
When a user indicates -i in the CLI, they will be presented with an interactive prompt where, it will ask for required information for the deployment such as OS, release, kernel, setting a machine is a KVM host, and customising cloud-init user-data.
By default, maas deploy will throw an error, because a user needs to supply information about the machine or a characteristic of a collection of machines they wish to deploy.
Since the default experience is tailored to scripting users, by default a user will get the prompt back when they perform an action. They will also be informed that the machine(s) they deployed are running in the background and they may use any of these suggestions to check up on the status of the deployment.
If a user wishes to have their prompt block when performing an action and want to see if it’s running, they can use the --wait flag to see the waiting state of the CLI. This will show a broken down version of the running task, a loading indication, and the time elapse. Time is quite important for MAAS users because for many users, if something is processing longer than usual, they would rather have that process aborted and reboot.
What’s next?
- We are still working to define a better way to help our users debug when an error occurs. So the error state is another important piece that we are focusing on. Our current goal is to enhance the learnability aspects of our CLI and help our users recover from their errors or mistakes.
- Another interesting feature is partial matching of the machine name. Currently, MAAS operates on machine IDs, which is not easy to fetch. We will allow our users to operate based on the machine names instead and they can either supply the full FQDN or just hostname. The current prototype provides suggestions for misspelled names and our next task is to allow partial string matching for this.
If you are reading about this and would like to add feedback, we are more than happy to find out how we can improve the CLI experience. Your feedback is a gift.
hell yeah ! This is fantastic.
