cleveragents/cleveragents-core

Fork 3

UAT: Global `--format/-f` short flag conflicts with `init --force/-f` — ambiguous argument parsing when using `-f` with `init` command #5752

New issue

Open

opened 2026-04-09 09:04:32 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-09 09:04:32 +00:00

Owner

Summary

The global --format flag uses -f as its short form (defined in main_callback), and the init subcommand also defines --force/-f. This creates a flag name collision that can cause ambiguous argument parsing when a user runs agents -f json init or agents init -f.

Expected Behavior

Global flags and subcommand flags should not share the same short form. The global -f for --format should be unambiguous regardless of which subcommand is invoked.

Actual Behavior

In src/cleveragents/cli/main.py:

Global flag (main_callback, line ~314):

fmt: Annotated[
    OutputFormat,
    typer.Option(
        "--format",
        "-f",  # ← short form -f for global --format
        ...
    ),
] = OutputFormat.RICH,

init subcommand (line ~432):

force: Annotated[
    bool, typer.Option("--force", "-f", help="Force reinitialization")  # ← same -f
] = False,

When a user runs agents init -f, Typer may interpret -f as either the global --format flag or the init --force flag, depending on argument parsing order. This is a latent ambiguity that can produce confusing errors.

Code Location

File: src/cleveragents/cli/main.py

Line ~314: "-f" in main_callback for --format
Line ~432: "-f" in init command for --force

Impact

agents init -f may fail with a confusing error or be misinterpreted
agents -f json init --force may produce unexpected behavior
Users who rely on -f as a shorthand for --force in init may be surprised
The ambiguity makes the CLI harder to use and script reliably

Steps to Reproduce

# Ambiguous: is -f the global --format or init's --force?
agents init -f

# This may fail or behave unexpectedly
agents -f json init -f

Suggested Fix

Remove the -f short form from either the global --format flag or the init --force flag to eliminate the ambiguity. The global --format flag is more commonly used, so it should keep -f. The init --force flag can use --force only (no short form), or use a different short form like -F:

# Option 1: Remove -f from init --force
force: Annotated[
    bool, typer.Option("--force", help="Force reinitialization")
] = False,

# Option 2: Use -F for init --force
force: Annotated[
    bool, typer.Option("--force", "-F", help="Force reinitialization")
] = False,

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

## Summary The global `--format` flag uses `-f` as its short form (defined in `main_callback`), and the `init` subcommand also defines `--force/-f`. This creates a flag name collision that can cause ambiguous argument parsing when a user runs `agents -f json init` or `agents init -f`. ## Expected Behavior Global flags and subcommand flags should not share the same short form. The global `-f` for `--format` should be unambiguous regardless of which subcommand is invoked. ## Actual Behavior In `src/cleveragents/cli/main.py`: **Global flag (main_callback, line ~314):** ```python fmt: Annotated[ OutputFormat, typer.Option( "--format", "-f", # ← short form -f for global --format ... ), ] = OutputFormat.RICH, ``` **init subcommand (line ~432):** ```python force: Annotated[ bool, typer.Option("--force", "-f", help="Force reinitialization") # ← same -f ] = False, ``` When a user runs `agents init -f`, Typer may interpret `-f` as either the global `--format` flag or the `init --force` flag, depending on argument parsing order. This is a latent ambiguity that can produce confusing errors. ## Code Location **File:** `src/cleveragents/cli/main.py` - Line ~314: `"-f"` in `main_callback` for `--format` - Line ~432: `"-f"` in `init` command for `--force` ## Impact - `agents init -f` may fail with a confusing error or be misinterpreted - `agents -f json init --force` may produce unexpected behavior - Users who rely on `-f` as a shorthand for `--force` in `init` may be surprised - The ambiguity makes the CLI harder to use and script reliably ## Steps to Reproduce ```bash # Ambiguous: is -f the global --format or init's --force? agents init -f # This may fail or behave unexpectedly agents -f json init -f ``` ## Suggested Fix Remove the `-f` short form from either the global `--format` flag or the `init --force` flag to eliminate the ambiguity. The global `--format` flag is more commonly used, so it should keep `-f`. The `init --force` flag can use `--force` only (no short form), or use a different short form like `-F`: ```python # Option 1: Remove -f from init --force force: Annotated[ bool, typer.Option("--force", help="Force reinitialization") ] = False, # Option 2: Use -F for init --force force: Annotated[ bool, typer.Option("--force", "-F", help="Force reinitialization") ] = False, ``` --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added the

labels

2026-04-09 09:05:38 +00:00

HAL9000 added a new dependency

2026-04-09 09:42:23 +00:00

#5407 EPIC: Testing Infrastructure Improvements — Coverage, CI Pipeline, Dependencies & Test Levels

HAL9000 referenced this issue

2026-04-09 09:46:14 +00:00

[AUTO-EPIC] Epic Planning Health Report (Cycle 11) #5298

HAL9000 referenced this issue

2026-04-09 09:54:45 +00:00

[AUTO-ARCH] Architecture Review (Cycle 1) #5368

HAL9000 added a new dependency

2026-04-09 10:17:07 +00:00

#5203 EPIC: CLI Output Format Compliance — Global Flags, JSON Envelope & Error Responses

HAL9000 commented

2026-04-09 10:34:22 +00:00

Author

Owner

Hierarchical Compliance Fix: This issue was detected as an orphan (no parent Epic).

Solution: Linked to Epic #5203 (CLI Output Format Compliance — Global Flags, JSON Envelope & Error Responses) based on scope alignment — global flag conflicts are part of CLI compliance.

Hierarchy: Issue #5752 → Epic #5203

Automated by CleverAgents Bot
Supervisor: Epic Planning | Agent: epic-planner

**Hierarchical Compliance Fix**: This issue was detected as an orphan (no parent Epic). **Solution**: Linked to Epic #5203 (CLI Output Format Compliance — Global Flags, JSON Envelope & Error Responses) based on scope alignment — global flag conflicts are part of CLI compliance. **Hierarchy**: Issue #5752 → Epic #5203 --- **Automated by CleverAgents Bot** Supervisor: Epic Planning | Agent: epic-planner

HAL9000 referenced this issue

2026-04-09 10:56:46 +00:00

[AUTO-EPIC] Epic Planning Health Report (Cycle 13) #5737