cleveragents/cleveragents-core

Fork 3

UAT: Global `--format` option missing from main CLI callback — spec requires it as a top-level flag propagated to all subcommands #2505

New issue

Closed

opened 2026-04-03 18:40:41 +00:00 by freemo · 2 comments

freemo commented

2026-04-03 18:40:41 +00:00

Owner

Metadata

Branch: fix/cli-global-format-option
Commit Message: fix(cli): add --format as global option to main CLI callback
Milestone: v3.7.0
Parent Epic: #397

Description

The specification defines --format as a global option on the main agents|cleveragents command:

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

This means agents --format json plan list should work, with the format applied globally to all subcommands.

Expected Behavior

The --format option should be registered on the main app.callback() in src/cleveragents/cli/main.py, and its value should be propagated to all subcommands so that:

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

all work correctly with the format applied globally.

The spec also states (Configuration section):

core.format key sets the default output rendering format used by all commands. Accepted values are rich, color, table, plain, json, yaml. When set, this value is used unless overridden by the --format CLI flag.

The priority chain is:

CLI flag --format (highest priority)
Config key core.format
Default: rich

Actual Behavior

In src/cleveragents/cli/main.py, the main_callback() function only accepts --version and --show-secrets:

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

There is no --format global option. Each subcommand independently defines its own --format option (e.g., plan list --format, project show --format), but these are per-command options, not a global option.

This means:

agents --format json plan list fails — Typer does not recognize --format at the top level
Users must use agents plan list --format json instead
The global format cannot be set via CLI flag for all commands at once

Code Location

src/cleveragents/cli/main.py — main_callback() function (lines 292–310)
The --format option needs to be added to the callback and stored in a context variable accessible by all subcommands

Proposed Fix

Add --format to main_callback():

@app.callback()
def main_callback(
    ctx: typer.Context,
    version: bool = typer.Option(None, "--version", ...),
    show_secrets: bool = typer.Option(False, "--show-secrets", ...),
    fmt: str = typer.Option(
        None,
        "--format",
        help="Output format: rich, color, table, plain, json, yaml",
    ),
) -> None:
    if fmt is not None:
        ctx.ensure_object(dict)
        ctx.obj["format"] = fmt
    _register_subcommands()

Subcommands should then read from ctx.obj when their own --format is not explicitly set.

Subtasks

Write a TDD Behave scenario demonstrating agents --format json plan list works (red test)
Add --format to main_callback() in src/cleveragents/cli/main.py
Implement context propagation so subcommands inherit the global format
Update subcommands to fall back to global format when their own --format is not set
Verify the TDD scenario passes (green test)
Run nox -e typecheck to confirm no type errors
Run nox -e unit_tests to confirm all scenarios pass
Run nox -e coverage_report to confirm coverage ≥ 97%

Definition of Done

agents --format json plan list works and outputs JSON
agents --format yaml project show local/api-service works and outputs YAML
Per-command --format still overrides the global flag
Config key core.format is respected when neither global nor per-command flag is set
All nox stages pass
Coverage ≥ 97%

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

