Feature: CLI help screen updates #344

New issue

Closed

opened 2025-07-29 00:06:28 +00:00 by jamie · 4 comments

jamie commented

2025-07-29 00:06:28 +00:00

(Migrated from git.hazaar.io)

Problem Statement

The Hazaar CLI framework allows developers to build CLI tools with a module/command structure. While help screens work correctly when using explicit help commands (e.g., toolname help module command), running incomplete commands like toolname module results in an error. This is confusing for users and inconsistent with common CLI UX practices. Additionally, when a module command is invoked without required options, the CLI throws an error without showing relevant help, which reduces usability.

Who will benefit?

Developers using Hazaar's CLI framework to build tools.
End users interacting with CLI tools built on Hazaar.
General user experience improvements across all CLI tools built with the framework.

Benefits and risks

Benefits:

Better user experience by gracefully handling partial or incorrect input.
Makes CLI tools more intuitive and self-documenting.
Aligns behavior with industry standards (e.g., Git, Docker, etc.).

Risks:

Minor changes to CLI control flow may introduce edge cases if not carefully implemented.
Slight performance cost due to additional help screen logic when validating arguments.

Proposed solution

When a user runs toolname module without specifying a command:
- Instead of throwing an error, display the help screen for that module.
When a user runs toolname module command but omits required options:
- Display an error explaining the missing required option(s).
- Immediately follow the error with the help screen for that specific command.
Ensure that help screen display logic is centralized so these behaviors remain consistent across all modules and commands.

Examples

Current behavior:

$ toolname foo
Error: No command specified for module foo.

Proposed behavior:

$ toolname foo
[ Help screen for module 'foo' ]

Current behavior:

$ toolname foo bar
Error: Missing required option '--path'

Proposed behavior:

$ toolname foo bar
Error: Missing required option '--path'

[ Help screen for command 'foo bar' ]

Priority/Severity

High (This will bring a huge increase in performance/productivity/usability/legislative cover)
Medium (This will bring a good increase in performance/productivity/usability)
Low (anything else e.g., trivial, minor improvements)

## Problem Statement The Hazaar CLI framework allows developers to build CLI tools with a module/command structure. While help screens work correctly when using explicit `help` commands (e.g., `toolname help module command`), running incomplete commands like `toolname module` results in an error. This is confusing for users and inconsistent with common CLI UX practices. Additionally, when a module command is invoked without required options, the CLI throws an error without showing relevant help, which reduces usability. ## Who will benefit? - Developers using Hazaar's CLI framework to build tools. - End users interacting with CLI tools built on Hazaar. - General user experience improvements across all CLI tools built with the framework. ## Benefits and risks ### Benefits: - Better user experience by gracefully handling partial or incorrect input. - Makes CLI tools more intuitive and self-documenting. - Aligns behavior with industry standards (e.g., Git, Docker, etc.). ### Risks: - Minor changes to CLI control flow may introduce edge cases if not carefully implemented. - Slight performance cost due to additional help screen logic when validating arguments. ## Proposed solution - When a user runs `toolname module` without specifying a command: - Instead of throwing an error, display the help screen for that module. - When a user runs `toolname module command` but omits required options: - Display an error explaining the missing required option(s). - Immediately follow the error with the help screen for that specific command. - Ensure that help screen display logic is centralized so these behaviors remain consistent across all modules and commands. ## Examples ### Current behavior: ```bash $ toolname foo Error: No command specified for module foo. ``` ### Proposed behavior: ```bash $ toolname foo [ Help screen for module 'foo' ] ``` ### Current behavior: ```bash $ toolname foo bar Error: Missing required option '--path' ``` ### Proposed behavior: ```bash $ toolname foo bar Error: Missing required option '--path' [ Help screen for command 'foo bar' ] ``` ## Priority/Severity - [ ] High (This will bring a huge increase in performance/productivity/usability/legislative cover) - [x] Medium (This will bring a good increase in performance/productivity/usability) - [ ] Low (anything else e.g., trivial, minor improvements)

jamie commented

2025-07-29 00:06:29 +00:00

(Migrated from git.hazaar.io)

assigned to @jamie

jamie commented

2025-07-29 05:15:54 +00:00

(Migrated from git.hazaar.io)

created branch 344-feature-cli-help-screen-updates to address this issue

created branch [`344-feature-cli-help-screen-updates`](/hazaar/framework/-/compare/master...344-feature-cli-help-screen-updates) to address this issue

jamie commented

2025-07-29 05:16:52 +00:00

(Migrated from git.hazaar.io)

mentioned in merge request !236