UAT: Global `--format` flag missing from top-level CLI — `agents --format table session list` fails with "No such option" #2099

New issue

Open

opened 2026-04-03 04:03:14 +00:00 by freemo · 1 comment

freemo commented

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

Owner

Metadata

Branch: fix/global-format-flag-missing
Commit Message: fix(cli): add global --format flag to main CLI callback for all subcommands
Milestone: v3.7.0
Parent Epic: #936

Subtasks

Add --format as a global option in main_callback() in src/cleveragents/cli/main.py
Propagate the resolved format value to all subcommands via context or a global state mechanism
Ensure the global --format flag takes precedence over per-command --format flags
Add unit tests (Behave) for global --format flag propagation
Add integration tests (Robot Framework) for agents --format <fmt> <command> patterns

Definition of Done

agents --format table session list works without error
agents --format json plan list works without error
agents --format plain version works without error
All 6 formats (rich, color, table, plain, json, yaml) work as global flags
The global --format flag takes precedence over per-command --format flags
Tests pass at ≥97% coverage

Bug Report

What Was Tested

The spec (§CLI Commands, §Output Rendering Framework) defines --format as a global flag at the top level of the CLI:

agents|cleveragents [--format (rich|color|table|plain|json|yaml)] <COMMAND> [<ARGS>...]

Multiple spec examples use this pattern:

agents --format table session list
agents --format table project list
agents --format json plan show
agents --format plain project show local/api-service

Expected Behavior (from spec)

The --format flag should be available at the top level of the CLI and apply to all subcommands. Running agents --format table session list should render the session list in table format.

Actual Behavior

Running agents --format table session list (or any agents --format <fmt> <command>) fails with:

Error [500] INTERNAL: An unexpected error occurred

The underlying error is: NoSuchOption: No such option: --format

The main_callback() in src/cleveragents/cli/main.py does not define a --format option:

@app.callback()
def main_callback(
    version: bool = typer.Option(...),
    show_secrets: bool = typer.Option(...),
) -> None:
    # No --format option here!

Code Location

src/cleveragents/cli/main.py — main_callback() function (line ~293)
The spec requires --format to be a global option in the CLI synopsis

Steps to Reproduce

from cleveragents.cli.main import main
result = main(['--format', 'json', 'version'])
# Returns exit code 1 with error: "No such option: --format"

Severity

High — This is a fundamental spec requirement. The spec explicitly shows agents --format <fmt> <command> as the primary usage pattern throughout the documentation (§1633, §3095, §12157, §22398, §26719, §26762, §26809, §26868, §26917, §26972, §27015, §27150, §27202).

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

## Metadata - **Branch**: `fix/global-format-flag-missing` - **Commit Message**: `fix(cli): add global --format flag to main CLI callback for all subcommands` - **Milestone**: v3.7.0 - **Parent Epic**: #936 ## Subtasks - [ ] Add `--format` as a global option in `main_callback()` in `src/cleveragents/cli/main.py` - [ ] Propagate the resolved format value to all subcommands via context or a global state mechanism - [ ] Ensure the global `--format` flag takes precedence over per-command `--format` flags - [ ] Add unit tests (Behave) for global `--format` flag propagation - [ ] Add integration tests (Robot Framework) for `agents --format <fmt> <command>` patterns ## Definition of Done - `agents --format table session list` works without error - `agents --format json plan list` works without error - `agents --format plain version` works without error - All 6 formats (`rich`, `color`, `table`, `plain`, `json`, `yaml`) work as global flags - The global `--format` flag takes precedence over per-command `--format` flags - Tests pass at ≥97% coverage ## Bug Report ### What Was Tested The spec (§CLI Commands, §Output Rendering Framework) defines `--format` as a **global** flag at the top level of the CLI: ``` agents|cleveragents [--format (rich|color|table|plain|json|yaml)] <COMMAND> [<ARGS>...] ``` Multiple spec examples use this pattern: - `agents --format table session list` - `agents --format table project list` - `agents --format json plan show` - `agents --format plain project show local/api-service` ### Expected Behavior (from spec) The `--format` flag should be available at the top level of the CLI and apply to all subcommands. Running `agents --format table session list` should render the session list in table format. ### Actual Behavior Running `agents --format table session list` (or any `agents --format <fmt> <command>`) fails with: ``` Error [500] INTERNAL: An unexpected error occurred ``` The underlying error is: `NoSuchOption: No such option: --format` The `main_callback()` in `src/cleveragents/cli/main.py` does not define a `--format` option: ```python @app.callback() def main_callback( version: bool = typer.Option(...), show_secrets: bool = typer.Option(...), ) -> None: # No --format option here! ``` ### Code Location - `src/cleveragents/cli/main.py` — `main_callback()` function (line ~293) - The spec requires `--format` to be a global option in the CLI synopsis ### Steps to Reproduce ```python from cleveragents.cli.main import main result = main(['--format', 'json', 'version']) # Returns exit code 1 with error: "No such option: --format" ``` ### Severity **High** — This is a fundamental spec requirement. The spec explicitly shows `agents --format <fmt> <command>` as the primary usage pattern throughout the documentation (§1633, §3095, §12157, §22398, §26719, §26762, §26809, §26868, §26917, §26972, §27015, §27150, §27202). --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo commented

2026-04-03 04:04:16 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: High (confirmed) — The global --format flag is a fundamental spec requirement. The spec shows agents --format <fmt> <command> as the primary usage pattern throughout the documentation. Its absence means users cannot set output format globally, forcing per-command --format flags.
Milestone: v3.7.0 (assigning — this is part of the Output Rendering Pipeline Epic #936)
MoSCoW: Should Have — The spec explicitly defines the global --format flag in the CLI synopsis. This is important for usability and spec compliance, especially for CI/CD pipelines.
Parent Epic: #936 (confirmed correct)

Note: This issue is missing a milestone assignment. Assigning to v3.7.0.

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

Issue triaged by project owner: - **State**: Verified - **Priority**: High (confirmed) — The global `--format` flag is a fundamental spec requirement. The spec shows `agents --format <fmt> <command>` as the primary usage pattern throughout the documentation. Its absence means users cannot set output format globally, forcing per-command `--format` flags. - **Milestone**: v3.7.0 (assigning — this is part of the Output Rendering Pipeline Epic #936) - **MoSCoW**: Should Have — The spec explicitly defines the global `--format` flag in the CLI synopsis. This is important for usability and spec compliance, especially for CI/CD pipelines. - **Parent Epic**: #936 (confirmed correct) Note: This issue is missing a milestone assignment. Assigning to v3.7.0. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo added this to the v3.7.0 milestone

2026-04-03 04:04:28 +00:00

freemo referenced this issue

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

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2023

freemo referenced this issue

2026-04-03 04:08:26 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2023

freemo referenced this issue

2026-04-03 04:11:31 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 711 — v3.7.0 #2115

freemo referenced this issue