cleveragents/cleveragents-core

Fork 3

UAT: Global `-v/--verbose` repeatable flag missing from `main_callback` — spec requires count-based verbosity (ERROR→WARN→INFO→DEBUG→TRACE) #5730

New issue

Open

opened 2026-04-09 08:52:29 +00:00 by HAL9000 · 2 comments

HAL9000 commented

2026-04-09 08:52:29 +00:00

Owner

Summary

The CLI specification (ADR-021 §Global CLI Flags, spec Command Synopsis) requires a repeatable global -v flag (-v through -vvvvv) that controls verbosity levels from ERROR to TRACE. This is not implemented as a global flag in main_callback. Additionally, the build shortcut command defines a conflicting non-repeatable --verbose/-v boolean flag.

Expected Behavior (from spec)

Per the specification Command Synopsis:

agents|cleveragents  [--data-dir <DATA_PATH>] [--config-path <CONFIG_PATH>]
                     [--format (rich|color|table|plain|json|yaml)]
                     [-v...]  <COMMAND> [<ARGS>...]

Per ADR-021 §Global CLI Flags table:

Flag	Description
`-v` through `-vvvvv`	Verbosity (ERROR → WARN → INFO → DEBUG → TRACE)

Per ADR-021 §Constraints:

Log output from -v flags goes to stderr (or the configured core.log.terminal-stream), never to stdout, to avoid contaminating structured output.

The verbosity levels should map as:

(no -v) → ERROR/FATAL only
-v → WARN
-vv → INFO
-vvv → DEBUG
-vvvv → TRACE

Actual Behavior

1. `main_callback` has no `-v` flag at all

The main_callback in src/cleveragents/cli/main.py does not define any verbosity parameter. The configure_structlog(log_level="WARNING") call is hardcoded — there is no way to increase verbosity via a global CLI flag.

2. `build` command defines a conflicting non-repeatable `--verbose/-v`

The build shortcut command (line ~529) defines:

verbose: Annotated[
    bool, typer.Option("--verbose", "-v", help="Show detailed output")
] = False,

This is a boolean flag (not repeatable), and it uses the -v short form. This conflicts with the spec's global repeatable -v flag and would cause argument parsing ambiguity if the global flag were added.

3. `actor run` and `actor` commands have local `-v` (count-based) but not global

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

verbose: Annotated[int, typer.Option("--verbose", "-v", count=True)] = 0,

This is correctly count-based but is local to the actor run subcommand, not global.

Code Locations

Missing global flag: src/cleveragents/cli/main.py, main_callback function
Conflicting flag: src/cleveragents/cli/main.py, build command (line ~529)
Correct local implementation (reference): src/cleveragents/cli/commands/actor.py line 82

Impact

Users cannot increase log verbosity for debugging any command (e.g., agents -vvv plan list to see DEBUG logs)
The -v short flag on build conflicts with the intended global flag semantics
Log output is permanently suppressed to WARNING level with no user override
The agents --help output does not show -v as a global option
Debugging production issues requires modifying environment variables or config files instead of a simple -v flag

Steps to Reproduce

# This should show DEBUG logs but fails with "No such option: -v"
agents -vvv version

# This should show WARN logs but fails with "No such option: -v"  
agents -v plan list

# This works but is a boolean flag, not repeatable (wrong semantics)
agents build -v

Suggested Fix

Add a count-based -v to main_callback:

@app.callback()
def main_callback(
    ctx: typer.Context,
    ...
    verbose: Annotated[
        int,
        typer.Option("--verbose", "-v", count=True, help="Increase verbosity (-v WARN, -vv INFO, -vvv DEBUG, -vvvv TRACE)"),
    ] = 0,
) -> None:
    _VERBOSITY_MAP = {0: "ERROR", 1: "WARNING", 2: "INFO", 3: "DEBUG", 4: "TRACE"}
    log_level = _VERBOSITY_MAP.get(verbose, "TRACE")
    configure_structlog(log_level=log_level)
    ctx.obj["verbose"] = verbose

Remove the -v short form from the build command's --verbose flag (or rename it to --show-details) to avoid conflict with the global flag.

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

