Improve CLI UI and UX

[fmvilas]

Reason/Context

The current CLI is great but lacks some consistency and quality in how we handle user errors and mistakes. On top of that, we could be doing a better job in making it look nicer, although that's secondary IMHO.

A CLI with a great user experience should help the users navigate it easily, recover from bad states (errors/mistakes), and move forward after a command has been executed. Especifically, when it comes to error messages, it always comes to my mind this image:

We have a bunch of this ☝️ We should instead aim for something like this:

This article is really good in case you're interested: https://wix-ux.com/when-life-gives-you-lemons-write-better-error-messages-46c5223e1a2f

Description

So, what are the tasks to do here? I just came up with a few ones but feel free to suggest adding others:

• Improving error messages
• Improving the --help command listing
• Review all commands to see if they're consistent with the CLI structure (this may cause a breaking change)
• Enhance the visual design of different elements like success messages, info messages, and error messages.

[Shurtu-gal]

@fmvilas Adding this issue to link a previous discussion also.
#551

[Shurtu-gal]

@fmvilas Would love to work on this too.

[sambhavgupta0705]

@fmvilas I would like to work on this one

[aeworxet]

Bounty Issue's End Of Life (EOL): 2024-02-29 23:59:59 UTC-12:00

[Mayaleeeee]

Hello @fmvilas
I would love to work on this issue.

Thank you.

[fmvilas]

Since this is purely a design task (no code required), I'm assigning this to @Mayaleeeee. That said, we'll want to make it a reality down the track. As an outcome of this issue, Maya will come up with a list of other issues for implementation. Most likely good first issues. I count on you for those, @sambhavgupta0705 and @Shurtu-gal 🙏

[aeworxet]

Bounty Issue's Timeline

Complexity Level	Assignment date (by GitHub)	Start date (by BP rules)	End date (by BP rules)	Draft PR submission	Final PR submission	Final PR merge
Medium	2023-11-07	2023-11-13	2023-12-22	2023-11-24	2023-12-08	2023-12-22

Please note that the dates given represent deadlines, not specific dates, so if the goal is reached sooner, it's better.

[Shurtu-gal]

Since this is purely a design task (no code required), I'm assigning this to @Mayaleeeee. That said, we'll want to make it a reality down the track. As an outcome of this issue, Maya will come up with a list of other issues for implementation. Most likely good first issues. I count on you for those, @sambhavgupta0705 and @Shurtu-gal 🙏

Absolutely. Would be happy to work on them. I guess this can also be included in the v1 release tasks when @Mayaleeeee is done with it.

[Mayaleeeee]

Since this is purely a design task (no code required), I'm assigning this to @Mayaleeeee. That said, we'll want to make it a reality down the track. As an outcome of this issue, Maya will come up with a list of other issues for implementation. Most likely good first issues. I count on you for those, @sambhavgupta0705 and @Shurtu-gal 🙏

Thanks, @fmvilas

[fmvilas]

I've been told every issue on the Bounty program needs to have a draft PR. Since this is a UI and UX task (at least the part tied to the Bounty program), @Mayaleeeee, you should create a Figma file and share it here. You can create in on the AsyncAPI workspace in Figma. Let me know if you need more permissions to do it.

[aeworxet]

Or, since it is CLI, which is text-only by default, there might be a text-only (non-graphical) description of changes utilizing GitHub's terminal font (with three backticks) on

- Improving error messages
- Improving the --help command listing
- Review all commands to see if they're consistent with the CLI structure (this may cause a breaking change)
- Enhance the visual design of different elements like success messages, info messages, and error messages.

[aeworxet]

If I were doing this code-related strictly textual UI/UX design task as a non-coder, I would still use VSCode to take a look at the errors directory, catch and error messages, and usual messages. All of them are easy to grep visually because they are highlighted with different color. Some require only grammatical fixes.

Click to expand

Then, I would run different variations of the asyncapi command even on Windows to see the --help part for different commands.

And simultaneously with all this, I would be editing a large text file, which I would post here as one big comment (and update weekly) to provide a measurable deliverable for this task, with the following information:

Improving error messages

./src/commands/new/file.ts

message: 'would you like to start your new file from one of our examples?',
->
message: 'Would you like to start your new file from one of our examples?',

./src/errors/specification-file.ts

cli only supports yml ,yaml ,json extension
->
CLI only supports ".yml", ".yaml" and ".json" extensions.

Improving the --help command listing

