bug(cli): multiple registered commands missing from --help common commands list #2259

Open
opened 2026-04-03 11:39:34 +00:00 by hamza.khyari · 2 comments
Member

Metadata

  • Commit Message: fix(cli): add missing commands to --help common commands list
  • Branch: fix/cli-help-missing-commands

Background and Context

agents --help displays a hardcoded "Common commands" list in _print_basic_help() (src/cleveragents/cli/main.py:251-265). Several registered subcommands are missing from this list, making them undiscoverable to users.

Current Behavior

agents --help lists 14 commands. The following registered commands are not listed:

  • action — Manage actions (reusable plan templates)
  • resource — Resource management
  • skill — Skill management
  • validation — Validation management
  • invariant — Invariant management
  • server — Server connection management
  • lsp — Language Server Protocol operations
  • config — Configuration management

Users must guess these commands exist or read source code to find them.

Expected Behavior

All user-facing subcommands are listed in agents --help, grouped logically (e.g. "Plan lifecycle", "Resource management", "Configuration").

Acceptance Criteria

  • action listed in --help output
  • resource listed in --help output
  • skill listed in --help output
  • validation listed in --help output
  • invariant listed in --help output
  • server listed in --help output
  • lsp listed in --help output (if user-facing)
  • config listed in --help output (if user-facing)
  • Commands grouped logically with section headers

Subtasks

  • Update _print_basic_help() in src/cleveragents/cli/main.py to include missing commands
  • Group commands by category (plan lifecycle, resource, configuration, etc.)
  • Tests (Behave): Verify all registered commands appear in --help output
  • Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

  • All subtasks above are completed and checked off.
  • A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly.
  • The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
  • The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
## Metadata - **Commit Message**: `fix(cli): add missing commands to --help common commands list` - **Branch**: `fix/cli-help-missing-commands` ## Background and Context `agents --help` displays a hardcoded "Common commands" list in `_print_basic_help()` (`src/cleveragents/cli/main.py:251-265`). Several registered subcommands are missing from this list, making them undiscoverable to users. ## Current Behavior `agents --help` lists 14 commands. The following registered commands are **not listed**: - `action` — Manage actions (reusable plan templates) - `resource` — Resource management - `skill` — Skill management - `validation` — Validation management - `invariant` — Invariant management - `server` — Server connection management - `lsp` — Language Server Protocol operations - `config` — Configuration management Users must guess these commands exist or read source code to find them. ## Expected Behavior All user-facing subcommands are listed in `agents --help`, grouped logically (e.g. "Plan lifecycle", "Resource management", "Configuration"). ## Acceptance Criteria - [ ] `action` listed in `--help` output - [ ] `resource` listed in `--help` output - [ ] `skill` listed in `--help` output - [ ] `validation` listed in `--help` output - [ ] `invariant` listed in `--help` output - [ ] `server` listed in `--help` output - [ ] `lsp` listed in `--help` output (if user-facing) - [ ] `config` listed in `--help` output (if user-facing) - [ ] Commands grouped logically with section headers ## Subtasks - [ ] Update `_print_basic_help()` in `src/cleveragents/cli/main.py` to include missing commands - [ ] Group commands by category (plan lifecycle, resource, configuration, etc.) - [ ] Tests (Behave): Verify all registered commands appear in --help output - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done.
Owner

Issue reviewed and acknowledged.

This is a well-documented bug report with clear current vs. expected behavior and a specific root cause location (_print_basic_help() in src/cleveragents/cli/main.py:251-265). The issue body follows CONTRIBUTING.md format with proper Metadata, Subtasks, and Definition of Done sections.

Triage summary:

  • State: Verified (confirmed — the bug is clearly reproducible and the root cause is identified)
  • Priority: Medium (confirmed — discoverability issue, not a crash or data loss)
  • Milestone: Not currently assigned. This is a CLI usability bug. Recommend assigning to v3.6.0 (M7: Advanced Concepts) since it affects the CLI user experience and v3.6.0 includes CLI-related work.
  • Parent Epic: Not linked. This should be linked to a CLI usability or CLI polish epic if one exists. Flagging as potentially orphan — needs a parent epic.

The issue is well-formed and ready for implementation.


Automated by CleverAgents Bot
Supervisor: Human Liaison | Agent: ca-human-liaison

Issue reviewed and acknowledged. This is a well-documented bug report with clear current vs. expected behavior and a specific root cause location (`_print_basic_help()` in `src/cleveragents/cli/main.py:251-265`). The issue body follows CONTRIBUTING.md format with proper Metadata, Subtasks, and Definition of Done sections. **Triage summary:** - **State**: Verified (confirmed — the bug is clearly reproducible and the root cause is identified) - **Priority**: Medium (confirmed — discoverability issue, not a crash or data loss) - **Milestone**: Not currently assigned. This is a CLI usability bug. Recommend assigning to **v3.6.0** (M7: Advanced Concepts) since it affects the CLI user experience and v3.6.0 includes CLI-related work. - **Parent Epic**: Not linked. This should be linked to a CLI usability or CLI polish epic if one exists. Flagging as potentially orphan — needs a parent epic. The issue is well-formed and ready for implementation. --- **Automated by CleverAgents Bot** Supervisor: Human Liaison | Agent: ca-human-liaison
Owner

MoSCoW classification: MoSCoW/Should Have

Rationale: This bug affects the CLI help output — multiple registered commands are missing from the --help common commands list. This is a user-facing discoverability issue that degrades the developer experience.

Why Should Have (not Must Have):

  • The commands themselves still work — only the help listing is incomplete
  • This does not block core functionality or milestone delivery
  • Users can still discover commands through other means (documentation, tab completion)

Why Should Have (not Could Have):

  • Help output is a primary discovery mechanism for CLI tools
  • Missing commands in --help creates a poor first impression and confuses new users
  • The fix is likely straightforward (registration/display logic bug)
  • Priority/Medium is appropriate — should be fixed but not blocking

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner

MoSCoW classification: **MoSCoW/Should Have** Rationale: This bug affects the CLI help output — multiple registered commands are missing from the `--help` common commands list. This is a user-facing discoverability issue that degrades the developer experience. **Why Should Have (not Must Have):** - The commands themselves still work — only the help listing is incomplete - This does not block core functionality or milestone delivery - Users can still discover commands through other means (documentation, tab completion) **Why Should Have (not Could Have):** - Help output is a primary discovery mechanism for CLI tools - Missing commands in `--help` creates a poor first impression and confuses new users - The fix is likely straightforward (registration/display logic bug) - Priority/Medium is appropriate — should be fixed but not blocking --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner
Sign in to join this conversation.
No milestone
No project
No assignees
3 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core#2259
No description provided.