docs/content/en/project/contributing/contributing-cli-guide.md
These guidelines are a collection of principles and conventions that need to be followed while designing mesheryctl commands.
1. Consistency is quality.
Consistency is key when designing intuitive interfaces. Although mesheryctl perf run -f <performance profile name> may sound more intuitive, users who are experienced in using the CLI will prefer the consistent verb apply over run. This will also ensure a consistent command language making memorizing easier. Consistency should also be enforced when chaining commands and using flags.
2. Intuitive user experiences feel natural to users.
mesheryctl design apply -f <design name> requires no further clarification as it is evident that the command will apply the design specified.Part of delivering a great user experience is providing intuitive interfaces. In the case of mesheryctl takes inspiration from and delivers similar user experiences as popular CLIs do in this ecosystem, like kubectl and docker. Here is relevant kubectl information to reference - Kubectl SIG CLI Community Meeting Minutes, contributing to kubectl.
3. Design for brevity.
4. Design with automated testing in mind.
Consistency should also be enforced when chaining commands and using flags. For example, if mesheryctl design has a list and view command and has an -all and --output flag, then, similar commands like mesheryctl perf should also support the same commands and flags and provide a consistent user experience.
Default behaviour should be optimised for what users will need to do most of the time.
These assumed defaults should be easily overridden by the user with flags.
For example, mesheryctl system context create <context name> assumes a default platform for the created context. But this can be easily overridden with the --platform flag.
Ideally, all functionally provided in Meshery UI should be available to users via CLI (in mesheryctl). Meshery strives for parity of functionality between it's two clients. For example, viewing a performance profile in the GUI and with mesheryctl system perf view <profile name> in the CLI should show the same data.
Command line interfaces offer less context to the user, which makes them inherently less intuitive compared to graphical user interfaces. Both of these user interfaces, however, are the same in that they are both clients of Meshery Server. Both clients are a user experience and as such, to be attended to in this way. The following considerations should be accounted for when designing mesheryctl experiences:
--verbose flag wherever needed.AskForConfirmation function which will prompt the user to type in "yes" or "no" to continue.mesheryctl system context create then the next action might be mesheryctl system start to start Meshery ot mesheryctl system context switch to switch context names.mesheryctl system satrt, using the inbuilt features with the cobra library, we can correct it to start and alert the user.The following table outlines a set of design artifacts produced in the process of creating and implementing functional specifications.
| Document | Purpose |
|---|---|
| Meshery CLI Commands & Documentation | Overarching index of all mesheryctl commands |
| Meshery CLI Design Specification - See Creating a Functional Specification | Breakout of individual command purpose, syntax, flags, and behavior. Links to these separate, breakout documents should be pasted into the Meshery CLI Commands & Documentation doc. |
| Mesheryctl Command Matrix | A spreadsheet of all commands, subcommands and flags with an indication of their implementation status would be most helpful for both documentation and planning purposes. |
The following table outlines a set of design artifacts produced in the process of creating and implementing functional specifications.
| Document | Purpose |
|---|---|
| mesheryctl Command Reference | Overarching index in the form of succinct, categorized, and tabularly displayed reference of all commands and their syntax with simple example usage. |
mesheryctl <name of command> | Breakout of individual command purpose, syntax, flags, and behavior. Links to these separate, breakout documents should be available from the mesheryctl Command Reference. |
If you are working on a new command or adding a new feature on an existing command, it is recommended to setup a design spec so that other contributors can weigh in on the design before you start to code.Broader features should have a design spec made in Google Doc. Check <a href="https://drive.google.com/drive/folders/1KHtJc4ToklBQ_UUsDgAL2sVZNhOQGzbh">this Google Doc</a> out, which has detailed information on creating a Design Specification. For small changes, communicating over the issue tracker or the discussions will be helpful.
When designing for the command line interface, ask and consider the following questions.
mesheryctl <command> <subcommand> [args] [flags] [value])You will need to provide a short and long description of the command for the help pages and also for the Meshery Documentation.
If you are working on a new command or adding a new feature on an existing command, it is recommended to setup a design spec so that other contributors can weigh in on the design before you start to code.
Broader features should have a design specification created in the form of a Google Doc. Refer to "Process: Creating a Functional Specification or other Document", which has detailed information on creating a design specification.
For small changes, communicating over the issue tracker or the discussions will be helpful.