feat: Add cli_aliases to CLI settings

`cli_aliases` is a mapping of alias name to field path.

Author: karta9821

pydantic_settings/main.py

@@ -4,6 +4,7 @@
 import inspect
 import threading
 from argparse import Namespace
+from collections.abc import Mapping
 from types import SimpleNamespace
 from typing import Any, ClassVar, TypeVar
 
@@ -57,6 +58,7 @@ class SettingsConfigDict(ConfigDict, total=False):
     cli_implicit_flags: bool | None
     cli_ignore_unknown_args: bool | None
     cli_kebab_case: bool | None
+    cli_aliases: Mapping[str, str] | None
     secrets_dir: PathType | None
     json_file: PathType | None
     json_file_encoding: str | None
@@ -149,6 +151,7 @@ class BaseSettings(BaseModel):
             (e.g. --flag, --no-flag). Defaults to `False`.
         _cli_ignore_unknown_args: Whether to ignore unknown CLI args and parse only known ones. Defaults to `False`.
         _cli_kebab_case: CLI args use kebab case. Defaults to `False`.
+        _cli_aliases: Mapping of alias name to field path. Defaults to `None`.
         _secrets_dir: The secret files directory or a sequence of directories. Defaults to `None`.
     """
 
@@ -178,6 +181,7 @@ def __init__(
         _cli_implicit_flags: bool | None = None,
         _cli_ignore_unknown_args: bool | None = None,
         _cli_kebab_case: bool | None = None,
+        _cli_aliases: Mapping[str, str] | None = None,
         _secrets_dir: PathType | None = None,
         **values: Any,
     ) -> None:
@@ -208,6 +212,7 @@ def __init__(
                 _cli_implicit_flags=_cli_implicit_flags,
                 _cli_ignore_unknown_args=_cli_ignore_unknown_args,
                 _cli_kebab_case=_cli_kebab_case,
+                _cli_aliases=_cli_aliases,
                 _secrets_dir=_secrets_dir,
             )
         )
@@ -263,6 +268,7 @@ def _settings_build_values(
         _cli_implicit_flags: bool | None = None,
         _cli_ignore_unknown_args: bool | None = None,
         _cli_kebab_case: bool | None = None,
+        _cli_aliases: Mapping[str, str] | None = None,
         _secrets_dir: PathType | None = None,
     ) -> dict[str, Any]:
         # Determine settings config values
@@ -336,6 +342,7 @@ def _settings_build_values(
             else self.model_config.get('cli_ignore_unknown_args')
         )
         cli_kebab_case = _cli_kebab_case if _cli_kebab_case is not None else self.model_config.get('cli_kebab_case')
+        cli_aliases = _cli_aliases if _cli_aliases is not None else self.model_config.get('cli_aliases')
 
         secrets_dir = _secrets_dir if _secrets_dir is not None else self.model_config.get('secrets_dir')
 
@@ -401,6 +408,7 @@ def _settings_build_values(
                     cli_implicit_flags=cli_implicit_flags,
                     cli_ignore_unknown_args=cli_ignore_unknown_args,
                     cli_kebab_case=cli_kebab_case,
+                    cli_aliases=cli_aliases,
                     case_sensitive=case_sensitive,
                 )
                 sources = (cli_settings,) + sources
@@ -450,6 +458,7 @@ def _settings_build_values(
         cli_implicit_flags=False,
         cli_ignore_unknown_args=False,
         cli_kebab_case=False,
+        cli_aliases=None,
         json_file=None,
         json_file_encoding=None,
         yaml_file=None,

pydantic_settings/sources/providers/cli.py

@@ -119,6 +119,7 @@ class CliSettingsSource(EnvSettingsSource, Generic[T]):
             (e.g. --flag, --no-flag). Defaults to `False`.
         cli_ignore_unknown_args: Whether to ignore unknown CLI args and parse only known ones. Defaults to `False`.
         cli_kebab_case: CLI args use kebab case. Defaults to `False`.
+        cli_aliases: Mapping of alias name to field path. Defaults to `None`.
         case_sensitive: Whether CLI "--arg" names should be read with case-sensitivity. Defaults to `True`.
             Note: Case-insensitive matching is only supported on the internal root parser and does not apply to CLI
             subcommands.
@@ -150,6 +151,7 @@ def __init__(
         cli_implicit_flags: bool | None = None,
         cli_ignore_unknown_args: bool | None = None,
         cli_kebab_case: bool | None = None,
+        cli_aliases: Mapping[str, str] | None = None,
         case_sensitive: bool | None = True,
         root_parser: Any = None,
         parse_args_method: Callable[..., Any] | None = None,
@@ -215,6 +217,9 @@ def __init__(
         self.cli_kebab_case = (
             cli_kebab_case if cli_kebab_case is not None else settings_cls.model_config.get('cli_kebab_case', False)
         )
+        self.cli_aliases = (
+            cli_aliases if cli_aliases is not None else settings_cls.model_config.get('cli_aliases', None)
+        )
 
         case_sensitive = case_sensitive if case_sensitive is not None else True
         if not case_sensitive and root_parser is not None:
@@ -767,6 +772,11 @@ def _add_parser_args(
                     else f'{arg_prefix}{preferred_alias}'
                 )
 
+                if self.cli_aliases and kwargs['dest'] in self.cli_aliases:
+                    raise SettingsError(
+                        f'{model.__name__}.{field_name} has multiple aliases: {preferred_alias} and {self.cli_aliases[kwargs["dest"]]}'
+                    )
+
                 arg_names = self._get_arg_names(arg_prefix, subcommand_prefix, alias_prefixes, alias_names, added_args)
                 if not arg_names or (kwargs['dest'] in added_args):
                     continue
@@ -874,6 +884,12 @@ def _get_arg_names(
                 )
                 if arg_name not in added_args:
                     arg_names.append(arg_name)
+
+        if self.cli_aliases:
+            for alias, name in self.cli_aliases.items():
+                if name in arg_names and alias not in added_args:
+                    arg_names.append(alias)
+
         return arg_names
 
     def _add_parser_submodels(

tests/test_source_cli.py

@@ -2525,3 +2525,38 @@ def settings_customise_sources(
         cfg = CliApp.run(MySettings)
 
         assert cfg.model_dump() == {'foo': 'bar'}
+
+
+def test_cli_aliases_on_flat_object():
+    class Settings(BaseSettings):
+        option: str = Field(default='foo')
+
+        model_config = SettingsConfigDict(cli_aliases={'option2': 'option'})
+
+    assert CliApp.run(Settings, cli_args=['--option2', 'bar']).model_dump() == {'option': 'bar'}
+
+
+def test_cli_aliases_on_nested_object():
+    class Nested(BaseModel):
+        option: str = Field(default='foo')
+
+    class Settings(BaseSettings):
+        nested: Nested = Nested()
+
+        model_config = SettingsConfigDict(cli_aliases={'option2': 'nested.option'})
+
+    assert CliApp.run(Settings, cli_args=['--option2', 'bar']).model_dump() == {'nested': {'option': 'bar'}}
+
+
+def test_cli_aliases_name_collision():
+    class Nested(BaseModel):
+        option: str = Field(default='foo')
+
+    class Settings(BaseSettings):
+        nested: Nested = Nested()
+        option2: str = Field(default='foo2')
+
+        model_config = SettingsConfigDict(cli_aliases={'option2': 'nested.option'})
+
+    with pytest.raises(SettingsError, match='Settings.option2 has multiple aliases: option2 and nested.option'):
+        CliApp.run(Settings, cli_args=['--option2', 'bar'])