cleveragents/cleveragents-core

Fork 3

UAT: `--format` is not a global option — spec requires `agents --format <fmt> <command>` syntax but only per-command `agents <command> --format <fmt>` works #2133

New issue

Closed

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

freemo commented

2026-04-03 04:20:35 +00:00

Owner

Metadata

Branch: fix/cli-global-format-option
Commit Message: fix(cli): add --format as global option to main_callback with core.format config fallback
Milestone: v3.7.0
Parent Epic: #936

Bug Report

What Was Tested

The spec (§CLI Commands, §Command Synopsis) defines --format as a global option in the command synopsis:

agents|cleveragents [--data-dir <DATA_PATH>] [--config-path <CONFIG_PATH>]
                     [--format (rich|color|table|plain|json|yaml)]
                     [--help|-h] [--version]
                     [--install-completion [<INST_SHELL>]] [--show-completion [<SHOW_SHELL>]]
                     [-v...] <COMMAND> [<ARGS>...]

The spec also states:

--format rich|color|table|plain|json|yaml: Set the output rendering format for all subcommands. When omitted, the value is read from the global config key core.format. If not set in config either, defaults to rich.

Expected Behavior (from spec)

agents --format json diagnostics → runs diagnostics with JSON output format
agents --format yaml version → shows version in YAML format

Actual Behavior

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

@app.callback()
def main_callback(
    version: bool = typer.Option(None, "--version", ...),
    show_secrets: bool = typer.Option(False, "--show-secrets", ...),
) -> None:

--format is only available as a per-command option. This means:

agents --format json diagnostics → ❌ Error: No such option: --format
agents diagnostics --format json → ✅ Works (per-command format)

The spec explicitly positions --format before the command name in the synopsis, indicating it should be a global option that applies to all subcommands. The spec also says the value should fall back to core.format config key when not specified, implying a global resolution mechanism.

Steps to Reproduce

agents --format json diagnostics
# Expected: diagnostics output in JSON format
# Actual:   Error: No such option: --format

agents --format yaml version
# Expected: version output in YAML format
# Actual:   Error: No such option: --format

Note: Per-command --format works correctly as a workaround:

agents diagnostics --format json  # Works
agents version --format yaml      # Works

Code Location

src/cleveragents/cli/main.py — main_callback() function (missing --format parameter)

Severity

Medium — The spec-defined global --format syntax does not work. Users who follow the spec's command synopsis will get errors. The per-command --format works as a workaround, but the global syntax is part of the spec contract.

Subtasks

Add --format parameter to main_callback() in src/cleveragents/cli/main.py
Implement core.format config key fallback when --format is not specified on the CLI
Propagate the resolved format value to all subcommands via the Typer context or a shared state mechanism
Write Behave unit tests covering global --format option parsing and config fallback
Write Robot Framework integration tests verifying agents --format <fmt> <command> end-to-end
Update CLI help text / docstrings to reflect --format as a global option
Verify all existing per-command --format tests still pass (no regression)

Definition of Done

agents --format json diagnostics produces JSON-formatted output without error
agents --format yaml version produces YAML-formatted output without error
agents --format plain <any-command> works for all supported subcommands
When --format is omitted globally, core.format config key is respected
When neither global --format nor core.format is set, output defaults to rich
Per-command --format still works and is not broken by this change
All nox stages pass
Coverage >= 97%

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