asyncapi start --help (use difftool to see the difference between the original text and the proposed change)
->

Start AsyncAPI Studio

USAGE
  $ asyncapi start

DESCRIPTION
  Start AsyncAPI Studio

COMMANDS
  start studio starts a new local instance of Studio

Review all commands to see if they're consistent with the CLI structure (this may cause a breaking change)

Making all code parts responsible for the output of different texts follow the same rules requires rewriting portions of the source code indeed.

Enhance the visual design of different elements like success messages, info messages, and error messages.

@sambhavgupta0705 and @Shurtu-gal might exercise in ASCII art here, like I did in #555 , though emojis are not pictures but usual UTF characters so they can be embedded into the code directly, to make error messages look more attractive:

❌ Diff command does not support AsyncAPI v3 yet which was your first document

😱 You have no context file configured. Run "asyncapi config context init" to initialize it.

There might still be a need for the help of a developer to make sure all scenarios when text is outputted are tried.
Such help may be obtained with a call in #02_general or #11_contributing containing text

Attention to first-time contributors. Help with CLI needed. Possibility to make the first-time contribution.
Refer to https://github.com/asyncapi/cli/issues/872#issuecomment-1824328894 for details.

[thulieblack]

From what I understand (correct me if I'm wrong), part of this issue requires improving the design of the CLI UI/UX. This means whatever Maya is currently designing, a developer needs to implement the designs to the CLI.

This issue is a sub-task of #551, and only the design part is of the Bounty?

Question?

Will the implementation have a follow-up issue?
or
This issue requires both design and implementation since we want to improve the runtime error messages?

cc @fmvilas

[fmvilas]

This issue is both design and code. The bounty is just about design.

[fmvilas]

Copying from a private conversation with @aeworxet 👇

@Mayaleeeee —like the majority of the designers— doesn't feel comfortable with Markdown. The beginning of the process is a set of wireframes and at the end she'll have high-fidelity prototypes which may or may not be done with Markdown (most probably not). We should respect every profession dynamics instead of trying to impose dev stuff on them.

If what we're looking for is metrics to show to potential sponsors, cool, but I honestly believe that the only metric potential sponsors will care about is finished vs unfinished issues. They'll want to know that their money is actually serving a purpose. Whether someone pushes every week or rather waits a month and then pushes all at once in one week will be irrelevant for them IMHO. It will be relevant for us though, so that we understand how people are approaching these issues but for that you don't need to enforce a draft PR but just recommend it. Or just enforce it for code issues and maybe technical writing issues but not all kinds of them.

[thulieblack]

Thanks for the clarity.

What I can suggest is that Maya shares her weekly progress reports here on the issue like how we did in the Bouny trial (for progress tracking). As she progresses, she can later share the Figma board or file that she's working on.

[fmvilas]

Yeah, that should work 👌

[Mayaleeeee]

Thanks for the clarity.

What I can suggest is that Maya shares her weekly progress reports here on the issue like how we did in the Bouny trial (for progress tracking). As she progresses, she can later share the Figma board or file that she's working on.

Project Progress Overview: Weeks 1-3 Update

Hello, everyone. I apologise for the delay in providing an update on this issue.
During the first and second weeks, I focused on learning about CLI design, including the best approaches for creating a user-friendly interface, as well as the restrictions and possibilities of the terminal. I have been having weekly meetings with Fran to understand the issue better and meet twice a week.

Here are the lists of materials I have been exploring.

• When life gives you lemons, write better error messages
• Jess Archer "Unveiling Laravel Prompts" - Laracon US 2023 Nashville
• 10 Usability Heuristics for User Interface Design
• 10 design principles for delightful CLIs - Atlassian Developer Blog
• Designing Command-Lines Tools People Love

For this week
I am playing with the asyncapi validate and evaluating ways to improve it. You can view my work {WIP} and updates for this week through this Figma link.

Thank you, and have a great day!

[Mayaleeeee]

Project Progress Overview: Weeks 3&4 Update

Hello everyone,

Over the past two weeks, I have been refining the asyncapi --validate states and enhancing the clarity of error messages. I crafted six distinct states, covering valid and invalid scenarios, each with and without recommendations. You can explore these states in the attached visuals or the linked Figma file.

This week, I look forward to delving deeper into this material and exploring another command for the CLI.

Have a wonderful week ahead!

• Valid state

• Invalid state

• Valid with no recommendations

• Invalid with no recommendation

• Valid with show-recommendations

• Invalid with recommendations

cc @fmvilas

[aeworxet]

@asyncapi/bounty_team

[Mayaleeeee]

Hello Everyone.

I want to request an extension for this bounty issue.

For the past two weeks, I have been busy with exams and I could not work on it. I just resumed to working on it this week, and I would really appreciate if the deadline could be extended to 2 weeks.

Thank you.

cc @fmvilas @thulieblack @aeworxet

[fmvilas]

It's totally fine from my side. I also underestimated the length of the issue. There are lots of commands and potential errors to cover. @Mayaleeeee you're doing great progress so far (even with the exams) so I think it's fair to extend the period.

PS: But that's not for free. As a payback, you need to return the swag you won during the AsyncAPI v3 celebration 😄 😜 (I'm kidding, just in case 😄)

