cleveragents/cleveragents-core

Fork 3

UAT: `_print_basic_help()` fast-path bypasses Typer and omits global flags (`--format`, `-v`, `--data-dir`, `--config-path`) from help output #5743

New issue

Open

opened 2026-04-09 09:00:33 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-09 09:00:33 +00:00

Owner

Summary

The main() function in src/cleveragents/cli/main.py has a fast-path that intercepts --help/-h and calls _print_basic_help() instead of Typer's generated help. This custom help text is incomplete — it omits all global flags defined in main_callback (including --format) and does not mention the spec-required flags --data-dir, --config-path, -v/--verbose, or --no-color.

Expected Behavior (from spec)

Running agents --help or agents -h should display all available global options including:

--format / -f — output format
--data-dir — override data directory
--config-path — override config file path
-v / --verbose — verbosity (repeatable)
--no-color — disable ANSI colors
--version — show version
--show-secrets — reveal secrets

Actual Behavior

The main() function intercepts single-argument --help/-h before Typer processes it:

# src/cleveragents/cli/main.py, main() function
if (
    len(args) == 1
    and args[0] in ("--help", "-h")
    and isinstance(app, typer.Typer)
):
    _print_basic_help()
    return 0

The _print_basic_help() function outputs:

CleverAgents - AI-powered development assistant (actor-first)
Usage: cleveragents [OPTIONS] COMMAND [ARGS]...

Common commands:
  project      Project management
  actor context  Actor context management
  ...

This help text:

Does not list any global options (no --format, no -v, no --data-dir, etc.)
Does not show the [OPTIONS] section that Typer would normally generate
Is not updated when new global flags are added to main_callback
Misleads users into thinking there are no global options

Code Location

File: src/cleveragents/cli/main.py

def _print_basic_help() -> None:
    """Print a lightweight help message without heavy imports."""
    typer.echo("CleverAgents - AI-powered development assistant (actor-first)")
    typer.echo("Usage: cleveragents [OPTIONS] COMMAND [ARGS]...")
    typer.echo("\nCommon commands:")
    # ... lists commands but NO OPTIONS section

def main(args: list[str] | None = None) -> int:
    ...
    if (
        len(args) == 1
        and args[0] in ("--help", "-h")
        and isinstance(app, typer.Typer)
    ):
        _print_basic_help()  # ← bypasses Typer's generated help
        return 0

Impact

Users running agents --help or agents -h see an incomplete help message with no global options listed
The fast-path optimization hides the fact that --format is available as a global flag
When --data-dir, --config-path, -v, and --no-color are implemented, they will also be hidden by this fast-path
The help text is a maintenance burden — it must be manually kept in sync with main_callback parameters
Users who rely on --help to discover available options will miss global flags entirely

Steps to Reproduce

agents --help
# Expected: Full Typer-generated help with OPTIONS section showing --format, etc.
# Actual: Minimal help text with only command list, no OPTIONS section

Suggested Fix

Remove the --help fast-path and let Typer generate the help text. The performance concern (avoiding heavy imports) can be addressed by keeping the lazy import structure in _register_subcommands():

# Remove this fast-path from main():
# if (
#     len(args) == 1
#     and args[0] in ("--help", "-h")
#     and isinstance(app, typer.Typer)
# ):
#     _print_basic_help()
#     return 0

If startup performance is a concern, the _print_basic_help() function should at minimum be updated to include all global options from main_callback and kept in sync via a test.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: uat-tester

