UAT Bug: --format flag is per-command rather than global — spec requires a single global --format option on the root CLI callback #2908

Closed
opened 2026-04-05 02:46:56 +00:00 by freemo · 4 comments
Owner

Background

The specification states: "The framework supports six distinct output formats, selectable via the global --format flag." This means --format should be a global option available on the root agents command (via the Typer callback), not a per-command option that must be duplicated on every subcommand.

Currently, main_callback() in src/cleveragents/cli/main.py defines --version and --show-secrets but has no --format parameter. Individual commands such as version(), info(), and diagnostics() each define their own fmt: str = typer.Option("rich", "--format", "-f", ...) parameter. Subcommands under plan, actor, resource, etc. may or may not have their own --format option, meaning there is no consistent format control across the CLI.

Expected Behavior

--format should be a global flag on the root CLI callback (main_callback in src/cleveragents/cli/main.py), so that:

agents --format json plan list
agents --format yaml actor list
agents --format plain version

All work with a single global flag, and every command that produces output honours the globally-selected format.

Actual Behavior

The --format flag is defined per-command. Each command that supports it (e.g., version, info, diagnostics) defines its own --format option. Subcommands like plan list, actor list, etc. may or may not have their own --format option. There is no global --format on the root callback.

agents --format json version   # Error: No such option: --format
agents --format json plan list # Error: No such option: --format

Impact

  • Users cannot set a single format for all commands in a pipeline
  • Commands that don't explicitly define --format (e.g., many subcommands in plan, actor, resource, etc.) have no format control at all
  • Violates the spec's "every command that produces output must support all six formats" requirement

Code Locations

  • src/cleveragents/cli/main.pymain_callback() function has --version and --show-secrets but no --format
  • Individual commands like version(), info(), diagnostics() each define their own fmt: str = typer.Option("rich", "--format", "-f", ...) parameter

Metadata

  • Branch: fix/format-flag-global-callback
  • Commit Message: fix(cli): promote --format to global CLI callback option per spec
  • Milestone: v3.7.0
  • Parent Epic: #936

Subtasks

  • Add fmt: OutputFormat parameter to main_callback() in src/cleveragents/cli/main.py with typer.Option("rich", "--format", "-f", help="Output format: rich|plain|json|yaml|csv|tsv")
  • Store the selected format in the Typer context object (ctx.ensure_object(dict); ctx.obj["format"] = fmt) so subcommands can read it
  • Remove per-command --format / fmt parameters from version(), info(), diagnostics(), and any other commands that duplicate it
  • Update all commands that produce output to read the format from ctx.obj["format"] instead of a local parameter
  • Verify that agents --format json plan list, agents --format yaml actor list, and agents --format plain version all work correctly
  • Write Behave scenarios covering global --format flag propagation to subcommands for all six formats
  • Update Robot Framework integration tests to exercise the global --format flag
  • Run nox (all default sessions) and fix any errors
  • Verify coverage >= 97% via nox -s coverage_report

Definition of Done

  • --format is defined once on main_callback() and not duplicated on individual subcommands
  • agents --format <fmt> <any-command> works for all six formats (rich, plain, json, yaml, csv, tsv) and all commands
  • All Behave scenarios for global format propagation pass
  • All Robot Framework integration tests pass
  • nox (all default sessions) passes with no errors
  • Coverage >= 97%
  • PR is merged and this issue is closed

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

## Background The specification states: "The framework supports six distinct output formats, selectable via the global `--format` flag." This means `--format` should be a global option available on the root `agents` command (via the Typer callback), not a per-command option that must be duplicated on every subcommand. Currently, `main_callback()` in `src/cleveragents/cli/main.py` defines `--version` and `--show-secrets` but has no `--format` parameter. Individual commands such as `version()`, `info()`, and `diagnostics()` each define their own `fmt: str = typer.Option("rich", "--format", "-f", ...)` parameter. Subcommands under `plan`, `actor`, `resource`, etc. may or may not have their own `--format` option, meaning there is no consistent format control across the CLI. ## Expected Behavior `--format` should be a global flag on the root CLI callback (`main_callback` in `src/cleveragents/cli/main.py`), so that: ```bash agents --format json plan list agents --format yaml actor list agents --format plain version ``` All work with a single global flag, and every command that produces output honours the globally-selected format. ## Actual Behavior The `--format` flag is defined per-command. Each command that supports it (e.g., `version`, `info`, `diagnostics`) defines its own `--format` option. Subcommands like `plan list`, `actor list`, etc. may or may not have their own `--format` option. There is no global `--format` on the root callback. ```bash agents --format json version # Error: No such option: --format agents --format json plan list # Error: No such option: --format ``` ## Impact - Users cannot set a single format for all commands in a pipeline - Commands that don't explicitly define `--format` (e.g., many subcommands in `plan`, `actor`, `resource`, etc.) have no format control at all - Violates the spec's "every command that produces output must support all six formats" requirement ## Code Locations - `src/cleveragents/cli/main.py` — `main_callback()` function has `--version` and `--show-secrets` but no `--format` - Individual commands like `version()`, `info()`, `diagnostics()` each define their own `fmt: str = typer.Option("rich", "--format", "-f", ...)` parameter ## Metadata - **Branch**: `fix/format-flag-global-callback` - **Commit Message**: `fix(cli): promote --format to global CLI callback option per spec` - **Milestone**: v3.7.0 - **Parent Epic**: #936 ## Subtasks - [ ] Add `fmt: OutputFormat` parameter to `main_callback()` in `src/cleveragents/cli/main.py` with `typer.Option("rich", "--format", "-f", help="Output format: rich|plain|json|yaml|csv|tsv")` - [ ] Store the selected format in the Typer context object (`ctx.ensure_object(dict); ctx.obj["format"] = fmt`) so subcommands can read it - [ ] Remove per-command `--format` / `fmt` parameters from `version()`, `info()`, `diagnostics()`, and any other commands that duplicate it - [ ] Update all commands that produce output to read the format from `ctx.obj["format"]` instead of a local parameter - [ ] Verify that `agents --format json plan list`, `agents --format yaml actor list`, and `agents --format plain version` all work correctly - [ ] Write Behave scenarios covering global `--format` flag propagation to subcommands for all six formats - [ ] Update Robot Framework integration tests to exercise the global `--format` flag - [ ] Run `nox` (all default sessions) and fix any errors - [ ] Verify coverage >= 97% via `nox -s coverage_report` ## Definition of Done - [ ] `--format` is defined once on `main_callback()` and not duplicated on individual subcommands - [ ] `agents --format <fmt> <any-command>` works for all six formats (`rich`, `plain`, `json`, `yaml`, `csv`, `tsv`) and all commands - [ ] All Behave scenarios for global format propagation pass - [ ] All Robot Framework integration tests pass - [ ] `nox` (all default sessions) passes with no errors - [ ] Coverage >= 97% - [ ] PR is merged and this issue is closed --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator
freemo added this to the v3.7.0 milestone 2026-04-05 02:47:00 +00:00
Author
Owner