## Metadata - **Branch**: `fix/cli-global-format-option` - **Commit Message**: `fix(cli): add --format as global option to main CLI callback` - **Milestone**: v3.7.0 - **Parent Epic**: #397 ## Description The specification defines `--format` as a **global option** on the main `agents|cleveragents` command: ``` agents|cleveragents [--data-dir <DATA_PATH>] [--config-path <CONFIG_PATH>] [--format (rich|color|table|plain|json|yaml)] [--help|-h] [--version] [-v...] <COMMAND> [<ARGS>...] ``` This means `agents --format json plan list` should work, with the format applied globally to all subcommands. ### Expected Behavior The `--format` option should be registered on the main `app.callback()` in `src/cleveragents/cli/main.py`, and its value should be propagated to all subcommands so that: ```bash agents --format json plan list agents --format yaml project show local/api-service agents --format table session list ``` all work correctly with the format applied globally. The spec also states (Configuration section): > `core.format` key sets the default output rendering format used by all commands. Accepted values are `rich`, `color`, `table`, `plain`, `json`, `yaml`. When set, this value is used unless overridden by the `--format` CLI flag. The priority chain is: 1. CLI flag `--format` (highest priority) 2. Config key `core.format` 3. Default: `rich` ### Actual Behavior In `src/cleveragents/cli/main.py`, the `main_callback()` function only accepts `--version` and `--show-secrets`: ```python @app.callback() def main_callback( version: bool = typer.Option(..., "--version", ...), show_secrets: bool = typer.Option(..., "--show-secrets", ...), ) -> None: ... ``` There is no `--format` global option. Each subcommand independently defines its own `--format` option (e.g., `plan list --format`, `project show --format`), but these are per-command options, not a global option. This means: - `agents --format json plan list` **fails** — Typer does not recognize `--format` at the top level - Users must use `agents plan list --format json` instead - The global format cannot be set via CLI flag for all commands at once ### Code Location - `src/cleveragents/cli/main.py` — `main_callback()` function (lines 292–310) - The `--format` option needs to be added to the callback and stored in a context variable accessible by all subcommands ### Proposed Fix Add `--format` to `main_callback()`: ```python @app.callback() def main_callback( ctx: typer.Context, version: bool = typer.Option(None, "--version", ...), show_secrets: bool = typer.Option(False, "--show-secrets", ...), fmt: str = typer.Option( None, "--format", help="Output format: rich, color, table, plain, json, yaml", ), ) -> None: if fmt is not None: ctx.ensure_object(dict) ctx.obj["format"] = fmt _register_subcommands() ``` Subcommands should then read from `ctx.obj` when their own `--format` is not explicitly set. ## Subtasks - [ ] Write a TDD Behave scenario demonstrating `agents --format json plan list` works (red test) - [ ] Add `--format` to `main_callback()` in `src/cleveragents/cli/main.py` - [ ] Implement context propagation so subcommands inherit the global format - [ ] Update subcommands to fall back to global format when their own `--format` is not set - [ ] Verify the TDD scenario passes (green test) - [ ] Run `nox -e typecheck` to confirm no type errors - [ ] Run `nox -e unit_tests` to confirm all scenarios pass - [ ] Run `nox -e coverage_report` to confirm coverage ≥ 97% ## Definition of Done - [ ] `agents --format json plan list` works and outputs JSON - [ ] `agents --format yaml project show local/api-service` works and outputs YAML - [ ] Per-command `--format` still overrides the global flag - [ ] Config key `core.format` is respected when neither global nor per-command flag is set - [ ] All nox stages pass - [ ] Coverage ≥ 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo referenced this issue

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

[UAT-SUPERVISOR] Progress Report — Cycle 1571 — v3.7.0 #2516

freemo commented

2026-04-03 18:46:47 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
MoSCoW: Should Have — Spec compliance or quality improvement that should be included in the milestone.

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

Issue triaged by project owner: - **State**: Verified - **MoSCoW**: Should Have — Spec compliance or quality improvement that should be included in the milestone. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-04 20:50:23 +00:00

[CA-AUTO] Project Owner — project-owner-1 — Session Tracker #2793

freemo added this to the v3.7.0 milestone

2026-04-05 05:07:06 +00:00

freemo commented

2026-04-05 19:45:08 +00:00

Author

Owner

Closing as duplicate of #2099.

Both issues describe the same bug: the global --format option is missing from the main CLI callback. Issue #2099 is the older tracking issue (v3.7.0 milestone, Priority/High, State/Verified). Please track this work in #2099.

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

Closing as duplicate of #2099. Both issues describe the same bug: the global `--format` option is missing from the main CLI callback. Issue #2099 is the older tracking issue (v3.7.0 milestone, `Priority/High`, `State/Verified`). Please track this work in #2099. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

freemo closed this issue

2026-04-05 19:45:12 +00:00

freemo referenced this issue

2026-04-05 19:46:30 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377