[aeworxet]

Bounty Issue's Timeline Extended

Complexity Level	Assignment date (by GitHub)	Start date (by BP rules)	End date (by BP rules)	Draft PR submission	Final PR submission	Final PR merge
Medium	2023-11-07	2023-11-13	2024-01-05	2023-11-24	2023-12-22	2024-01-05

Please note that the dates given represent deadlines, not specific dates, so if the goal is reached sooner, it's better.

[Mayaleeeee]

It's totally fine from my side. I also underestimated the length of the issue. There are lots of commands and potential errors to cover. @Mayaleeeee you're doing great progress so far (even with the exams) so I think it's fair to extend the period.

PS: But that's not for free. As a payback, you need to return the swag you won during the AsyncAPI v3 celebration 😄 😜 (I'm kidding, just in case 😄)

The swag that's on it's way to Nigeria already 🤣🤣😂

[Mayaleeeee]

Project Progress Overview: Week 5 Update

Hello everyone,
This week, I worked on the asyncapi --convert feature by enhancing the error messages and UI&UX. I designed five (5) different states for this feature, which include convert-same-version-state, convert-pervious-version-state, convert-next-version-state, convert-valid-state and convert-invalid-state

You can check out these states in the visuals attached or by accessing the Figma file.

• Same version
  

• Previous version
  

• Next version
  

• Valid state
  

• Invalid state
  
  

[Mayaleeeee]

Week 7 Progress Update: I took a break during week 6 for Christmas and New Year.

Hi there,
Last week, I worked on a new feature called asyncapi new. This feature includes two sub-commands: new file and glee project.

For the new file sub-command, I discovered three (3) different states with sub-states:

1. Creation

• creating a new file
• creating a new file with a different name
• a studio file
  
  
  

2. Validation

• valid state
• invalid state
  
  

3. Interaction
I'm still trying to figure out how this works, but I'll keep trying.

For the glee project sub-command, I discovered two (2) states with sub-states:

1. Creation

• with default: this involves creating a new glee project with the default name - project
• with a unique name - for instance, you have created a project with the default name, and you want to create another with a different name - unique name
  
  

2a. Error state

• error - no
• error state - yes
  
  

You can also check out the states by accessing this Figma file.

cc cc @fmvilas @thulieblack @aeworxet

[aeworxet]

AsyncAPI Maintainer (@fmvilas) was absent online in Slack for two periods of three working days in a row, so all remaining target dates of the Bounty Issue's Timeline are extended by three calendar weeks.

Bounty Issue's Timeline Extended

Complexity Level	Assignment date (by GitHub)	Start date (by BP rules)	End date (by BP rules)	Draft PR submission	Final PR submission	Final PR merge
Medium	2023-11-07	2023-11-13	2024-01-26	2023-11-24	2023-12-22	2024-01-26

Please note that the dates given represent deadlines, not specific dates, so if the goal is reached sooner, it's better.

[aeworxet]

@Mayaleeeee, please provide an update on the Bounty Issue.

[Mayaleeeee]

@Mayaleeeee, please provide an update on the Bounty Issue.

Hello @aeworxet, I apologize for not providing an update on the project. Let me explain what happened. Last week, I worked on a generator command that was more complex and time-consuming than I initially thought. Unfortunately, I couldn't complete it by the end of the week, and I didn't get a chance to give an update. However, I have been working on it this week, and once it's finished, I'll provide a comprehensive update on it.

Thank you for your patience and understanding.

[Mayaleeeee]

Hello, everyone. I am pleased to announce that I have completed this issue. Below you will find the proposal for the CLI command.
cc @fmvilas @aeworxet

Proposal for the CLI Command

STRUCTURE

