params-proto 3.1.2__tar.gz → 3.2.1__tar.gz

{params_proto-3.1.2 → params_proto-3.2.1}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "params-proto",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "Declarative hyperparameter management skills for ML/AI experiments",
   "author": {
     "name": "Ge Yang"

{params_proto-3.1.2 → params_proto-3.2.1}/.idea/workspace.xml

@@ -33,6 +33,7 @@
   <component name="HighlightingSettingsPerFile">
     <setting file="file://$USER_HOME$/Library/Caches/JetBrains/PyCharm2025.2/python_stubs/-1979844046/_typing.py" root0="SKIP_INSPECTION" />
     <setting file="file://$PROJECT_DIR$/pyproject.toml" root0="SKIP_INSPECTION" />
+    <setting file="file://$PROJECT_DIR$/src/params_proto/envvar.py" root0="SKIP_INSPECTION" />
   </component>
   <component name="KubernetesApiPersistence">{}</component>
   <component name="KubernetesApiProvider">{
@@ -193,10 +194,10 @@
       <option name="ADD_CONTENT_ROOTS" value="true" />
       <option name="ADD_SOURCE_ROOTS" value="true" />
       <EXTENSION ID="PythonCoverageRunConfigurationExtension" runner="coverage.py" />
-      <option name="RUN_TOOL" value="" />
+      <option name="RUN_TOOL" value="true" />
       <option name="_new_keywords" value="&quot;&quot;" />
       <option name="_new_parameters" value="&quot;&quot;" />
-      <option name="_new_additionalArguments" value="&quot;&quot;" />
+      <option name="_new_additionalArguments" value="&quot;-n auto&quot;" />
       <option name="_new_target" value="&quot;$PROJECT_DIR$/tests&quot;" />
       <option name="_new_targetType" value="&quot;PATH&quot;" />
       <method v="2" />
@@ -223,8 +224,8 @@
   <component name="SharedIndexes">
     <attachedChunks>
       <set>
-        <option value="bundled-js-predefined-d6986cc7102b-9b0f141eb926-JavaScript-PY-253.29346.308" />
-        <option value="bundled-python-sdk-ca5e2b39c7df-6e1f45a539f7-com.jetbrains.pycharm.pro.sharedIndexes.bundled-PY-253.29346.308" />
+        <option value="bundled-js-predefined-d6986cc7102b-9b0f141eb926-JavaScript-PY-253.30387.127" />
+        <option value="bundled-python-sdk-3944b0c99280-6d6dccd035ac-com.jetbrains.pycharm.pro.sharedIndexes.bundled-PY-253.30387.127" />
       </set>
     </attachedChunks>
   </component>
@@ -255,6 +256,8 @@
       <workItem from="1768126847510" duration="6729000" />
       <workItem from="1768382679094" duration="3000" />
       <workItem from="1769135684123" duration="4247000" />
+      <workItem from="1769569263076" duration="1863000" />
+      <workItem from="1769933004821" duration="3502000" />
     </task>
     <task id="LOCAL-00001" summary="add design specs">
       <option name="closed" value="true" />
@@ -295,7 +298,7 @@
     <SUITE FILE_PATH="coverage/params_proto$scratch.coverage" NAME="scratch Coverage Results" MODIFIED="1762422882594" SOURCE_PROVIDER="com.intellij.coverage.DefaultCoverageFileProvider" RUNNER="coverage.py" COVERAGE_BY_TEST_ENABLED="false" COVERAGE_TRACING_ENABLED="false" WORKING_DIRECTORY="$PROJECT_DIR$" />
     <SUITE FILE_PATH="coverage/params_proto$demo_params_proto.coverage" NAME="demo_params_proto Coverage Results" MODIFIED="1762230413342" SOURCE_PROVIDER="com.intellij.coverage.DefaultCoverageFileProvider" RUNNER="coverage.py" COVERAGE_BY_TEST_ENABLED="false" COVERAGE_TRACING_ENABLED="false" WORKING_DIRECTORY="$PROJECT_DIR$/scratch" />
     <SUITE FILE_PATH="coverage/params_proto$pytest_for_tests_test_v3_test_proto_cli_test_proto_cli.coverage" NAME="pytest for tests.test_v3.test_proto_cli.test_proto_cli Coverage Results" MODIFIED="1762386112096" SOURCE_PROVIDER="com.intellij.coverage.DefaultCoverageFileProvider" RUNNER="coverage.py" COVERAGE_BY_TEST_ENABLED="false" COVERAGE_TRACING_ENABLED="false" WORKING_DIRECTORY="$PROJECT_DIR$" />
-    <SUITE FILE_PATH="coverage/params_proto$pytest_in_tests.coverage" NAME="pytest in tests Coverage Results" MODIFIED="1767991865711" SOURCE_PROVIDER="com.intellij.coverage.DefaultCoverageFileProvider" RUNNER="coverage.py" COVERAGE_BY_TEST_ENABLED="false" COVERAGE_TRACING_ENABLED="false" WORKING_DIRECTORY="$PROJECT_DIR$/tests" />
+    <SUITE FILE_PATH="coverage/params_proto$pytest_in_tests.coverage" NAME="pytest in tests Coverage Results" MODIFIED="1769934711414" SOURCE_PROVIDER="com.intellij.coverage.DefaultCoverageFileProvider" RUNNER="coverage.py" COVERAGE_BY_TEST_ENABLED="false" COVERAGE_TRACING_ENABLED="false" WORKING_DIRECTORY="$PROJECT_DIR$/tests" />
     <SUITE FILE_PATH="coverage/params_proto$pytest_in_test_parse_env_template_py.coverage" NAME="pytest in test_parse_env_template.py Coverage Results" MODIFIED="1762242493577" SOURCE_PROVIDER="com.intellij.coverage.DefaultCoverageFileProvider" RUNNER="coverage.py" COVERAGE_BY_TEST_ENABLED="false" COVERAGE_TRACING_ENABLED="false" WORKING_DIRECTORY="$PROJECT_DIR$" />
     <SUITE FILE_PATH="coverage/params_proto$pytest_in_test_v2.coverage" NAME="pytest in test_v2 Coverage Results" MODIFIED="1762232660046" SOURCE_PROVIDER="com.intellij.coverage.DefaultCoverageFileProvider" RUNNER="coverage.py" COVERAGE_BY_TEST_ENABLED="false" COVERAGE_TRACING_ENABLED="false" WORKING_DIRECTORY="$PROJECT_DIR$/tests/test_v2" />
     <SUITE FILE_PATH="coverage/params_proto$pytest_in_test_neo_proto_py.coverage" NAME="pytest in test_neo_proto.py Coverage Results" MODIFIED="1762233469671" SOURCE_PROVIDER="com.intellij.coverage.DefaultCoverageFileProvider" RUNNER="coverage.py" COVERAGE_BY_TEST_ENABLED="false" COVERAGE_TRACING_ENABLED="false" WORKING_DIRECTORY="$PROJECT_DIR$" />

{params_proto-3.1.2 → params_proto-3.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: params-proto
-Version: 3.1.2
+Version: 3.2.1
 Summary: Modern Hyper Parameter Management for Machine Learning
 Project-URL: Homepage, https://github.com/geyang/params-proto
 Project-URL: Documentation, https://params-proto.readthedocs.io

{params_proto-3.1.2 → params_proto-3.2.1}/docs/key_concepts/union_types.md

@@ -36,8 +36,13 @@ class SGD:
 def train(optimizer: Adam | SGD, epochs: int = 10):
     pass
 
-# CLI: python train.py --optimizer:Adam --optimizer.lr 0.01
-# CLI: python train.py adam --epochs 50
+# CLI: python train.py adam --lr 0.01 --epochs 50
+# CLI: python train.py sgd --momentum 0.95
+```
+
+```{note}
+**Version 3.2.0+**: Subcommand attributes are **unprefixed by default**.
+Use `--lr` instead of `--optimizer.lr`. The prefixed syntax still works for backwards compatibility.
 ```
 
 ```python
@@ -51,15 +56,16 @@ class Model:
 def main(model: Model):
     pass
 
-# CLI: python main.py --model:Model --model.hidden-size 512
-# CLI: python main.py model
+# CLI: python main.py model --hidden-size 512
+# CLI: python main.py model --name vit
 ```
 
 ```python
-# Pattern 3: Optional simple parameters (workaround)
-# Note: Optional[str] is not fully supported; use str with default instead
+# Pattern 3: Optional simple parameters
+from typing import Optional
+
 @proto.cli
-def process(checkpoint: str = None, batch_size: int = 32):
+def process(checkpoint: Optional[str] = None, batch_size: int = 32):
     pass
 
 # CLI: python process.py --checkpoint model.pt
@@ -75,17 +81,17 @@ Use Union types when you need to **select which class to instantiate**. This cre
 First, let's see how users interact with this from the command line:
 
 ```bash
-# Positional selection (simplest)
-python render.py perspective-camera --output scene.png
+# Positional selection with unprefixed attrs (v3.2.0+)
+python render.py perspective-camera --fov 45 --aspect 1.77
 
-# Named selection (explicit)
-python render.py --camera:perspective-camera
+# Alternative class
+python render.py orthographic-camera --scale 2.0
 
-# With attribute overrides
-python render.py perspective-camera --camera.fov 45 --camera.aspect 1.77
+# With shared parameters
+python render.py perspective-camera --output scene.png
 
-# Alternative class
-python render.py --camera:OrthographicCamera --camera.scale 2.0
+# Prefixed syntax still works (backwards compatible)
+python render.py --camera:perspective-camera --camera.fov 45
 ```
 
 Now the implementation:
@@ -121,7 +127,7 @@ if __name__ == "__main__":
 **How it works:**
 - `camera` is a **required parameter** with Union type
 - params-proto instantiates the selected class
-- Each class has its own parameter namespace (`--camera.fov`, `--camera.aspect`, etc.)
+- Attributes are unprefixed by default (`--fov`, `--aspect`)
 - Use `isinstance()` to dispatch on the selected type
 
 ## Optional[T]: Simple Optional Parameters
@@ -129,17 +135,18 @@ if __name__ == "__main__":
 `Optional[T]` is for parameters that **may or may not be provided**:
 
 ```python
+from typing import Optional
+
 @proto.cli
 def train(
-    checkpoint: str = None,      # Works (workaround)
-    # checkpoint: Optional[str] = None,  # ⚠️ Doesn't fully work yet
+    checkpoint: Optional[str] = None,  # Optional with None default
     epochs: int = 10,
 ):
     """Train model."""
     pass
 ```
 
-**Expected CLI usage:**
+**CLI usage:**
 
 ```bash
 python train.py --checkpoint model.pt       # Provide value
@@ -147,21 +154,15 @@ python train.py                             # Omit for None default
 python train.py --checkpoint model.pt --epochs 50
 ```
 
-```{note}
-**Current limitation:** `Optional[str]`, `Optional[int]`, etc. are not fully supported.
-Use regular parameters with defaults as a workaround:
+Both `Optional[str]` and `str = None` work equivalently:
 
 ```python
-# ✓ Works
+# Both work
 @proto.cli
-def train(checkpoint: str = None, epochs: int = 10):
-    pass
+def train(checkpoint: Optional[str] = None): ...
 
-# ⚠️ Doesn't work yet
 @proto.cli
-def train(checkpoint: Optional[str] = None, epochs: int = 10):
-    pass
-```
+def train(checkpoint: str = None): ...
 ```
 
 ## Key Differences
@@ -169,8 +170,8 @@ def train(checkpoint: Optional[str] = None, epochs: int = 10):
 | Type | Purpose | CLI Syntax | When to Use |
 |------|---------|-----------|-------------|
 | `Union[ClassA, ClassB]` | Choose which class instance | `--param:ClassName` or positional | Multiple configurations (optimizers, models, etc.) |
-| `Optional[str]` | Value may or may not be provided | `--param value` | Optional simple parameters (**currently use workaround**) |
-| `str` with default | Same as Optional | `--param value` | Simple optional parameters (**recommended workaround**) |
+| `Optional[str]` | Value may or may not be provided | `--param value` | Optional simple parameters |
+| `str = None` | Same as Optional | `--param value` | Alternative syntax for optional parameters |
 
 ## Syntax Variations
 
@@ -180,10 +181,10 @@ def train(checkpoint: Optional[str] = None, epochs: int = 10):
 --camera:PerspectiveCamera      # Exact match
 --camera:perspective-camera     # kebab-case
 --camera:perspectivecamera      # lowercase
-perspective-camera              # Positional
+perspective-camera              # Positional (recommended)
 ```
 
-**Attribute overrides** (kebab-case conversion):
+**Attribute overrides** (v3.2.0+: unprefixed by default):
 
 ```python
 @dataclass
@@ -191,11 +192,37 @@ class Config:
     batch_size: int = 32          # Python: snake_case
     learning_rate: float = 0.001
 
-# CLI uses kebab-case
+# CLI uses kebab-case (unprefixed by default)
+--batch-size 64
+--learning-rate 0.01
+
+# Prefixed syntax still works
 --config.batch-size 64
 --config.learning-rate 0.01
 ```
 
+### Using `@proto.prefix` for Required Prefixes
+
+If you want to **require** prefixed syntax for a class (e.g., for disambiguation), decorate it with `@proto.prefix`:
+
+```python
+@proto.prefix  # Now requires --config.batch-size syntax
+@dataclass
+class Config:
+    batch_size: int = 32
+
+@dataclass
+class Model:
+    batch_size: int = 16  # Same attr name, no conflict
+
+@proto.cli
+def train(config: Config, model: Model):
+    pass
+
+# CLI: Config requires prefix, Model doesn't
+# python train.py config model --config.batch-size 64 --batch-size 32
+```
+
 ## Examples
 
 ### Example 1: Optimizer Selection
@@ -203,9 +230,11 @@ class Config:
 Command-line usage:
 
 ```bash
-# Choose optimizer and override defaults
-python train.py adam --optimizer.lr 0.01
-python train.py sgd --optimizer.momentum 0.95
+# Choose optimizer and override defaults (unprefixed)
+python train.py adam --lr 0.01
+python train.py sgd --momentum 0.95
+
+# Prefixed syntax also works
 python train.py --optimizer:Adam --optimizer.beta1 0.95
 ```
 
@@ -237,10 +266,10 @@ def train(optimizer: Adam | SGD):  # Union type selector
 Command-line usage:
 
 ```bash
-# Positional class selection
-python connect.py database-config --db.host prod.example.com --db.port 3306
+# Positional class selection with unprefixed attrs
+python connect.py database-config --host prod.example.com --port 3306
 
-# Or named selection
+# Or named selection with prefixed attrs
 python connect.py --db:DatabaseConfig --db.user root
 ```
 
@@ -264,11 +293,11 @@ def connect(db: DatabaseConfig):  # Single class (still uses Union mechanism)
 Command-line usage:
 
 ```bash
-# Union option + shared parameters
-python render.py perspective-camera --output scene.png --verbose
+# Union option + shared parameters (unprefixed)
+python render.py perspective-camera --fov 45 --output scene.png --verbose
 
 # Different union option with overrides
-python render.py --camera:OrthographicCamera --camera.scale 2.0 --verbose
+python render.py orthographic-camera --scale 2.0 --verbose
 
 # Help shows all options
 python render.py --help
@@ -303,6 +332,47 @@ def render(
 
 **Key point:** Union parameters are **required**, while other parameters can be optional with defaults.
 
+### Example 4: @proto.prefix Classes Require Prefixed Syntax
+
+When a Union class is decorated with `@proto.prefix`, its CLI attributes require prefixed syntax:
+
+```python
+@proto.prefix  # Requires prefixed syntax
+@dataclass
+class Train:
+    lr: float = 0.001
+    epochs: int = 100
+
+@dataclass  # Regular dataclass - unprefixed works
+class Evaluate:
+    checkpoint: str = "model.pt"
+
+@proto.cli
+def main(mode: Train | Evaluate):
+    if isinstance(mode, Train):
+        print(f"Training: lr={mode.lr}, epochs={mode.epochs}")
+    else:
+        print(f"Evaluating: {mode.checkpoint}")
+
+if __name__ == "__main__":
+    main()
+```
+
+Command-line usage:
+
+```bash
+# Train is @proto.prefix - requires prefixed syntax
+python main.py train --mode.lr 0.01 --mode.epochs 50
+
+# Evaluate is regular dataclass - unprefixed works
+python main.py evaluate --checkpoint best.pt
+```
+
+This is useful when:
+- You have multiple Union params with overlapping attribute names
+- You want explicit namespacing for clarity
+- You're using the class as a singleton config elsewhere
+
 ## Related
 
 - [Core Concepts](core-concepts) - Three main decorators

{params_proto-3.1.2 → params_proto-3.2.1}/docs/release_notes.md

@@ -2,6 +2,57 @@
 
 This page contains the release history and changelog for params-proto.
 
+## Version 3.2.1 (2025-02-01)
+
+### 🐛 Bug Fixes
+
+- **Positional Arguments in Subcommands**: Fixed positional arguments being silently ignored after subcommand name
+  - Before: `myapp add my-env/v1.2.3` → positional arg silently dropped
+  - After: `myapp add my-env/v1.2.3` → positional arg captured by subcommand's required field
+  - Enables CLI patterns like `pip install requests`, `cargo add serde`
+  - Raises clear error for extra unrecognized positional arguments
+
+### 📚 Documentation
+
+- Fixed outdated notes claiming `Optional[str]` was not supported (it works)
+
+---
+
+## Version 3.2.0 (2025-02-01)
+
+### ✨ Features
+
+- **Unprefixed CLI Subcommand Attributes**: Subcommand attributes no longer require prefix by default
+  - Old: `python train.py train-config --config.epochs 200`
+  - New: `python train.py train-config --epochs 200`
+  - Prefixed syntax still works for backwards compatibility
+
+- **`@proto.prefix` Controls CLI Prefix Requirement**: Classes decorated with `@proto.prefix` require prefixed CLI syntax
+  - Regular dataclasses: `--epochs 200` (unprefixed)
+  - `@proto.prefix` classes: `--config.epochs 200` (prefixed required)
+
+### 🐛 Bug Fixes
+
+- **`isinstance()` for `@proto.prefix` Instances**: Fixed `isinstance(instance, DecoratedClass)` returning `False`
+  - Instances of `@proto.prefix` decorated classes now correctly pass isinstance checks
+  - Enables proper type checking in Union subcommand handlers
+
+### 🧪 Testing
+
+- Added comprehensive nested CLI subcommand tests (`test_nested_cli.py`)
+- Added parallel test execution with `pytest-xdist`
+- Run tests in parallel: `pytest -n auto`
+
+---
+
+## Version 3.1.2 (2025-01-27)
+
+### 📚 Documentation
+
+- **Claude Code Plugin**: Fixed install command format in plugin documentation
+
+---
+
 ## Version 3.1.1 (2025-01-25)
 
 ### 🐛 Bug Fixes

{params_proto-3.1.2 → params_proto-3.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "params-proto"
-version = "3.1.2"
+version = "3.2.1"
 description = "Modern Hyper Parameter Management for Machine Learning"
 authors = [
     { name = "Ge Yang" }

{params_proto-3.1.2 → params_proto-3.2.1}/skills/params-proto/SKILL.md

@@ -10,14 +10,14 @@ description: |
   (6) Work with Union types for subcommand-like CLI patterns
 ---
 
-# params-proto v3.1.1
+# params-proto v3.2.1
 
 Declarative hyperparameter management for ML experiments with automatic CLI generation.
 
 ## Installation
 
 ```bash
-pip install params-proto==3.1.1
+pip install params-proto==3.2.0
 ```
 
 ## Three Decorators

{params_proto-3.1.2 → params_proto-3.2.1}/skills/params-proto/references/cli-and-types.md

@@ -309,9 +309,39 @@ def main(mode: Train | Evaluate):
 ```
 
 ```bash
-python main.py train --lr 0.01
+# v3.2.0+: Attributes are unprefixed by default
+python main.py train --lr 0.01 --epochs 50
+python main.py evaluate --checkpoint best.pt
+
+# Prefixed syntax still works (backwards compatible)
+python main.py --mode:train --mode.lr 0.01
+```
+
+### @proto.prefix Classes Require Prefixed Syntax
+
+When a Union class is decorated with `@proto.prefix`, its attributes require prefixed CLI syntax:
+
+```python
+@proto.prefix  # Requires prefixed syntax
+@dataclass
+class Train:
+    lr: float = 0.001
+
+@dataclass  # Regular dataclass - unprefixed works
+class Evaluate:
+    checkpoint: str = "model.pt"
+
+@proto.cli
+def main(mode: Train | Evaluate):
+    ...
+```
+
+```bash
+# Train is @proto.prefix - requires prefix
+python main.py train --mode.lr 0.01
+
+# Evaluate is regular - unprefixed works
 python main.py evaluate --checkpoint best.pt
-# Also: --mode:train, --mode:Train, --mode:perspective-camera
 ```
 
 ### Enum Types

{params_proto-3.1.2 → params_proto-3.2.1}/src/params_proto/cli/cli_parse.py

@@ -57,6 +57,32 @@ def _normalize_class_name(class_name: str) -> str:
   return class_name.replace("-", "").replace("_", "").lower()
 
 
+def _get_required_fields(cls) -> List[str]:
+  """Get list of required field names (fields without defaults) in order."""
+  import dataclasses
+
+  required = []
+
+  # Check if it's a dataclass
+  if dataclasses.is_dataclass(cls):
+    for field in dataclasses.fields(cls):
+      has_default = (
+        field.default is not dataclasses.MISSING
+        or field.default_factory is not dataclasses.MISSING
+      )
+      if not has_default:
+        required.append(field.name)
+  else:
+    # For regular classes, check annotations and class-level defaults
+    annotations = getattr(cls, "__annotations__", {})
+    for name in annotations:
+      if not hasattr(cls, name):
+        # No class-level default
+        required.append(name)
+
+  return required
+
+
 def _match_class_by_name(name: str, classes: list) -> Union[type, None]:
   """Match a string to one of the Union classes.
 
@@ -164,12 +190,31 @@ def parse_cli_args(wrapper) -> Dict[str, Any]:
         is_bool = annotation == bool
         prefix_params[kebab_key] = (singleton, param_name, annotation, is_bool)
 
+  # Build unprefixed union attribute map for classes NOT decorated with @proto.prefix
+  # Maps attr-name -> (union_param_name, attr_name_underscore)
+  # Classes in _SINGLETONS are @proto.prefix decorated and require prefixed attrs
+  unprefixed_attrs = {}
+  for kebab_name, (param_name, union_classes) in union_params.items():
+    for cls in union_classes:
+      # Skip if class is a @proto.prefix singleton (requires prefixed attrs)
+      is_prefix_class = cls in _SINGLETONS.values()
+      if is_prefix_class:
+        continue
+      if hasattr(cls, "__annotations__"):
+        for attr_name in cls.__annotations__:
+          kebab_attr = attr_name.replace("_", "-")
+          # Map to the union param (first one wins if multiple unions have same attr)
+          if kebab_attr not in unprefixed_attrs:
+            unprefixed_attrs[kebab_attr] = (param_name, attr_name)
+
   # Parse arguments
   result = {}
   prefix_values = {}  # (singleton, param_name) -> value
   positional_values = []
   union_selections = {}  # param_name -> selected_class
   union_attrs = {}  # (param_name, attr_name) -> value
+  union_positional = {}  # param_name -> [positional_args] for subcommand fields
+  current_union_param = None  # Track which union we're collecting positionals for
 
   args = sys.argv[1:]
   i = 0
@@ -336,6 +381,17 @@ def parse_cli_args(wrapper) -> Dict[str, Any]:
             i += 2
         continue
 
+      # Check unprefixed union attrs when cli_prefix=False
+      if key in unprefixed_attrs:
+        union_param_name, attr_name = unprefixed_attrs[key]
+        # Get the value
+        if i + 1 >= len(args):
+          raise SystemExit(f"error: argument --{key} requires a value")
+        value_str = args[i + 1]
+        union_attrs[(union_param_name, attr_name)] = value_str
+        i += 2
+        continue
+
       # Unknown argument
       raise SystemExit(f"error: unrecognized argument: {arg}")
 
@@ -349,12 +405,18 @@ def parse_cli_args(wrapper) -> Dict[str, Any]:
           selected_class = _match_class_by_name(arg, union_classes)
           if selected_class:
             union_selections[param_name] = selected_class
+            current_union_param = param_name  # Track for following positionals
+            union_positional[param_name] = []
             matched_union = True
             i += 1
             break
 
       if not matched_union:
-        positional_values.append(arg)
+        # If we have a current union, add positional to its list
+        if current_union_param is not None:
+          union_positional[current_union_param].append(arg)
+        else:
+          positional_values.append(arg)
         i += 1
 
   # Assign positional arguments to required parameters
@@ -405,6 +467,33 @@ def parse_cli_args(wrapper) -> Dict[str, Any]:
           # No annotations, treat as string
           attrs[attr_name] = value_str
 
+    # Assign positional args to required fields of the selected class
+    if param_name in union_positional and union_positional[param_name]:
+      positionals = union_positional[param_name]
+      required_fields = _get_required_fields(selected_class)
+
+      for field_idx, field_name in enumerate(required_fields):
+        if field_name in attrs:
+          # Already set by named arg, skip
+          continue
+        if field_idx < len(positionals):
+          # Get type annotation for conversion
+          if hasattr(selected_class, "__annotations__"):
+            field_type = selected_class.__annotations__.get(field_name, str)
+            try:
+              attrs[field_name] = _convert_type(positionals[field_idx], field_type)
+            except (ValueError, TypeError):
+              raise SystemExit(
+                f"error: invalid value for {field_name}: {positionals[field_idx]}"
+              )
+          else:
+            attrs[field_name] = positionals[field_idx]
+
+      # Check for extra positional args
+      if len(positionals) > len(required_fields):
+        extra = positionals[len(required_fields):]
+        raise SystemExit(f"error: unrecognized arguments: {' '.join(extra)}")
+
     # If selected_class is a proto.prefix singleton, merge its overrides
     from params_proto.proto import _SINGLETONS, ptype
 
@@ -419,6 +508,14 @@ def parse_cli_args(wrapper) -> Dict[str, Any]:
               attrs[key] = value
         break
 
+    # Check for missing required fields
+    required_fields = _get_required_fields(selected_class)
+    for field_name in required_fields:
+      if field_name not in attrs:
+        raise SystemExit(
+          f"error: {selected_class.__name__} requires argument: {field_name}"
+        )
+
     # Instantiate the class with collected attributes
     try:
       instance = selected_class(**attrs)