[FEATURE] Standardized Output Formatting and Error Reporting for CLI Commands

[shwetd19]

Why do we need this improvement?

Problem Overview

Right now, the AsyncAPI CLI's output formatting and error messages feel a bit inconsistent across different commands. This can make it harder for users to:

• Quickly understand if a command was successful or failed, and what key information they need.
• Troubleshoot issues when something goes wrong, since error messages aren’t always clear or actionable.
• Use the CLI in automated scripts, as the output isn’t always predictable or easy to parse.

Proposed Solution

To make the CLI more user-friendly and script-friendly, we could standardize how output and errors are handled across all commands. Some improvements might include:

• Consistent Output Format: Choosing a clear, structured format (like JSON, YAML, or a human-readable table) that works well for both humans and automation.
• Clearer Error Messages: Providing more detailed and helpful error messages, including:
  • Specific error details (e.g., “Invalid file format” or “Missing required field”).
  • Suggested solutions or troubleshooting steps.
  • Links to relevant documentation.
• Standardized Exit Codes: Using consistent exit codes so scripts can reliably interpret command results.
• Better Logging: Considering a logging library (e.g., Winston, Zap) for more structured and configurable logging.

Would love to hear thoughts from the maintainers on this!

How will this change help?

• Better user experience: Users can easily interpret results and errors without confusion.
• Easier debugging: More informative error messages will help users troubleshoot issues faster.
• Improved automation: Predictable output formats and standardized exit codes will make it easier to integrate the CLI into scripts and workflows.

Screenshots

No response

How could it be implemented/designed?

• Standardize output format (JSON, YAML, or a structured human-readable format) for all commands.
• Enhance error messages by including specific details, troubleshooting steps, and links to documentation.
• Use consistent exit codes to indicate success, failure, and different types of errors.
• Integrate a logging library (like Winston or Zap) for better structured and configurable logs.

🚧 Breaking changes

Yes

👀 Have you checked for similar open issues?

• I checked and didn't find a similar issue

🏢 Have you read the Contributing Guidelines?

• I have read the Contributing Guidelines

Are you willing to work on this issue?

Yes I am willing to submit a PR!

[github-actions]

Welcome to AsyncAPI. Thanks a lot for reporting your first issue. Please check out our contributors guide and the instructions about a basic recommended setup useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.