Serialization fixes.

kschwab · kschwab · commit e985e221962d · 2025-07-15T08:25:14.000-06:00
diff --git a/docs/index.md b/docs/index.md
@@ -1173,6 +1173,29 @@ CliApp.run(Git, cli_args=['clone', 'repo', 'dir']).model_dump() == {
 
 When executing a subcommand with an asynchronous cli_cmd, Pydantic settings automatically detects whether the current thread already has an active event loop. If so, the async command is run in a fresh thread to avoid conflicts. Otherwise, it uses asyncio.run() in the current thread. This handling ensures your asynchronous subcommands "just work" without additional manual setup.
 
+### Serializing CLI Arguments
+
+An instantiated Pydantic model can be serialized into its CLI arguments using the `CliApp.serialize` method.
+
+```py
+from pydantic import BaseModel
+
+from pydantic_settings import CliApp
+
+
+class Nested(BaseModel):
+    that: int
+
+
+class Settings(BaseModel):
+    this: str
+    nested: Nested
+
+
+print(CliApp.serialize(Settings(this='hello', nested=Nested(that=123))))
+#> ['--this', 'hello', '--nested.that', '123']
+```
+
 ### Mutually Exclusive Groups
 
 CLI mutually exclusive groups can be created by inheriting from the `CliMutuallyExclusiveGroup` class.
diff --git a/pydantic_settings/main.py b/pydantic_settings/main.py
@@ -477,6 +477,25 @@ class CliApp:
     CLI applications.
     """
 
+    @staticmethod
+    def _get_base_settings_cls(model_cls: type[Any]) -> type[BaseSettings]:
+        if issubclass(model_cls, BaseSettings):
+            return model_cls
+
+        class CliAppBaseSettings(BaseSettings, model_cls):  # type: ignore
+            __doc__ = model_cls.__doc__
+            model_config = SettingsConfigDict(
+                nested_model_default_partial_update=True,
+                case_sensitive=True,
+                cli_hide_none_type=True,
+                cli_avoid_json=True,
+                cli_enforce_required=True,
+                cli_implicit_flags=True,
+                cli_kebab_case=True,
+            )
+
+        return CliAppBaseSettings
+
     @staticmethod
     def _run_cli_cmd(model: Any, cli_cmd_method_name: str, is_required: bool) -> Any:
         command = getattr(type(model), cli_cmd_method_name, None)
@@ -575,22 +594,10 @@ def run(
         model_init_data['_cli_exit_on_error'] = cli_exit_on_error
         model_init_data['_cli_settings_source'] = cli_settings
         if not issubclass(model_cls, BaseSettings):
-
-            class CliAppBaseSettings(BaseSettings, model_cls):  # type: ignore
-                __doc__ = model_cls.__doc__
-                model_config = SettingsConfigDict(
-                    nested_model_default_partial_update=True,
-                    case_sensitive=True,
-                    cli_hide_none_type=True,
-                    cli_avoid_json=True,
-                    cli_enforce_required=True,
-                    cli_implicit_flags=True,
-                    cli_kebab_case=True,
-                )
-
-            model = CliAppBaseSettings(**model_init_data)
+            base_settings_cls = CliApp._get_base_settings_cls(model_cls)
+            model = base_settings_cls(**model_init_data)
             model_init_data = {}
-            for field_name, field_info in type(model).model_fields.items():
+            for field_name, field_info in base_settings_cls.model_fields.items():
                 model_init_data[_field_name_for_signature(field_name, field_info)] = getattr(model, field_name)
 
         return CliApp._run_cli_cmd(model_cls(**model_init_data), cli_cmd_method_name, is_required=False)
@@ -619,3 +626,18 @@ def run_subcommand(
 
         subcommand = get_subcommand(model, is_required=True, cli_exit_on_error=cli_exit_on_error)
         return CliApp._run_cli_cmd(subcommand, cli_cmd_method_name, is_required=True)
+
+    @staticmethod
+    def serialize(model: PydanticModel) -> list[str]:
+        """
+        Serializes the CLI arguments for a Pydantic data model.
+
+        Args:
+            model: The data model to serialize.
+
+        Returns:
+            The serialized CLI arguments for the data model.
+        """
+
+        base_settings_cls = CliApp._get_base_settings_cls(type(model))
+        return CliSettingsSource._serialized_args(model, base_settings_cls.model_config)
diff --git a/pydantic_settings/sources/providers/cli.py b/pydantic_settings/sources/providers/cli.py
@@ -35,7 +35,7 @@
 )
 
 import typing_extensions
-from pydantic import BaseModel, Field
+from pydantic import AliasChoices, AliasPath, BaseModel, Field, create_model
 from pydantic._internal._repr import Representation
 from pydantic._internal._utils import is_model_class
 from pydantic.dataclasses import is_pydantic_dataclass
@@ -47,7 +47,15 @@
 
 from ...exceptions import SettingsError
 from ...utils import _lenient_issubclass, _WithArgsTypes
-from ..types import NoDecode, _CliExplicitFlag, _CliImplicitFlag, _CliPositionalArg, _CliSubCommand, _CliUnknownArgs
+from ..types import (
+    NoDecode,
+    PydanticModel,
+    _CliExplicitFlag,
+    _CliImplicitFlag,
+    _CliPositionalArg,
+    _CliSubCommand,
+    _CliUnknownArgs,
+)
 from ..utils import (
     _annotation_contains_types,
     _annotation_enum_val_to_name,
@@ -1084,3 +1092,116 @@ def _help_format(
     def _is_field_suppressed(self, field_info: FieldInfo) -> bool:
         _help = field_info.description if field_info.description else ''
         return _help == CLI_SUPPRESS or CLI_SUPPRESS in field_info.metadata
+
+    @classmethod
+    def _update_alias_path_only_default(
+        cls, arg_name: str, value: Any, field_info: FieldInfo, alias_path_only_defaults: dict[str, Any]
+    ) -> tuple[str, list[Any] | dict[str, Any]]:
+        alias_path: AliasPath = [
+            alias if isinstance(alias, AliasPath) else cast(AliasPath, alias.choices[0])
+            for alias in (field_info.alias, field_info.validation_alias)
+            if isinstance(alias, (AliasPath, AliasChoices))
+        ][0]
+
+        alias_nested_paths: list[str] = alias_path.path[1:-1]  # type: ignore
+        if '.' in arg_name:
+            alias_nested_paths = arg_name.split('.') + alias_nested_paths
+            arg_name = alias_nested_paths.pop(0)
+
+        if not alias_nested_paths:
+            alias_path_only_defaults.setdefault(arg_name, [])
+            alias_default = alias_path_only_defaults[arg_name]
+        else:
+            alias_path_only_defaults.setdefault(arg_name, {})
+            current_path = alias_path_only_defaults[arg_name]
+
+            for nested_path in alias_nested_paths[:-1]:
+                current_path.setdefault(nested_path, {})
+                current_path = current_path[nested_path]
+            current_path.setdefault(alias_nested_paths[-1], [])
+            alias_default = current_path[alias_nested_paths[-1]]
+
+        alias_path_index = cast(int, alias_path.path[-1])
+        alias_default.extend([''] * max(alias_path_index + 1 - len(alias_default), 0))
+        alias_default[alias_path_index] = value
+        return arg_name, alias_path_only_defaults[arg_name]
+
+    @classmethod
+    def _serialized_args(cls, model: PydanticModel, model_config: Any, prefix: str = '') -> list[str]:
+        model_field_definitions: dict[str, Any] = {}
+        for field_name, field_info in _get_model_fields(type(model)).items():
+            model_default = getattr(model, field_name)
+            if field_info.default == model_default:
+                continue
+            if _CliSubCommand in field_info.metadata and model_default is None:
+                continue
+            model_field_definitions[field_name] = (field_info.annotation, field_info)
+        cli_serialize_cls = create_model('CliSerialize', __config__=model_config, **model_field_definitions)
+
+        added_args: set[str] = set()
+        alias_path_args: dict[str, str] = {}
+        alias_path_only_defaults: dict[str, Any] = {}
+        optional_args: list[str | list[Any] | dict[str, Any]] = []
+        positional_args: list[str | list[Any] | dict[str, Any]] = []
+        subcommand_args: list[str] = []
+        cli_settings = CliSettingsSource[Any](cli_serialize_cls)
+        for field_name, field_info in _get_model_fields(cli_serialize_cls).items():
+            model_default = getattr(model, field_name)
+            alias_names, is_alias_path_only = _get_alias_names(
+                field_name, field_info, alias_path_args=alias_path_args, case_sensitive=cli_settings.case_sensitive
+            )
+            preferred_alias = alias_names[0]
+            if _CliSubCommand in field_info.metadata:
+                subcommand_args.append(preferred_alias)
+                subcommand_args += cls._serialized_args(model_default, model_config)
+                continue
+            if is_model_class(type(model_default)) or is_pydantic_dataclass(type(model_default)):
+                positional_args += cls._serialized_args(
+                    model_default, model_config, prefix=f'{prefix}{preferred_alias}.'
+                )
+                continue
+
+            arg_name = f'{prefix}{cls._check_kebab_name(cli_settings, preferred_alias)}'
+            value: str | list[Any] | dict[str, Any] = (
+                json.dumps(model_default) if isinstance(model_default, (dict, list, set)) else str(model_default)
+            )
+
+            if is_alias_path_only:
+                # For alias path only, we wont know the complete value until we've finished parsing the entire class. In
+                # this case, insert value as a non-string reference pointing to the relevant alias_path_only_defaults
+                # entry and convert into completed string value later.
+                arg_name, value = cls._update_alias_path_only_default(
+                    arg_name, value, field_info, alias_path_only_defaults
+                )
+
+            if arg_name in added_args:
+                continue
+            added_args.add(arg_name)
+
+            if _CliPositionalArg in field_info.metadata:
+                if is_alias_path_only:
+                    positional_args.append(value)
+                    continue
+                for value in model_default if isinstance(model_default, list) else [model_default]:
+                    value = json.dumps(value) if isinstance(value, (dict, list, set)) else str(value)
+                    positional_args.append(value)
+                continue
+
+            flag_chars = f'{cli_settings.cli_flag_prefix_char * min(len(arg_name), 2)}'
+
+            kwargs = {'metavar': cls._metavar_format(cli_settings, field_info.annotation)}
+            cls._convert_bool_flag(cli_settings, kwargs, field_info, model_default)
+            # Note: cls._convert_bool_flag will add action to kwargs if value is implicit bool flag
+            if 'action' in kwargs and model_default is False:
+                flag_chars += 'no-'
+
+            optional_args.append(f'{flag_chars}{arg_name}')
+
+            # If implicit bool flag, do not add a value
+            if 'action' not in kwargs:
+                optional_args.append(value)
+
+        serialized_args: list[str] = []
+        serialized_args += [json.dumps(value) if not isinstance(value, str) else value for value in optional_args]
+        serialized_args += [json.dumps(value) if not isinstance(value, str) else value for value in positional_args]
+        return serialized_args + subcommand_args
diff --git a/tests/test_source_cli.py b/tests/test_source_cli.py
@@ -297,6 +297,21 @@ class Cfg(BaseSettings, cli_avoid_json=avoid_json):
         'alias_str': 'str',
     }
 
+    serialized_cli_args = CliApp.serialize(cfg)
+    assert serialized_cli_args == [
+        '-a',
+        'a',
+        '--path1',
+        '["", "b1"]',
+        '-b',
+        'b',
+        '--path2',
+        '{"deep": ["", "b2"]}',
+        '--str',
+        'str',
+    ]
+    assert CliApp.run(Cfg, cli_args=serialized_cli_args).model_dump() == cfg.model_dump()
+
 
 @pytest.mark.parametrize('avoid_json', [True, False])
 def test_cli_alias_nested_arg(capsys, monkeypatch, avoid_json):
@@ -333,6 +348,19 @@ class Cfg(BaseSettings, cli_avoid_json=avoid_json):
         }
     }
 
+    serialized_cli_args = CliApp.serialize(cfg)
+    assert serialized_cli_args == [
+        '--nest.a',
+        'a',
+        '--nest',
+        '{"path1": ["", "b1"], "path2": {"deep": ["", "b2"]}}',
+        '--nest.b',
+        'b',
+        '--nest.str',
+        'str',
+    ]
+    assert CliApp.run(Cfg, cli_args=serialized_cli_args).model_dump() == cfg.model_dump()
+
 
 def test_cli_alias_exceptions(capsys, monkeypatch):
     with pytest.raises(SettingsError, match='subcommand argument BadCliSubCommand.foo has multiple aliases'):
@@ -2574,3 +2602,9 @@ class Settings(BaseSettings):
         'nested': {'option': 'bar'},
         'option2': 'foo2',
     }
+
+
+# ADD TEST KEBAB CASE
+# ADD TEST SUBCOMMAND BEFORE POSITIONAL
+# ADD TEST IMPLICIT BOOL FLAGS
+# ADD TEST ONLY SERIALIZE NON-DEFAULT VALUES
