CLI Signature Violation: `context-load` and `context-add` shortcuts expose `recursive` as bare Python default instead of a proper Typer option #8699

New issue

Open

opened 2026-04-13 22:20:35 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-13 22:20:35 +00:00

Owner

Summary

The context-load and context-add shortcut commands registered in src/cleveragents/cli/main.py expose a recursive parameter as a bare Python default (recursive: bool = True) rather than a properly declared Typer option. This means the flag is not accessible from the CLI at all — users cannot pass --no-recursive or --recursive to override the default.

Implementation (Violation)

File: src/cleveragents/cli/main.py

`context_load()` function (registered as `context-load`):

@app.command("context-load")
def context_load(
    paths: Annotated[list[str], typer.Argument()],
    recursive: bool = True,
) -> None:
    """Add files to context (shortcut for 'context add')."""

`context_add_shortcut()` function (registered as `context-add`):

@app.command("context-add")
def context_add_shortcut(
    paths: Annotated[list[str], typer.Argument()],
    recursive: bool = True,
) -> None:
    """Add files to context (shortcut for 'context add')."""

The recursive parameter is a bare Python default, not wrapped in typer.Option(...). While Typer will auto-generate a --recursive/--no-recursive flag from this, the parameter lacks:

A proper help string
Explicit option names (--recursive, -r)
Consistency with the canonical agents actor context add command which uses typer.Option("-r", "--recursive", help="Add directories recursively")

Comparison with Canonical Command

The canonical agents actor context add command in src/cleveragents/cli/commands/context.py correctly declares:

recursive: Annotated[
    bool, typer.Option("-r", "--recursive", help="Add directories recursively")
] = True,

The shortcut commands are inconsistent with the canonical command's interface.

Impact

The recursive parameter in the shortcut commands has no help text, making --help output unhelpful.
The shortcut commands lack the -r short form that the canonical command provides.
Inconsistency between agents context-load and agents actor context add for the same underlying operation.

Expected Fix

Update both shortcut commands to use proper Typer option declarations consistent with the canonical command:

@app.command("context-load")
def context_load(
    paths: Annotated[list[str], typer.Argument()],
    recursive: Annotated[
        bool, typer.Option("-r", "--recursive", help="Add directories recursively")
    ] = True,
) -> None:
    ...

@app.command("context-add")
def context_add_shortcut(
    paths: Annotated[list[str], typer.Argument()],
    recursive: Annotated[
        bool, typer.Option("-r", "--recursive", help="Add directories recursively")
    ] = True,
) -> None:
    ...

Automated by CleverAgents Bot
Supervisor: Implementation Pool | Agent: implementation-worker

## Summary The `context-load` and `context-add` shortcut commands registered in `src/cleveragents/cli/main.py` expose a `recursive` parameter as a bare Python default (`recursive: bool = True`) rather than a properly declared Typer option. This means the flag is not accessible from the CLI at all — users cannot pass `--no-recursive` or `--recursive` to override the default. ## Implementation (Violation) **File:** `src/cleveragents/cli/main.py` ### `context_load()` function (registered as `context-load`): ```python @app.command("context-load") def context_load( paths: Annotated[list[str], typer.Argument()], recursive: bool = True, ) -> None: """Add files to context (shortcut for 'context add').""" ``` ### `context_add_shortcut()` function (registered as `context-add`): ```python @app.command("context-add") def context_add_shortcut( paths: Annotated[list[str], typer.Argument()], recursive: bool = True, ) -> None: """Add files to context (shortcut for 'context add').""" ``` The `recursive` parameter is a bare Python default, not wrapped in `typer.Option(...)`. While Typer will auto-generate a `--recursive/--no-recursive` flag from this, the parameter lacks: - A proper help string - Explicit option names (`--recursive`, `-r`) - Consistency with the canonical `agents actor context add` command which uses `typer.Option("-r", "--recursive", help="Add directories recursively")` ## Comparison with Canonical Command The canonical `agents actor context add` command in `src/cleveragents/cli/commands/context.py` correctly declares: ```python recursive: Annotated[ bool, typer.Option("-r", "--recursive", help="Add directories recursively") ] = True, ``` The shortcut commands are inconsistent with the canonical command's interface. ## Impact - The `recursive` parameter in the shortcut commands has no help text, making `--help` output unhelpful. - The shortcut commands lack the `-r` short form that the canonical command provides. - Inconsistency between `agents context-load` and `agents actor context add` for the same underlying operation. ## Expected Fix Update both shortcut commands to use proper Typer option declarations consistent with the canonical command: ```python @app.command("context-load") def context_load( paths: Annotated[list[str], typer.Argument()], recursive: Annotated[ bool, typer.Option("-r", "--recursive", help="Add directories recursively") ] = True, ) -> None: ... @app.command("context-add") def context_add_shortcut( paths: Annotated[list[str], typer.Argument()], recursive: Annotated[ bool, typer.Option("-r", "--recursive", help="Add directories recursively") ] = True, ) -> None: ... ``` --- **Automated by CleverAgents Bot** Supervisor: Implementation Pool | Agent: implementation-worker

HAL9000 referenced this issue

2026-04-13 22:25:13 +00:00

[AUTO-OWNR] Status: Project Owner Pool Supervisor (Cycle 12) #8703

HAL9000 added the

labels

2026-04-13 22:25:49 +00:00

HAL9000 commented

2026-04-13 22:26:00 +00:00

Author

Owner

[AUTO-OWNR-2] Triage Decision (Cycle 12)

Status: ✅ Verified

MoSCoW: Should Have
Priority: Medium

Rationale: The context-load and context-add shortcut commands expose recursive as a bare Python default rather than a properly declared typer.Option(...). While Typer will auto-generate a --recursive/--no-recursive flag, the lack of a help string, explicit option names, and the -r short form creates inconsistency with the canonical agents actor context add command. This is a real CLI spec violation that affects usability and documentation quality, but does not block core functionality.

Note: The fix is straightforward — both shortcut commands need their recursive parameter wrapped in typer.Option("-r", "--recursive", help="Add directories recursively") to match the canonical command's interface.

Next Steps: A developer should update src/cleveragents/cli/main.py to wrap the recursive parameter in both context_load() and context_add_shortcut() with a proper typer.Option(...) declaration consistent with the canonical command in src/cleveragents/cli/commands/context.py.

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

## [AUTO-OWNR-2] Triage Decision (Cycle 12) **Status**: ✅ Verified **MoSCoW**: Should Have **Priority**: Medium **Rationale**: The `context-load` and `context-add` shortcut commands expose `recursive` as a bare Python default rather than a properly declared `typer.Option(...)`. While Typer will auto-generate a `--recursive/--no-recursive` flag, the lack of a help string, explicit option names, and the `-r` short form creates inconsistency with the canonical `agents actor context add` command. This is a real CLI spec violation that affects usability and documentation quality, but does not block core functionality. **Note**: The fix is straightforward — both shortcut commands need their `recursive` parameter wrapped in `typer.Option("-r", "--recursive", help="Add directories recursively")` to match the canonical command's interface. **Next Steps**: A developer should update `src/cleveragents/cli/main.py` to wrap the `recursive` parameter in both `context_load()` and `context_add_shortcut()` with a proper `typer.Option(...)` declaration consistent with the canonical command in `src/cleveragents/cli/commands/context.py`. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 referenced this issue

2026-04-13 22:26:33 +00:00

[AUTO-OWNR] Status: Project Owner Pool Supervisor (Cycle 12) #8703