cleveragents/cleveragents-core

Fork 3

UAT: `--format` help text inconsistency — `color` format omitted from per-command `_FORMAT_HELP` strings but present in `constants.py` #5024

New issue

Open

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

HAL9000 commented

2026-04-09 00:49:11 +00:00

Owner

Bug Report

Feature Area: CLI Commands — --help output accuracy
Severity: Low
Discovered by: UAT Testing (uat-pool-1, worker: CLI Commands)

What Was Tested

Reviewed --format option help text across all CLI command modules.

Expected Behavior (from spec)

The --format option should consistently document all supported output formats. The canonical list defined in constants.py is:

VALID_FORMATS: tuple[str, ...] = ("json", "yaml", "plain", "table", "rich", "color")
FORMAT_HELP: str = (
    "Output format: json, yaml, plain, table, rich, or color (default: rich)"
)

Actual Behavior

Individual command modules define their own _FORMAT_HELP constant that omits color:

src/cleveragents/cli/commands/actor.py:

_FORMAT_HELP = "Output format: json, yaml, plain, table, or rich (default: rich)"

src/cleveragents/cli/commands/action.py:

_FORMAT_HELP = "Output format: json, yaml, plain, table, or rich (default: rich)"

src/cleveragents/cli/commands/session.py:

_FORMAT_HELP = "Output format: json, yaml, plain, table, or rich (default: rich)"

This means agents actor list --help shows "json, yaml, plain, table, or rich" while the actual OutputFormat enum and format_output() function both support color as a valid format.

Code Location

src/cleveragents/cli/constants.py — canonical FORMAT_HELP (correct)
src/cleveragents/cli/commands/actor.py — local _FORMAT_HELP (missing color)
src/cleveragents/cli/commands/action.py — local _FORMAT_HELP (missing color)
src/cleveragents/cli/commands/session.py — local _FORMAT_HELP (missing color)

Steps to Reproduce

agents actor list --help
# Shows: "Output format: json, yaml, plain, table, or rich (default: rich)"
# Missing: "color"

agents actor list --format color
# Works fine (color is supported), but --help doesn't mention it

Impact

Users reading --help output will not know that --format color is available. This is a documentation/UX inconsistency.

Suggested Fix

Replace local _FORMAT_HELP definitions with the canonical constant from constants.py:

# In actor.py, action.py, session.py — remove local _FORMAT_HELP and import:
from cleveragents.cli.constants import FORMAT_HELP as _FORMAT_HELP

Or update all local _FORMAT_HELP strings to include color.

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

## Bug Report **Feature Area:** CLI Commands — `--help` output accuracy **Severity:** Low **Discovered by:** UAT Testing (uat-pool-1, worker: CLI Commands) --- ## What Was Tested Reviewed `--format` option help text across all CLI command modules. ## Expected Behavior (from spec) The `--format` option should consistently document all supported output formats. The canonical list defined in `constants.py` is: ```python VALID_FORMATS: tuple[str, ...] = ("json", "yaml", "plain", "table", "rich", "color") FORMAT_HELP: str = ( "Output format: json, yaml, plain, table, rich, or color (default: rich)" ) ``` ## Actual Behavior Individual command modules define their own `_FORMAT_HELP` constant that **omits `color`**: **`src/cleveragents/cli/commands/actor.py`:** ```python _FORMAT_HELP = "Output format: json, yaml, plain, table, or rich (default: rich)" ``` **`src/cleveragents/cli/commands/action.py`:** ```python _FORMAT_HELP = "Output format: json, yaml, plain, table, or rich (default: rich)" ``` **`src/cleveragents/cli/commands/session.py`:** ```python _FORMAT_HELP = "Output format: json, yaml, plain, table, or rich (default: rich)" ``` This means `agents actor list --help` shows `"json, yaml, plain, table, or rich"` while the actual `OutputFormat` enum and `format_output()` function both support `color` as a valid format. ## Code Location - `src/cleveragents/cli/constants.py` — canonical `FORMAT_HELP` (correct) - `src/cleveragents/cli/commands/actor.py` — local `_FORMAT_HELP` (missing `color`) - `src/cleveragents/cli/commands/action.py` — local `_FORMAT_HELP` (missing `color`) - `src/cleveragents/cli/commands/session.py` — local `_FORMAT_HELP` (missing `color`) ## Steps to Reproduce ```bash agents actor list --help # Shows: "Output format: json, yaml, plain, table, or rich (default: rich)" # Missing: "color" agents actor list --format color # Works fine (color is supported), but --help doesn't mention it ``` ## Impact Users reading `--help` output will not know that `--format color` is available. This is a documentation/UX inconsistency. ## Suggested Fix Replace local `_FORMAT_HELP` definitions with the canonical constant from `constants.py`: ```python # In actor.py, action.py, session.py — remove local _FORMAT_HELP and import: from cleveragents.cli.constants import FORMAT_HELP as _FORMAT_HELP ``` Or update all local `_FORMAT_HELP` strings to include `color`. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added the

labels

2026-04-09 00:50:28 +00:00

HAL9000 commented

2026-04-09 01:02:10 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Low — Minor spec deviation; undocumented option or cosmetic inconsistency
Milestone: Not assigned (backlog)
Story Points: 2 — S
MoSCoW: Could Have — Minor polish item; does not block core functionality

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Low — Minor spec deviation; undocumented option or cosmetic inconsistency - **Milestone**: Not assigned (backlog) - **Story Points**: 2 — S - **MoSCoW**: Could Have — Minor polish item; does not block core functionality --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner

HAL9000 referenced this issue

2026-04-09 02:56:12 +00:00

[AUTO-UAT-POOL] UAT Testing Report (Cycle 4) #5160

HAL9000 referenced this issue

2026-04-09 03:09:06 +00:00

[AUTO-UAT-POOL] UAT Testing Report (Cycle 5) #5200

HAL9000 added a new dependency

2026-04-09 04:55:51 +00:00

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

HAL9000 added this to the v3.2.0 milestone

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