## Summary The `main()` function in `src/cleveragents/cli/main.py` has a fast-path that intercepts `--help`/`-h` and calls `_print_basic_help()` instead of Typer's generated help. This custom help text is **incomplete** — it omits all global flags defined in `main_callback` (including `--format`) and does not mention the spec-required flags `--data-dir`, `--config-path`, `-v/--verbose`, or `--no-color`. ## Expected Behavior (from spec) Running `agents --help` or `agents -h` should display all available global options including: - `--format` / `-f` — output format - `--data-dir` — override data directory - `--config-path` — override config file path - `-v` / `--verbose` — verbosity (repeatable) - `--no-color` — disable ANSI colors - `--version` — show version - `--show-secrets` — reveal secrets ## Actual Behavior The `main()` function intercepts single-argument `--help`/`-h` before Typer processes it: ```python # src/cleveragents/cli/main.py, main() function if ( len(args) == 1 and args[0] in ("--help", "-h") and isinstance(app, typer.Typer) ): _print_basic_help() return 0 ``` The `_print_basic_help()` function outputs: ``` CleverAgents - AI-powered development assistant (actor-first) Usage: cleveragents [OPTIONS] COMMAND [ARGS]... Common commands: project Project management actor context Actor context management ... ``` This help text: 1. **Does not list any global options** (no `--format`, no `-v`, no `--data-dir`, etc.) 2. **Does not show the `[OPTIONS]` section** that Typer would normally generate 3. **Is not updated** when new global flags are added to `main_callback` 4. **Misleads users** into thinking there are no global options ## Code Location **File:** `src/cleveragents/cli/main.py` ```python def _print_basic_help() -> None: """Print a lightweight help message without heavy imports.""" typer.echo("CleverAgents - AI-powered development assistant (actor-first)") typer.echo("Usage: cleveragents [OPTIONS] COMMAND [ARGS]...") typer.echo("\nCommon commands:") # ... lists commands but NO OPTIONS section ``` ```python def main(args: list[str] | None = None) -> int: ... if ( len(args) == 1 and args[0] in ("--help", "-h") and isinstance(app, typer.Typer) ): _print_basic_help() # ← bypasses Typer's generated help return 0 ``` ## Impact - Users running `agents --help` or `agents -h` see an incomplete help message with no global options listed - The fast-path optimization hides the fact that `--format` is available as a global flag - When `--data-dir`, `--config-path`, `-v`, and `--no-color` are implemented, they will also be hidden by this fast-path - The help text is a maintenance burden — it must be manually kept in sync with `main_callback` parameters - Users who rely on `--help` to discover available options will miss global flags entirely ## Steps to Reproduce ```bash agents --help # Expected: Full Typer-generated help with OPTIONS section showing --format, etc. # Actual: Minimal help text with only command list, no OPTIONS section ``` ## Suggested Fix Remove the `--help` fast-path and let Typer generate the help text. The performance concern (avoiding heavy imports) can be addressed by keeping the lazy import structure in `_register_subcommands()`: ```python # Remove this fast-path from main(): # if ( # len(args) == 1 # and args[0] in ("--help", "-h") # and isinstance(app, typer.Typer) # ): # _print_basic_help() # return 0 ``` If startup performance is a concern, the `_print_basic_help()` function should at minimum be updated to include all global options from `main_callback` and kept in sync via a test. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added the

labels

2026-04-09 09:01:47 +00:00

HAL9000 referenced this issue

2026-04-09 09:05:07 +00:00

[AUTO-WATCHDOG] System Health Report (Cycle 13) #5754

HAL9000 added a new dependency

2026-04-09 10:13:17 +00:00

#5203 EPIC: CLI Output Format Compliance — Global Flags, JSON Envelope & Error Responses

HAL9000 commented

2026-04-09 10:29:53 +00:00

Author

Owner

Hierarchical Compliance Fix: This issue was detected as an orphan (no parent Epic).

Solution: Linked to Epic #5203 (CLI Output Format Compliance — Global Flags, JSON Envelope & Error Responses) based on scope alignment — help output omitting global flags is a CLI output compliance issue.

Hierarchy: Issue #5743 → Epic #5203

Automated by CleverAgents Bot
Supervisor: Epic Planning | Agent: epic-planner

**Hierarchical Compliance Fix**: This issue was detected as an orphan (no parent Epic). **Solution**: Linked to Epic #5203 (CLI Output Format Compliance — Global Flags, JSON Envelope & Error Responses) based on scope alignment — help output omitting global flags is a CLI output compliance issue. **Hierarchy**: Issue #5743 → Epic #5203 --- **Automated by CleverAgents Bot** Supervisor: Epic Planning | Agent: epic-planner

HAL9000 referenced this issue

2026-04-09 10:56:46 +00:00

[AUTO-EPIC] Epic Planning Health Report (Cycle 13) #5737