Kevin Pham

Designing a CLI: 11 Principles from the MongoDB Realm Design Team

Don Norman saw this coming. Back in 2007 , Norman, one of the giants of user-centered design, predicted that the next UI breakthrough in the design world would be the command-line interface (CLI). Noting the limitations of graphical user interfaces and the capabilities of command-line language in search functions, Norman staked this bold claim: “Command line interfaces are back again, hiding under the name of search. Now you see them, now you don't. Now you see them again. And they will get better and better with time: Mark my words, that is my prediction for the future of interfaces.” In 2020, the return of the CLI is, perhaps, debatable. In the world of software development, CLI's still dominate with software professionals , due to their wide availability, high capacity for automation, and cultural fit with the developer ethos. But in the design world, “user experience” is still largely associated with modern web and mobile interfaces — clean whites, curved borders, and gradient buttons. Design interventions of the CLI are often left to the wayside. Here at MongoDB, our designers understand the importance of the CLI to our users. Through internal discussion and collaboration with our product and engineering teams, we are working hard to match the user experience of the CLI to our user’s needs. As such, the MongoDB Realm team has been working on a revamp of our Realm CLI to be released by the end of Q4. In order to improve the experience of using the CLI, our UX research and Realm design teams have conducted primary and secondary research, attempting to figure out how our CLI is used, and how developers commonly interact with CLIs writ large. Based on our findings, we created a list of 11 CLI UX principles for the Realm CLI . We call this our CLI Design Cheat Sheet. Modeled off Nielson-Norman’s Usability Heuristics , this set of principles has allowed us to inform and streamline our CLI design process, and to foster a user-centered approach across our product’s operations. It’s my hope that presenting these principles will help others design better CLIs, too. We’ll provide some CLI illustrations that are not representative of the new Realm CLI, but can help show these principles visually. 1. Allow users to create and clone Realm applications and assets via the CLI Develop short and easy-to-understand commands for app creation and cloning. Consider dividing this command into an object and an action: For example, the command may read realm app clone , where “app” is the object, and “clone” is the action. 2. Use accessible language to bridge the CLI and the real world The system should speak the users' language, with words, phrases, and concepts familiar to the user, rather than system-oriented terms. When creating CLI commands and prompts, use questions or phrases that resemble sentences. Avoid positional arguments, where the order matters. These types of arguments can be confusing. Use flags instead of args. Although they require a little more typing, flags better prevent input errors (e.g., realm fork --from sourceapp --to destapp ) compared to args (e.g., realm fork -sourceapp ) When collecting user information, use questions to make the CLI more conversational. For example, when initializing, the CLI can ask the user questions such as, “What’s your project name?” when determining the user’s framework. 3. Simplify CLI outputs to increase user control Complicated and messy outputs reduce user control and diffuse action. CLI users expect high-level outputs following a command. Make outputs simple so that users don’t need to scroll through multiple lines of text to find what they need. The MongoDB CLI provides a good example of human-friendly CLI output: Human-friendly MongoDB CLI output. Additionally, the CLI should allow for both human-friendly (plaintext) output, and machine-friendly (JSON) output. A user should be able to define which output they’d like to see. For example, the MongoDB CLI has the following functionalities that allow users to define their output as plaintext or JSON: Illustration: Allowing users to choose between different output formats. 4. Make terminologies consistent Try to use the same terminology consistently across your product’s system. In the case of Realm, the product’s CLI should use the same terminology as its GUI, as well as other CLI’s across the MongoDB platform. Additionally, try to draw from the user’s context with terminologies from the tools and CLIs that are already familiar to your users. 5. Prevent errors As mentioned before, the use of flags -- as opposed to args -- is one way to accomplish this. Another consideration is to have clear warnings and retype commands. These can better prevent destructive mistakes. For instance, instead of using a “Y/N” prompt, consider having the user re-type their input, and prefacing with a warning that it may result in drastic changes to their program. Illustration: Providing a warning and a retype command to prevent destructive errors. 6. Maximize user recognition by combining commands or prompting input Make the CLI experience more efficient and easy-to-use by easing the user’s memory load. One way to do that is by giving users a single command to perform a task, which doesn’t require them to remember certain inputs. For MongoDB Realm, this principle can be mobilized to improve our authentication experience. A single command can be called to automatically generate CLI credentials from the Realm CLI for Atlas. If it isn’t possible or ideal to combine several commands, then consider a prompt showing users a choice of complicated options in the CLI. Rather than asking users to type and remember an input, the CLI can show them a series of options. Illustration: A prompt suggesting complicated inputs that are hard to remember 7. Make the CLI more flexible by allowing users to easily set and change configuration options Understood generally, this principle is meant to highlight user freedom and customization capability. The CLI should provide straightforward commands that can allow users to easily set and change things as they wish. In the case of Realm, we are looking to make MongoDB auth configuration file creation automatic upon Realm initialization, with the access token stored in the user’s home folder. This makes configuration more efficient. Additionally, we are considering allowing users to change their config file directly in the CLI to increase user flexibility. 8. Implementing aesthetics and interactions There are different visual considerations that can improve CLI interactions and experiences. Here are a few examples: Adding better color support (e.g., Yellow or green = good; red = wrong) Adding visual hierarchy for tables (e.g., making headers stand out through highlighting) Adding spinners, progress bars, and/or step count to show long-running tasks Illustrations: Different ways to show task runtime. 9. Help users recognize, diagnose, and recover from errors Error messages should be expressed in plain language (no codes), precisely indicate the problem, and constructively suggest a solution. They should be informative and should indicate next steps. Consider providing or linking to a troubleshooting guide or links to documentation as part of your error messages. 10. Help and documentation For users that decide not to go through the CLI docs, the help command is vital. We recommend writing a small description of the CLI’s purpose in the --help command. Also, consider providing links to documentation when necessary (i.e. as part of an error message). An example of an effective --help output is seen in the MongoDB CLI: The MongoDB CLI's --help output is both descriptive and concise. 11. Maintain user control and freedom by allowing users to opt-out of data collection Allow users to control data collection settings from their config in the CLI. This functionality can be provided with a command. In the case of realm, this may look like: --realm telemetry-disable . We hope these principles provide a solid foundation for designers and developers looking to create effective, user-centered CLIs. Be on the lookout for a new version of our Realm CLI by the end of Q4! Interested in trying MongoDB Realm ? Start building your app today! Start Free