cleveragents/cleveragents-core

Fork 3

UAT: Global `-v` verbosity flag (repeatable up to 5x) is not implemented as a global option — spec requires `-v...` on all commands #2415

New issue

Open

opened 2026-04-03 17:39:45 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 17:39:45 +00:00

Owner

Metadata

Branch: fix/cli-global-verbosity-flag
Commit Message: fix(cli): add global -v verbosity flag repeatable up to five times
Milestone: v3.6.0
Parent Epic: #397

Background and Context

The specification (docs/specification.md) defines a global verbosity option as part of the top-level CLI synopsis:

agents|cleveragents [-v...] <COMMAND> [<ARGS>...]

The -v... notation means the flag can be repeated to increase the verbosity level up to five times (-v, -vv, -vvv, -vvvv, -vvvvv). This is a global option that must apply to all agents commands, not just individual subcommands.

This issue was found by UAT tester instance uat-tester-cli-worker as part of pool supervisor session uat-pool-1, tracking issue #2360.

Current Behavior

The main_callback() function in src/cleveragents/cli/main.py does not define a global -v verbosity option. The global callback only defines --version and --show-secrets.

While some individual commands (e.g., actor run, plan build) define their own --verbose/-v flags, there is no global verbosity control at the top-level agents command.

Steps to reproduce:

agents -v project list
# Expected: runs with increased verbosity
# Actual: Error: No such option: -v  (at the global level)

agents -vvv plan status <PLAN_ID>
# Expected: runs with level-3 verbosity
# Actual: Error: No such option: -vvv

Code location: src/cleveragents/cli/main.py, main_callback() function

Expected Behavior

Per the specification, the -v flag should be available globally on all commands and increase log verbosity when repeated:

Flag	Verbosity Level
(none)	0 — default (WARNING)
`-v`	1 — INFO
`-vv`	2 — DEBUG
`-vvv`	3 — DEBUG + verbose
`-vvvv`	4 — TRACE
`-vvvvv`	5 — TRACE + verbose

The flag must be accepted at the global level so that agents -vvv <any-command> works uniformly.

Note: Individual commands like actor run that already have their own -v count option should be reconciled with the global flag to avoid conflicts.

Acceptance Criteria

agents -v <command> is accepted without error for all top-level commands
-v can be repeated up to five times (-vvvvv) and each repetition increases the verbosity level
The global verbosity level is applied to the logging system before any subcommand executes
Individual subcommand -v flags are reconciled or removed to avoid conflicts with the global flag
agents --help documents the global -v flag
All existing CLI tests continue to pass
New unit tests cover verbosity levels 0–5

Supporting Information

Spec reference: docs/specification.md — global CLI synopsis agents|cleveragents [-v...] <COMMAND> [<ARGS>...]
Related issue: #2409 (Global CLI options --data-dir and --config-path also missing)
UAT tracking issue: #2360
Code location: src/cleveragents/cli/main.py, main_callback()

Subtasks