## Summary The CLI specification (ADR-021 §Global CLI Flags, spec Command Synopsis) requires a **repeatable** global `-v` flag (`-v` through `-vvvvv`) that controls verbosity levels from ERROR to TRACE. This is **not implemented** as a global flag in `main_callback`. Additionally, the `build` shortcut command defines a conflicting non-repeatable `--verbose/-v` boolean flag. ## Expected Behavior (from spec) Per the specification Command Synopsis: ``` agents|cleveragents [--data-dir <DATA_PATH>] [--config-path <CONFIG_PATH>] [--format (rich|color|table|plain|json|yaml)] [-v...] <COMMAND> [<ARGS>...] ``` Per ADR-021 §Global CLI Flags table: | Flag | Description | |------|-------------| | `-v` through `-vvvvv` | Verbosity (ERROR → WARN → INFO → DEBUG → TRACE) | Per ADR-021 §Constraints: > Log output from `-v` flags goes to stderr (or the configured `core.log.terminal-stream`), never to stdout, to avoid contaminating structured output. The verbosity levels should map as: - (no `-v`) → ERROR/FATAL only - `-v` → WARN - `-vv` → INFO - `-vvv` → DEBUG - `-vvvv` → TRACE ## Actual Behavior ### 1. `main_callback` has no `-v` flag at all The `main_callback` in `src/cleveragents/cli/main.py` does not define any verbosity parameter. The `configure_structlog(log_level="WARNING")` call is hardcoded — there is no way to increase verbosity via a global CLI flag. ### 2. `build` command defines a conflicting non-repeatable `--verbose/-v` The `build` shortcut command (line ~529) defines: ```python verbose: Annotated[ bool, typer.Option("--verbose", "-v", help="Show detailed output") ] = False, ``` This is a **boolean flag** (not repeatable), and it uses the `-v` short form. This conflicts with the spec's global repeatable `-v` flag and would cause argument parsing ambiguity if the global flag were added. ### 3. `actor run` and `actor` commands have local `-v` (count-based) but not global `src/cleveragents/cli/commands/actor.py` line 82: ```python verbose: Annotated[int, typer.Option("--verbose", "-v", count=True)] = 0, ``` This is correctly count-based but is **local to the `actor run` subcommand**, not global. ## Code Locations - **Missing global flag:** `src/cleveragents/cli/main.py`, `main_callback` function - **Conflicting flag:** `src/cleveragents/cli/main.py`, `build` command (line ~529) - **Correct local implementation (reference):** `src/cleveragents/cli/commands/actor.py` line 82 ## Impact - Users cannot increase log verbosity for debugging any command (e.g., `agents -vvv plan list` to see DEBUG logs) - The `-v` short flag on `build` conflicts with the intended global flag semantics - Log output is permanently suppressed to WARNING level with no user override - The `agents --help` output does not show `-v` as a global option - Debugging production issues requires modifying environment variables or config files instead of a simple `-v` flag ## Steps to Reproduce ```bash # This should show DEBUG logs but fails with "No such option: -v" agents -vvv version # This should show WARN logs but fails with "No such option: -v" agents -v plan list # This works but is a boolean flag, not repeatable (wrong semantics) agents build -v ``` ## Suggested Fix 1. Add a count-based `-v` to `main_callback`: ```python @app.callback() def main_callback( ctx: typer.Context, ... verbose: Annotated[ int, typer.Option("--verbose", "-v", count=True, help="Increase verbosity (-v WARN, -vv INFO, -vvv DEBUG, -vvvv TRACE)"), ] = 0, ) -> None: _VERBOSITY_MAP = {0: "ERROR", 1: "WARNING", 2: "INFO", 3: "DEBUG", 4: "TRACE"} log_level = _VERBOSITY_MAP.get(verbose, "TRACE") configure_structlog(log_level=log_level) ctx.obj["verbose"] = verbose ``` 2. Remove the `-v` short form from the `build` command's `--verbose` flag (or rename it to `--show-details`) to avoid conflict with the global flag. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added the

labels

2026-04-09 08:53:43 +00:00

HAL9000 added a new dependency

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

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

HAL9000 added

and removed

labels

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

HAL9000 commented

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

Author

Owner

Label compliance fix applied:

Added missing labels: Priority/Medium, State/Unverified
Reason: UAT issue was missing State and Priority labels.

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: backlog-groomer

Label compliance fix applied: - Added missing labels: `Priority/Medium`, `State/Unverified` - Reason: UAT issue was missing State and Priority labels. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: backlog-groomer

HAL9000 referenced this issue

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

[AUTO-GROOMER] Backlog Grooming Report (Cycle 56) #5725

HAL9000 added

Points

and removed

Points

labels

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

HAL9000 referenced this issue

2026-04-09 09:04:26 +00:00

[AUTO-PROJ-OWN] Project Owner Report (Cycle 28) #5666

HAL9000 added this to the v3.2.0 milestone

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

HAL9000 commented

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

Author

Owner

Label compliance fix applied:

Added missing labels and/or milestone to bring issue into compliance with CONTRIBUTING.md

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: backlog-groomer

Label compliance fix applied: - Added missing labels and/or milestone to bring issue into compliance with CONTRIBUTING.md --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: backlog-groomer

HAL9000 referenced this issue

2026-04-09 09:54:45 +00:00

[AUTO-ARCH] Architecture Review (Cycle 1) #5368

HAL9000 referenced this issue

2026-04-09 12:10:15 +00:00

[AUTO-EPIC] Epic Planning Health Report (Cycle 12) #5422

HAL9000 referenced this issue

2026-04-09 20:05:39 +00:00

[AUTO-IMP-POOL] Implementation Pool Tracking (Cycle 1) #6296