Every CLI command should follow a consistent structure for successful and errored results.

1. Successful Result:

• Feedback
  A message indicating the operation was successful.

• Additional Content
  Additional information is requested via flags, e.g., --show-recommendations on the validate command.

• Next Steps or Documentation Link
  Offer guidance on the next steps or link to detailed instructions.

2. Errored Result

• Feedback:
  Clear and informative error message explaining what went wrong.
• Additional Content
  Extra information that may help to give some context about the error
• Next Steps or Documentation Link
  Include links to external documentation providing detailed information on resolving the issue.

3. Missing Information

• Feedback:
  Communicate that the required information is missing.
• Educate the users:
  Provide an example of how to provide the missing information correctly and educate the users so they don't make the same mistakes again.
• Prompt for Missing Information
  Ask for the missing information with a prompt, suggesting sensible default values.

Consistent Message Formats for CLI Responses

These formats are proposed to provide users with informative and easy-to-understand feedback, whether the operation is successful, encounters an error, or requires additional information.

1. Success Messages
The examples include a concise message indicating success, any additional content prompted by flags, next steps or a link to detailed documentation.

• Example 1 (with an addition flag option)
  

• Example 2
  

2. Error Messages
In case of an error, users should receive a clear and informative message explaining what went wrong and potential ways to fix it. This example showcases a typical error message with additional information and a link to external documentation for further assistance.

• Example
  

3. Prompt
These examples prompt the user for necessary information in a clear and concise manner, guiding them on what input is expected.

• Example 1
  

• Example 2
  

4. Highlighted Words
Bold, italicized, or coloured text can emphasize specific words and help users quickly identify the message's nature.

• Example 1
  

• Example 2
  

5. Code example

CLI Command Recommendations

Here are recommendations for improving the CLI commands: validate, generate models (--raw), generate models & fromTemplate to enhance the user experience.

asyncapi validate

• Introducing the --show-recommendations flag to this command ensures a cleaner and less cluttered interface, with recommendations displayed only when users explicitly request them.

asyncapi generate models

• Introducing the --raw flag allows users to view the generated models directly in the terminal, promoting a cleaner and more straightforward interface for seamless interaction.

asyncapi generate models and fromTemplate

• Reverse the order of parameters in the asyncapi generate fromTemplate command to match the asyncapi generate models command for a more consistent UX. e.g asyncapi generate {models or fromTemplate} {template or language} {file}
• Choose a consistent and precise name for the AsyncAPI file parameter, emphasizing that it can be either a file or a URL.
  e.g AsyncAPISource
• Consider making the AsyncAPI file parameter optional in the asyncapi generate fromTemplate and asyncapi generate models command.

generic error message for all the commands

• Implementing this will result in a cleaner and less cluttered UI, making it easier to understand.
  

Figma File

To view the designs, please refer to this Figma File

[Shurtu-gal]

Just a suggestion @Mayaleeeee. Do you think these can be aligned?

Also are emojis really needed, as it can become a pain if the output is piped into some other command.

Any thoughts @fmvilas?

[fmvilas]

Yeah, agree that there are too many emojis 😅 Making it hard to read the messages themselves. I think @Mayaleeeee should come up with a different design but using the same structure IMHO. In any case, this is not part of the issue itself. I think Maya did a great job analyzing the UX and came up with some design guidelines. Colors, emojis yes or no, and things like that can be worked later on too, most probably as part of a CLI design system.

I won't worry about piping to other commands as these are the kind of messages that are meant for the user to see in the screen. There are ways to detect if a command is being piped or if there isn't any use behind (like in a CI/CD). We can simplify this output for this cases.

[fmvilas]

@aeworxet bounty completed 💪 you can go ahead and instruct @Mayaleeeee how to get the payment.

[aeworxet]

Design part of the

Bounty Issue Completed 🎉

Please go to the AsyncAPI's OpenCollective page and submit an invoice for USD 200.00 with the subject Bounty cli#872, tag bounty.

[Amzani]

I love this initiative, thanks @Mayaleeeee for this amazing work, I suggest taking the next iteration under the umbrella of the new DX working group
I'll split different tasks in #1214

[Mayaleeeee]

I love this initiative, thanks @Mayaleeeee for this amazing work, I suggest taking the next iteration under the umbrella of the new DX working group
I'll split different tasks in #1214

Thank you, @Amzani. I owe it all to @fmvilas for his guidance and support. 🙌🙌🙌

[Amzani]

Implementation part is completed in #1214