cleveragents/cleveragents-core

Fork 3

fix(cli): remove extra `<NAME>` positional from `actor add` — name should come from config #914

New issue

Closed

opened 2026-03-13 23:59:20 +00:00 by freemo · 2 comments

freemo commented

2026-03-13 23:59:20 +00:00

Owner

Background

The actor add command in the current implementation (src/cleveragents/cli/commands/actor.py:343) takes a <NAME> positional argument:

name: Annotated[str, typer.Argument(help="Name for the actor")],

The specification (spec line 4938) defines actor add as:

agents actor add (--config|-c) <FILE> [--update]

Per spec line 4945:

--config/-c FILE: Actor config file (required). The file must fully define the actor, including the name field which determines the actor's registered name.

The spec explicitly states that the actor name comes from inside the config file, not from a CLI positional argument. The current implementation also has additional non-spec flags (--unsafe, --set-default, --option/-o) that should be evaluated for spec compliance.

Acceptance Criteria

actor add no longer takes a <NAME> positional argument
The actor's registered name is derived from the name field in the provided config YAML file
actor add --help signature matches agents actor add (--config|-c) <FILE> [--update]
Non-spec flags (--unsafe, --set-default, --option/-o) are evaluated — either documented as intentional extensions or removed
Existing tests are updated to pass the name via config file instead of CLI positional

Metadata

Suggested commit message: fix(cli): derive actor name from config file instead of positional argument
Suggested branch name: fix/actor-add-name-from-config

Definition of Done

Code merged to main, actor add reads the actor name from the config file, no positional <NAME> argument exists.

## Background The `actor add` command in the current implementation (`src/cleveragents/cli/commands/actor.py:343`) takes a `<NAME>` positional argument: ```python name: Annotated[str, typer.Argument(help="Name for the actor")], ``` The specification ([spec line 4938](../docs/specification.md)) defines `actor add` as: ``` agents actor add (--config|-c) <FILE> [--update] ``` Per spec line 4945: > `--config/-c FILE`: Actor config file (required). The file must fully define the actor, including the **name field** which determines the actor's registered name. The spec explicitly states that the actor name comes from **inside the config file**, not from a CLI positional argument. The current implementation also has additional non-spec flags (`--unsafe`, `--set-default`, `--option/-o`) that should be evaluated for spec compliance. ## Acceptance Criteria - [ ] `actor add` no longer takes a `<NAME>` positional argument - [ ] The actor's registered name is derived from the `name` field in the provided config YAML file - [ ] `actor add --help` signature matches `agents actor add (--config|-c) <FILE> [--update]` - [ ] Non-spec flags (`--unsafe`, `--set-default`, `--option/-o`) are evaluated — either documented as intentional extensions or removed - [ ] Existing tests are updated to pass the name via config file instead of CLI positional ## Metadata - **Suggested commit message:** `fix(cli): derive actor name from config file instead of positional argument` - **Suggested branch name:** `fix/actor-add-name-from-config` ## Definition of Done Code merged to `main`, `actor add` reads the actor name from the config file, no positional `<NAME>` argument exists.

freemo added the

labels

2026-03-13 23:59:30 +00:00

freemo added this to the v3.4.0 milestone

2026-03-13 23:59:39 +00:00

freemo commented

2026-03-13 23:59:45 +00:00

Author

Owner

Related issues:

#901 — actor run signature also needs alignment (same actor command group)
#888 — actor context hierarchy relocation (same actor command group)

**Related issues:** - #901 — `actor run` signature also needs alignment (same actor command group) - #888 — `actor context` hierarchy relocation (same actor command group)

hurui200320 was assigned by freemo

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

hurui200320 was unassigned by freemo

2026-03-29 02:30:30 +00:00

freemo self-assigned this

2026-03-29 02:30:30 +00:00

freemo added

and removed

labels

2026-03-29 02:30:41 +00:00

freemo referenced this issue from a commit

2026-03-29 05:35:00 +00:00