## Metadata - **Branch**: `fix/cli-global-format-option` - **Commit Message**: `fix(cli): add --format as global option to main_callback with core.format config fallback` - **Milestone**: v3.7.0 - **Parent Epic**: #936 ## Bug Report ### What Was Tested The spec (§CLI Commands, §Command Synopsis) defines `--format` as a **global option** in the command synopsis: ``` agents|cleveragents [--data-dir <DATA_PATH>] [--config-path <CONFIG_PATH>] [--format (rich|color|table|plain|json|yaml)] [--help|-h] [--version] [--install-completion [<INST_SHELL>]] [--show-completion [<SHOW_SHELL>]] [-v...] <COMMAND> [<ARGS>...] ``` The spec also states: > `--format rich|color|table|plain|json|yaml`: Set the output rendering format for all subcommands. When omitted, the value is read from the global config key `core.format`. If not set in config either, defaults to `rich`. ### Expected Behavior (from spec) - `agents --format json diagnostics` → runs diagnostics with JSON output format - `agents --format yaml version` → shows version in YAML format ### Actual Behavior The `main_callback()` in `src/cleveragents/cli/main.py` does **NOT** include a `--format` option: ```python @app.callback() def main_callback( version: bool = typer.Option(None, "--version", ...), show_secrets: bool = typer.Option(False, "--show-secrets", ...), ) -> None: ``` `--format` is only available as a per-command option. This means: - `agents --format json diagnostics` → ❌ `Error: No such option: --format` - `agents diagnostics --format json` → ✅ Works (per-command format) The spec explicitly positions `--format` **before** the command name in the synopsis, indicating it should be a global option that applies to all subcommands. The spec also says the value should fall back to `core.format` config key when not specified, implying a global resolution mechanism. ### Steps to Reproduce ```bash agents --format json diagnostics # Expected: diagnostics output in JSON format # Actual: Error: No such option: --format agents --format yaml version # Expected: version output in YAML format # Actual: Error: No such option: --format ``` **Note:** Per-command `--format` works correctly as a workaround: ```bash agents diagnostics --format json # Works agents version --format yaml # Works ``` ### Code Location - `src/cleveragents/cli/main.py` — `main_callback()` function (missing `--format` parameter) ### Severity **Medium** — The spec-defined global `--format` syntax does not work. Users who follow the spec's command synopsis will get errors. The per-command `--format` works as a workaround, but the global syntax is part of the spec contract. ## Subtasks - [ ] Add `--format` parameter to `main_callback()` in `src/cleveragents/cli/main.py` - [ ] Implement `core.format` config key fallback when `--format` is not specified on the CLI - [ ] Propagate the resolved format value to all subcommands via the Typer context or a shared state mechanism - [ ] Write Behave unit tests covering global `--format` option parsing and config fallback - [ ] Write Robot Framework integration tests verifying `agents --format <fmt> <command>` end-to-end - [ ] Update CLI help text / docstrings to reflect `--format` as a global option - [ ] Verify all existing per-command `--format` tests still pass (no regression) ## Definition of Done - [ ] `agents --format json diagnostics` produces JSON-formatted output without error - [ ] `agents --format yaml version` produces YAML-formatted output without error - [ ] `agents --format plain <any-command>` works for all supported subcommands - [ ] When `--format` is omitted globally, `core.format` config key is respected - [ ] When neither global `--format` nor `core.format` is set, output defaults to `rich` - [ ] Per-command `--format` still works and is not broken by this change - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.7.0 milestone

2026-04-03 04:20:40 +00:00

freemo added a new dependency

2026-04-03 04:21:10 +00:00

#936 Epic: Output Rendering Pipeline Integration — Wire Commands to OutputSession Framework

freemo referenced this issue

2026-04-03 04:21:38 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 721 — v3.7.0 #2138

freemo commented

2026-04-03 04:21:51 +00:00

Author

Owner

Duplicate of #2099.

This issue describes the same problem as #2099 ("UAT: Global --format flag missing from top-level CLI — agents --format table session list fails with 'No such option'"). Both issues report that --format is not available as a global option in main_callback(), and both reference the same spec section (§CLI Commands, §Command Synopsis).

#2099 was triaged and verified in cycle 10 with MoSCoW: Should Have, milestone v3.7.0. Closing this as a duplicate.

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

**Duplicate of #2099.** This issue describes the same problem as #2099 ("UAT: Global `--format` flag missing from top-level CLI — `agents --format table session list` fails with 'No such option'"). Both issues report that `--format` is not available as a global option in `main_callback()`, and both reference the same spec section (§CLI Commands, §Command Synopsis). #2099 was triaged and verified in cycle 10 with MoSCoW: Should Have, milestone v3.7.0. Closing this as a duplicate. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-03 04:21:53 +00:00

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

freemo closed this issue

2026-04-03 04:22:07 +00:00