Add verbose: Annotated[int, typer.Option("-v", count=True, ...)] parameter to main_callback() in main.py
Wire the verbosity count to the logging configuration (set log level based on count 0–5)
Audit all subcommands for conflicting -v flags and reconcile (remove or delegate to global)
Update --help output to document the global -v flag
Tests (pytest/Behave): Add unit tests for verbosity levels 0–5
Tests (pytest/Behave): Add integration test confirming -v is accepted globally on representative commands
Verify coverage ≥ 97% via nox -s coverage_report
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, followed by a blank line, then additional lines providing relevant details about the implementation.
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.
All nox stages pass.
Coverage ≥ 97%.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/cli-global-verbosity-flag` - **Commit Message**: `fix(cli): add global -v verbosity flag repeatable up to five times` - **Milestone**: v3.6.0 - **Parent Epic**: #397 ## Background and Context The specification (`docs/specification.md`) defines a global verbosity option as part of the top-level CLI synopsis: ``` agents|cleveragents [-v...] <COMMAND> [<ARGS>...] ``` The `-v...` notation means the flag can be repeated to increase the verbosity level up to five times (`-v`, `-vv`, `-vvv`, `-vvvv`, `-vvvvv`). This is a **global** option that must apply to **all** `agents` commands, not just individual subcommands. This issue was found by UAT tester instance `uat-tester-cli-worker` as part of pool supervisor session `uat-pool-1`, tracking issue #2360. ## Current Behavior The `main_callback()` function in `src/cleveragents/cli/main.py` does **not** define a global `-v` verbosity option. The global callback only defines `--version` and `--show-secrets`. While some individual commands (e.g., `actor run`, `plan build`) define their own `--verbose/-v` flags, there is no global verbosity control at the top-level `agents` command. **Steps to reproduce:** ```bash agents -v project list # Expected: runs with increased verbosity # Actual: Error: No such option: -v (at the global level) agents -vvv plan status <PLAN_ID> # Expected: runs with level-3 verbosity # Actual: Error: No such option: -vvv ``` **Code location**: `src/cleveragents/cli/main.py`, `main_callback()` function ## Expected Behavior Per the specification, the `-v` flag should be available **globally** on all commands and increase log verbosity when repeated: | Flag | Verbosity Level | |------|----------------| | _(none)_ | 0 — default (WARNING) | | `-v` | 1 — INFO | | `-vv` | 2 — DEBUG | | `-vvv` | 3 — DEBUG + verbose | | `-vvvv` | 4 — TRACE | | `-vvvvv` | 5 — TRACE + verbose | The flag must be accepted at the global level so that `agents -vvv <any-command>` works uniformly. **Note**: Individual commands like `actor run` that already have their own `-v` count option should be reconciled with the global flag to avoid conflicts. ## Acceptance Criteria - [ ] `agents -v <command>` is accepted without error for all top-level commands - [ ] `-v` can be repeated up to five times (`-vvvvv`) and each repetition increases the verbosity level - [ ] The global verbosity level is applied to the logging system before any subcommand executes - [ ] Individual subcommand `-v` flags are reconciled or removed to avoid conflicts with the global flag - [ ] `agents --help` documents the global `-v` flag - [ ] All existing CLI tests continue to pass - [ ] New unit tests cover verbosity levels 0–5 ## Supporting Information - Spec reference: `docs/specification.md` — global CLI synopsis `agents|cleveragents [-v...] <COMMAND> [<ARGS>...]` - Related issue: #2409 (Global CLI options `--data-dir` and `--config-path` also missing) - UAT tracking issue: #2360 - Code location: `src/cleveragents/cli/main.py`, `main_callback()` ## Subtasks - [ ] Add `verbose: Annotated[int, typer.Option("-v", count=True, ...)]` parameter to `main_callback()` in `main.py` - [ ] Wire the verbosity count to the logging configuration (set log level based on count 0–5) - [ ] Audit all subcommands for conflicting `-v` flags and reconcile (remove or delegate to global) - [ ] Update `--help` output to document the global `-v` flag - [ ] Tests (pytest/Behave): Add unit tests for verbosity levels 0–5 - [ ] Tests (pytest/Behave): Add integration test confirming `-v` is accepted globally on representative commands - [ ] Verify coverage ≥ 97% via `nox -s coverage_report` - [ ] 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, followed by a blank line, then additional lines providing relevant details about the implementation. - 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. - All nox stages pass. - Coverage ≥ 97%. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.6.0 milestone

2026-04-03 17:39:49 +00:00

freemo added a new dependency

2026-04-03 17:40:32 +00:00

#397 Epic: Server & Autonomy Infrastructure

freemo referenced this issue

2026-04-03 17:42:38 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 1511 — v3.7.0 #2421

freemo referenced this issue

2026-04-03 17:52:45 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 1521 — v3.7.0 #2422

freemo referenced this issue

2026-04-03 18:02:52 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 1531 — v3.7.0 #2433

freemo referenced this issue

2026-04-03 18:12:59 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 1541 — v3.7.0 #2434

freemo commented

2026-04-03 18:21:14 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: High — The specification explicitly requires -v... as a global option on all commands. This is a spec compliance gap.
Milestone: v3.6.0 (as specified in issue metadata)
MoSCoW: Should Have — While the verbosity flag is spec-required, the application functions without it. This is important for developer experience and debugging but does not block core functionality.
Parent Epic: #397 (Server & Autonomy Infrastructure)

The issue is well-described with clear spec references, reproduction steps, and a definition of done. Valid and actionable.

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

Issue triaged by project owner: - **State**: Verified - **Priority**: High — The specification explicitly requires `-v...` as a global option on all commands. This is a spec compliance gap. - **Milestone**: v3.6.0 (as specified in issue metadata) - **MoSCoW**: Should Have — While the verbosity flag is spec-required, the application functions without it. This is important for developer experience and debugging but does not block core functionality. - **Parent Epic**: #397 (Server & Autonomy Infrastructure) The issue is well-described with clear spec references, reproduction steps, and a definition of done. Valid and actionable. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-03 18:23:14 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 1551 — v3.7.0 #2445

freemo referenced this issue

2026-04-03 18:25:44 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.x — Session Tracker #2435

freemo referenced this issue

2026-04-03 18:33:21 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 1561 — v3.7.0 #2467

freemo referenced this issue

2026-04-03 18:52:54 +00:00

UAT: Global -v repeatable verbosity flag missing from main CLI — spec requires log verbosity control on all commands #2540