Issue triaged by project owner:

  • State: Verified
  • Priority: High (confirmed)
  • MoSCoW: Should Have — spec requires global --format flag

Valid UAT finding verified during batch triage.


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

Issue triaged by project owner: - **State**: Verified - **Priority**: High (confirmed) - **MoSCoW**: Should Have — spec requires global --format flag Valid UAT finding verified during batch triage. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
Author
Owner

Starting implementation on branch fix/format-flag-global-callback.

Wave plan for parallel subtask execution:

  • Wave 1 (parallel): Subtasks 1, 2, 3 — Core CLI changes: add fmt param to main_callback(), store in ctx, remove per-command duplicates
  • Wave 2 (parallel): Subtasks 4, 5 — Update commands to read from ctx, verify CLI invocations work
  • Wave 3 (parallel): Subtasks 6, 7 — Write Behave scenarios + Robot Framework integration tests
  • Wave 4 (sequential): Subtasks 8, 9 — Run nox and verify coverage ≥ 97%

Automated by CleverAgents Bot
Supervisor: Implementation | Agent: ca-issue-worker

Starting implementation on branch `fix/format-flag-global-callback`. **Wave plan for parallel subtask execution:** - **Wave 1 (parallel):** Subtasks 1, 2, 3 — Core CLI changes: add `fmt` param to `main_callback()`, store in ctx, remove per-command duplicates - **Wave 2 (parallel):** Subtasks 4, 5 — Update commands to read from ctx, verify CLI invocations work - **Wave 3 (parallel):** Subtasks 6, 7 — Write Behave scenarios + Robot Framework integration tests - **Wave 4 (sequential):** Subtasks 8, 9 — Run `nox` and verify coverage ≥ 97% --- **Automated by CleverAgents Bot** Supervisor: Implementation | Agent: ca-issue-worker
Author
Owner

PR #3262 created on branch fix/format-flag-global-callback. PR review and merge handled by continuous review stream.

Implementation Summary:

  • Added fmt: Annotated[OutputFormat, typer.Option("--format", "-f", ...)] to main_callback() in src/cleveragents/cli/main.py
  • Stores selected format in ctx.obj["format"] via ctx.ensure_object(dict); ctx.obj["format"] = fmt.value
  • Removed per-command --format from version(), info(), diagnostics() — they now read from ctx.obj.get("format", OutputFormat.RICH.value)
  • All six formats (json, yaml, plain, rich, table, color) work via global --format flag and -f shorthand
  • 37 new Behave scenarios + 7 new Robot Framework integration tests added
  • All existing tests updated to use global flag

Quality Gates:

  • nox -e lint — passes
  • nox -e typecheck — 0 errors, 0 warnings
  • nox -e unit_tests — 37 new scenarios pass

Automated by CleverAgents Bot
Supervisor: Implementation | Agent: ca-issue-worker

PR #3262 created on branch `fix/format-flag-global-callback`. PR review and merge handled by continuous review stream. **Implementation Summary:** - Added `fmt: Annotated[OutputFormat, typer.Option("--format", "-f", ...)]` to `main_callback()` in `src/cleveragents/cli/main.py` - Stores selected format in `ctx.obj["format"]` via `ctx.ensure_object(dict); ctx.obj["format"] = fmt.value` - Removed per-command `--format` from `version()`, `info()`, `diagnostics()` — they now read from `ctx.obj.get("format", OutputFormat.RICH.value)` - All six formats (json, yaml, plain, rich, table, color) work via global `--format` flag and `-f` shorthand - 37 new Behave scenarios + 7 new Robot Framework integration tests added - All existing tests updated to use global flag **Quality Gates:** - ✅ `nox -e lint` — passes - ✅ `nox -e typecheck` — 0 errors, 0 warnings - ✅ `nox -e unit_tests` — 37 new scenarios pass --- **Automated by CleverAgents Bot** Supervisor: Implementation | Agent: ca-issue-worker
Owner

State label reconciliation:

  • Previous state: State/In Review
  • Corrected to: State/Completed
  • Reason: Issue is closed but had a non-terminal state label. CONTRIBUTING.md requires closed issues to have State/Completed or State/Wont Do.

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

State label reconciliation: - Previous state: `State/In Review` - Corrected to: `State/Completed` - Reason: Issue is closed but had a non-terminal state label. CONTRIBUTING.md requires closed issues to have `State/Completed` or `State/Wont Do`. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: backlog-groomer
Sign in to join this conversation.
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

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