Docs.

Author: kschwab

docs/index.md

@@ -1331,6 +1331,71 @@ class ImplicitSettings(BaseSettings, cli_parse_args=True, cli_implicit_flags=Tru
     """
 ```
 
+Implicit flag behavior can be further refined using the "toggle" or "dual" mode settings. Similarly, the provided
+`CliToggleFlag` and `CliDualFlag` annotations can be used for more granular control.
+
+For "toggle" flags, if default=`False`, `--flag` will store `True`. Otherwise, if default=`True`, `--no-flag` will store
+`False`.
+
+```py
+from pydantic_settings import BaseSettings, CliDualFlag, CliToggleFlag
+
+
+class ImplicitDualSettings(
+    BaseSettings, cli_parse_args=True, cli_implicit_flags='dual'
+):
+    """With cli_implicit_flags='dual', implicit flags are dual by default."""
+
+    implicit_req: bool
+    """
+    --implicit_req, --no-implicit_req (required)
+    """
+
+    implicit_dual_opt: bool = False
+    """
+    --implicit_dual_opt, --no-implicit_dual_opt (default: False)
+    """
+
+    # Implicit flags are dual by default, so must override toggle flags with annotation
+    flag_a: CliToggleFlag[bool] = False
+    """
+    --flag_a (default: False)
+    """
+
+    # Implicit flags are dual by default, so must override toggle flags with annotation
+    flag_b: CliToggleFlag[bool] = True
+    """
+    --no-flag_b (default: True)
+    """
+
+
+class ImplicitToggleSettings(
+    BaseSettings, cli_parse_args=True, cli_implicit_flags='toggle'
+):
+    """With cli_implicit_flags='toggle', implicit flags are toggle by default."""
+
+    implicit_req: bool
+    """
+    --implicit_req, --no-implicit_req (required)
+    """
+
+    # Implicit flags are toggle by default, so must override dual flags with annotation
+    implicit_dual_opt: CliDualFlag[bool] = False
+    """
+    --implicit_dual_opt, --no-implicit_dual_opt (default: False)
+    """
+
+    flag_a: bool = False
+    """
+    --flag_a (default: False)
+    """
+
+    flag_b: bool = True
+    """
+    --no-flag_b (default: True)
+    """
+```
+
 #### Ignore and Retrieve Unknown Arguments
 
 Change whether to ignore unknown CLI arguments and only parse known ones using `cli_ignore_unknown_args`. By default, the CLI

pydantic_settings/main.py

@@ -61,7 +61,7 @@ class SettingsConfigDict(ConfigDict, total=False):
     cli_exit_on_error: bool
     cli_prefix: str
     cli_flag_prefix_char: str
-    cli_implicit_flags: bool | None
+    cli_implicit_flags: bool | Literal['dual', 'toggle'] | None
     cli_ignore_unknown_args: bool | None
     cli_kebab_case: bool | Literal['all', 'no_enums'] | None
     cli_shortcuts: Mapping[str, str | list[str]] | None
@@ -153,8 +153,12 @@ class BaseSettings(BaseModel):
             Defaults to `True`.
         _cli_prefix: The root parser command line arguments prefix. Defaults to "".
         _cli_flag_prefix_char: The flag prefix character to use for CLI optional arguments. Defaults to '-'.
-        _cli_implicit_flags: Whether `bool` fields should be implicitly converted into CLI boolean flags.
-            (e.g. --flag, --no-flag). Defaults to `False`.
+        _cli_implicit_flags: Controls how `bool` fields are exposed as CLI flags.
+
+            - False (default): no implicit flags are generated; booleans must be set explicitly (e.g. --flag=true).
+            - True / 'dual': optional boolean fields generate both positive and negative forms (--flag and --no-flag).
+            - 'toggle': required boolean fields remain in 'dual' mode, while optional boolean fields generate a single
+              flag aligned with the default value (if default=False, expose --flag; if default=True, expose --no-flag).
         _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_shortcuts: Mapping of target field name to alias names. Defaults to `None`.
@@ -184,7 +188,7 @@ def __init__(
         _cli_exit_on_error: bool | None = None,
         _cli_prefix: str | None = None,
         _cli_flag_prefix_char: str | None = None,
-        _cli_implicit_flags: bool | None = None,
+        _cli_implicit_flags: bool | Literal['dual', 'toggle'] | None = None,
         _cli_ignore_unknown_args: bool | None = None,
         _cli_kebab_case: bool | Literal['all', 'no_enums'] | None = None,
         _cli_shortcuts: Mapping[str, str | list[str]] | None = None,
@@ -271,7 +275,7 @@ def _settings_build_values(
         _cli_exit_on_error: bool | None = None,
         _cli_prefix: str | None = None,
         _cli_flag_prefix_char: str | None = None,
-        _cli_implicit_flags: bool | None = None,
+        _cli_implicit_flags: bool | Literal['dual', 'toggle'] | None = None,
         _cli_ignore_unknown_args: bool | None = None,
         _cli_kebab_case: bool | Literal['all', 'no_enums'] | None = None,
         _cli_shortcuts: Mapping[str, str | list[str]] | None = None,

pydantic_settings/sources/providers/cli.py

@@ -274,8 +274,12 @@ class CliSettingsSource(EnvSettingsSource, Generic[T]):
             Defaults to `True`.
         cli_prefix: Prefix for command line arguments added under the root parser. Defaults to "".
         cli_flag_prefix_char: The flag prefix character to use for CLI optional arguments. Defaults to '-'.
-        cli_implicit_flags: Whether `bool` fields should be implicitly converted into CLI boolean flags.
-            (e.g. --flag, --no-flag). Defaults to `False`.
+        cli_implicit_flags: Controls how `bool` fields are exposed as CLI flags.
+
+            - False (default): no implicit flags are generated; booleans must be set explicitly (e.g. --flag=true).
+            - True / 'dual': optional boolean fields generate both positive and negative forms (--flag and --no-flag).
+            - 'toggle': required boolean fields remain in 'dual' mode, while optional boolean fields generate a single
+              flag aligned with the default value (if default=False, expose --flag; if default=True, expose --no-flag).
         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_shortcuts: Mapping of target field name to alias names. Defaults to `None`.
@@ -307,7 +311,7 @@ def __init__(
         cli_exit_on_error: bool | None = None,
         cli_prefix: str | None = None,
         cli_flag_prefix_char: str | None = None,
-        cli_implicit_flags: bool | None = None,
+        cli_implicit_flags: bool | Literal['dual', 'toggle'] | None = None,
         cli_ignore_unknown_args: bool | None = None,
         cli_kebab_case: bool | Literal['all', 'no_enums'] | None = None,
         cli_shortcuts: Mapping[str, str | list[str]] | None = None,
@@ -1011,7 +1015,9 @@ def _add_parser_args(
                     if isinstance(group, dict):
                         group = self._add_group(parser, **group)
                     context = parser if group is None else group
-                    arg.args = [f'{flag_prefix[: len(name)]}{name}' for name in arg_names]
+                    if arg.kwargs.get('action') == 'store_false':
+                        flag_prefix += 'no-'
+                    arg.args = [f'{flag_prefix[: 1 if len(name) == 1 else None]}{name}' for name in arg_names]
                     self._add_argument(context, *arg.args, **arg.kwargs)
                     added_args += list(arg_names)
 
@@ -1366,7 +1372,11 @@ def _serialized_args(self, model: PydanticModel, _is_submodel: bool = False) ->
                 continue
 
             # Note: prepend 'no-' for boolean optional action flag if model_default value is False and flag is not a short option
-            if arg.kwargs.get('action') == BooleanOptionalAction and model_default is False and flag_chars == '--':
+            if (
+                arg.kwargs.get('action') in (BooleanOptionalAction, 'store_false')
+                and model_default is False
+                and flag_chars == '--'
+            ):
                 flag_chars += 'no-'
 
             optional_args.append(f'{flag_chars}{arg_name}')