fix(cli): derive actor name from config file instead of positional argument

~~freemo referenced this issue 2026-03-29 05:35:36 +00:00~~

fix(cli): derive actor name from config file instead of positional argument #1189

freemo commented

2026-03-29 05:36:02 +00:00

Author

Owner

Implementation Notes — PR #1189

Branch: fix/actor-add-name-from-config
Commit: 575010cd5d1add04b11ec1b87fcf065cbb44d5b3

Changes Made

src/cleveragents/cli/commands/actor.py — Removed the name: Annotated[str, typer.Argument(...)] positional parameter from the add() function. Added logic after _load_config() to extract the actor name from config_blob.get("name"). If the name is missing or not a string, raises typer.BadParameter("Config file must contain a 'name' field for the actor name").
Test updates — All BDD step definitions (features/steps/actor_cli_steps.py, features/steps/actor_cli_yaml_steps.py) updated to:
- Include "name" key in all config data dictionaries
- Remove positional name from all ["add", ...] CLI invocations
- Update expected error for empty config (now "Config file must contain a 'name' field" instead of "provider is required")
Robot helper (robot/helper_m2_e2e_verification.py) — Added "name": "local/m2-cli-actor" to config JSON, removed positional from run_cli() call.
Benchmarks (benchmarks/actor_cli_bench.py) — Added "name" to _VALID_CONFIG, removed positional from invocation.

Non-spec flag evaluation

Retained --unsafe, --set-default, --option/-o, and --format/-f as they serve operational/safety/formatting purposes orthogonal to the config-as-complete-definition pattern. If strict spec compliance is desired, these can be removed in a follow-up issue.

All nox stages pass

Stage	Result
lint	PASS
typecheck	PASS (0 errors)
unit_tests	PASS (12,731 scenarios, 0 failures)
integration_tests	PASS (1 pre-existing failure unrelated)
coverage_report	PASS (97%)

## Implementation Notes — PR #1189 **Branch**: `fix/actor-add-name-from-config` **Commit**: `575010cd5d1add04b11ec1b87fcf065cbb44d5b3` ### Changes Made 1. **`src/cleveragents/cli/commands/actor.py`** — Removed the `name: Annotated[str, typer.Argument(...)]` positional parameter from the `add()` function. Added logic after `_load_config()` to extract the actor name from `config_blob.get("name")`. If the name is missing or not a string, raises `typer.BadParameter("Config file must contain a 'name' field for the actor name")`. 2. **Test updates** — All BDD step definitions (`features/steps/actor_cli_steps.py`, `features/steps/actor_cli_yaml_steps.py`) updated to: - Include `"name"` key in all config data dictionaries - Remove positional name from all `["add", ...]` CLI invocations - Update expected error for empty config (now "Config file must contain a 'name' field" instead of "provider is required") 3. **Robot helper** (`robot/helper_m2_e2e_verification.py`) — Added `"name": "local/m2-cli-actor"` to config JSON, removed positional from `run_cli()` call. 4. **Benchmarks** (`benchmarks/actor_cli_bench.py`) — Added `"name"` to `_VALID_CONFIG`, removed positional from invocation. ### Non-spec flag evaluation Retained `--unsafe`, `--set-default`, `--option/-o`, and `--format/-f` as they serve operational/safety/formatting purposes orthogonal to the config-as-complete-definition pattern. If strict spec compliance is desired, these can be removed in a follow-up issue. ### All nox stages pass | Stage | Result | |-------|--------| | lint | PASS | | typecheck | PASS (0 errors) | | unit_tests | PASS (12,731 scenarios, 0 failures) | | integration_tests | PASS (1 pre-existing failure unrelated) | | coverage_report | PASS (97%) |

freemo added

and removed

labels

2026-03-29 09:31:01 +00:00

freemo referenced this issue from a pull request that will close it,

2026-03-29 20:41:03 +00:00

fix(cli): derive actor name from config file instead of positional argument #1189

freemo referenced this issue from a commit