flet-cli 1.0.0.dev2__tar.gz → 1.0.2__tar.gz

{flet_cli-1.0.0.dev2 → flet_cli-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flet-cli
-Version: 1.0.0.dev2
+Version: 1.0.2
 Summary: Flet CLI
 Author-email: "Appveyor Systems Inc." <hello@flet.dev>
 License-Expression: Apache-2.0
@@ -9,8 +9,8 @@ Project-URL: Repository, https://github.com/flet-dev/flet
 Project-URL: Documentation, https://flet.dev/docs
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
-Requires-Dist: flet==1.0.0.dev2
-Requires-Dist: flet-platform-assets==1.0.0.dev2
+Requires-Dist: flet==1.0.2
+Requires-Dist: flet-platform-assets==1.0.2
 Requires-Dist: watchdog>=4.0.0
 Requires-Dist: packaging>=25.0
 Requires-Dist: qrcode>=7.4.2
@@ -29,6 +29,10 @@ Requires-Dist: flet-mcp; extra == "mcp"
 
 Flet CLI is a command-line interface tool for Flet, a framework for building interactive multi-platform applications using Python.
 
+> **[Try Flet online in Flet Studio](https://studio.flet.dev)**
+>
+> Try an idea in your browser with no installation, then use the Flet CLI locally to develop and package your app. Write your own Python code or get help from the AI agent.
+
 ## Features
 
 - Create new Flet projects

{flet_cli-1.0.0.dev2 → flet_cli-1.0.2}/README.md

@@ -5,6 +5,10 @@
 
 Flet CLI is a command-line interface tool for Flet, a framework for building interactive multi-platform applications using Python.
 
+> **[Try Flet online in Flet Studio](https://studio.flet.dev)**
+>
+> Try an idea in your browser with no installation, then use the Flet CLI locally to develop and package your app. Write your own Python code or get help from the AI agent.
+
 ## Features
 
 - Create new Flet projects

{flet_cli-1.0.0.dev2 → flet_cli-1.0.2}/pyproject.toml

@@ -1,14 +1,14 @@
 [project]
 name = "flet-cli"
-version = "1.0.0.dev2"
+version = "1.0.2"
 description = "Flet CLI"
 authors = [{ name = "Appveyor Systems Inc.", email = "hello@flet.dev" }]
 license = "Apache-2.0"
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
-    "flet==1.0.0.dev2",
-    "flet-platform-assets==1.0.0.dev2",
+    "flet==1.0.2",
+    "flet-platform-assets==1.0.2",
     "watchdog >=4.0.0",
     "packaging >=25.0",
     "qrcode >=7.4.2",

{flet_cli-1.0.0.dev2 → flet_cli-1.0.2}/src/flet_cli/cli.py

@@ -41,6 +41,34 @@ def _render_version(as_json: bool) -> str:
     return f"Flet: {flet.version.flet_version}\nFlutter: {flet.version.flutter_version}"
 
 
+class _PositionalsFixArgumentParser(argparse.ArgumentParser):
+    """
+    An `argparse.ArgumentParser` with the fix for CPython gh-59317 backported.
+
+    Before Python 3.12.7 and 3.13.1, `argparse` gives an optional positional its
+    default as soon as the positionals typed before an option run out, so one
+    typed after the option is rejected. `get_parser()` uses this class only on
+    those interpreters, and subparsers inherit it through `add_subparsers()`.
+    """
+
+    def _match_arguments_partial(self, actions, arg_strings_pattern):
+        """
+        Match positionals as Python 3.12.7+ and 3.13.1+ do: when the typed
+        positionals end at an option, the trailing positionals that matched
+        nothing are left unfilled, so positionals after the option can fill them.
+
+        The matched counts add up to the length of the matched pattern, so the
+        result is unchanged on interpreters whose `argparse` already does this.
+        """
+
+        result = super()._match_arguments_partial(actions, arg_strings_pattern)
+        matched = sum(result)
+        if matched < len(arg_strings_pattern) and arg_strings_pattern[matched] == "O":
+            while result and not result[-1]:
+                result.pop()
+        return result
+
+
 # Source https://stackoverflow.com/a/26379693
 def set_default_subparser(
     parser: argparse.ArgumentParser, name: str, args: list
@@ -88,9 +116,11 @@ def set_default_subparser(
 
 def get_parser() -> argparse.ArgumentParser:
     """Construct and return the CLI argument parser."""
-    parser = argparse.ArgumentParser(
-        formatter_class=argparse.RawDescriptionHelpFormatter
-    )
+    parser = (
+        _PositionalsFixArgumentParser
+        if sys.version_info < (3, 12, 7) or sys.version_info[:3] == (3, 13, 0)
+        else argparse.ArgumentParser
+    )(formatter_class=argparse.RawDescriptionHelpFormatter)
 
     # add version flags
     parser.add_argument(
@@ -138,9 +168,11 @@ def split_script_args(argv: list) -> tuple[list, Optional[list]]:
     """
     Split a command line at the first bare `--` separator.
 
-    Everything after the separator is meant for the app script, not for Flet
+    Everything after the separator is meant for the program the command runs -
+    the app script of `flet run`, pytest for `flet test`, Flutter for
+    `flet build` and `flet debug`, or PyInstaller for `flet pack` - not for Flet
     itself, so it must be removed before the parser (and `set_default_subparser`)
-    sees it - otherwise `flet run app.py -- --web` would be read as Flet's own
+    sees it. Otherwise `flet run app.py -- --web` would be read as Flet's own
     `--web` option, and `flet app.py -- build` would suppress the default `run`
     subcommand.
 
@@ -169,10 +201,14 @@ def parse_command_line(argv: list) -> argparse.Namespace:
 
     Returns:
         The parsed arguments. For `flet run`, `script_args` holds the arguments
-        to forward to the app script.
+        to forward to the app script, for `flet test`, `pytest_args` holds the
+        arguments to pass to pytest, for `flet build` and `flet debug`,
+        `flutter_build_args` holds the arguments to pass to Flutter, and for
+        `flet pack`, `pyinstaller_build_args` holds the arguments to pass to
+        PyInstaller.
     """
 
-    # pull off the arguments meant for the app script before the parser sees them
+    # pull off arguments meant for the program the command runs before parser sees them
     argv, script_args = split_script_args(argv)
 
     parser = get_parser()
@@ -195,14 +231,32 @@ def parse_command_line(argv: list) -> argparse.Namespace:
             )
         parser.error(message)
 
-    # forward the arguments that followed `--` to the app script
+    # forward the arguments that followed `--` to the program the command runs
     if script_args is not None:
-        if getattr(args, "command", None) != "run":
+        command = getattr(args, "command", None)
+        if command == "run":
+            args.script_args = list(args.script_args) + script_args
+        elif command == "test":
+            args.pytest_args = script_args
+        elif command in ("build", "debug"):
+            if script_args:
+                args.flutter_build_args = [
+                    *(args.flutter_build_args or []),
+                    script_args,
+                ]
+        elif command == "pack":
+            if script_args:
+                args.pyinstaller_build_args = [
+                    *(args.pyinstaller_build_args or []),
+                    script_args,
+                ]
+        else:
             parser.error(
-                "the `--` separator is only supported by `flet run`, to pass "
-                "the arguments that follow it to your app script"
+                "the `--` separator is only supported by commands that run "
+                "another program, which receives the arguments that follow it: "
+                "`flet run` (the app script), `flet test` (pytest), `flet build` "
+                "and `flet debug` (Flutter), and `flet pack` (PyInstaller)"
             )
-        args.script_args = list(args.script_args) + script_args
 
     return args
 

{flet_cli-1.0.0.dev2 → flet_cli-1.0.2}/src/flet_cli/commands/build.py

@@ -43,6 +43,8 @@ class Command(BaseBuildCommand):
     Android (APK/AAB), and iOS (IPA and simulator .app), with a wide range of
     customization options for metadata, assets, splash screens, and signing.
 
+    Arguments after `--` are passed down to the underlying `flutter build`.
+
     Detailed usage guide: https://flet.dev/docs/publish
     """
 
@@ -206,11 +208,7 @@ class Command(BaseBuildCommand):
         if build_version:
             args.extend(["--build-name", build_version])
 
-        for arg in (
-            self.get_pyproject(f"tool.flet.{self.config_platform}.flutter.build_args")
-            or self.get_pyproject("tool.flet.flutter.build_args")
-            or []
-        ):
+        for arg in self.get_platform_setting("flutter.build_args", []):
             args.append(arg)
 
     def run_flutter(self):

{flet_cli-1.0.0.dev2 → flet_cli-1.0.2}/src/flet_cli/commands/build_base.py

@@ -28,6 +28,7 @@ from flet_platform_assets import (
     write,
 )
 from packaging.requirements import Requirement
+from rich.markup import escape
 from rich.panel import Panel
 from rich.table import Column, Table
 
@@ -42,10 +43,12 @@ from flet_cli.commands.flutter_base import (
     verbose2_style,
     warning_style,
 )
+from flet_cli.commands.options import PassThroughArgsAction
 from flet_cli.utils.android import (
     ANDROID_ARCH_TO_FLUTTER_TARGET_PLATFORM,
     excluded_android_abis,
 )
+from flet_cli.utils.app_excludes import find_default_excludes
 from flet_cli.utils.cli import parse_cli_bool_value
 from flet_cli.utils.hash_stamp import HashStamp
 from flet_cli.utils.merge import merge_dict
@@ -358,6 +361,23 @@ class BaseBuildCommand(BaseFlutterCommand):
             help="Files and/or directories to exclude from the package"
             "; can be used multiple times",
         )
+        parser.add_argument(
+            "--include",
+            dest="include",
+            action="extend",
+            nargs="+",
+            default=[],
+            help="Files and/or directories excluded by default to package anyway "
+            "(e.g. `.env`); can be used multiple times",
+        )
+        parser.add_argument(
+            "--no-default-excludes",
+            dest="default_excludes",
+            action="store_false",
+            default=None,
+            help="Package hidden top-level files and directories, virtual "
+            "environments and `__pycache__` directories instead of excluding them",
+        )
         parser.add_argument(
             "--project",
             dest="project_name",
@@ -619,9 +639,12 @@ class BaseBuildCommand(BaseFlutterCommand):
         parser.add_argument(
             "--flutter-build-args",
             dest="flutter_build_args",
-            action="append",
+            action=PassThroughArgsAction,
+            example="--obfuscate",
             nargs="*",
-            help="Additional arguments for flutter build command",
+            help="Additional arguments for flutter build command. Attach an "
+            "argument that starts with `-` using `=`, e.g. "
+            "`--flutter-build-args=--obfuscate`, or pass the arguments after `--`",
         )
         parser.add_argument(
             "--source-packages",
@@ -634,6 +657,7 @@ class BaseBuildCommand(BaseFlutterCommand):
         parser.add_argument(
             "--android-extract-packages",
             dest="android_extract_packages",
+            action="extend",
             nargs="+",
             default=[],
             help="Android only: Python packages (relative paths) to ship extracted "
@@ -860,19 +884,25 @@ class BaseBuildCommand(BaseFlutterCommand):
         self.config_platform = self.platforms[self.target_platform]["config_platform"]
         self.require_android_sdk = self.package_platform == "Android"
 
-        super().initialize_command()
-
         self.python_app_path = Path(self.options.python_app_path).resolve()
 
-        if not (
-            os.path.exists(self.python_app_path) or os.path.isdir(self.python_app_path)
-        ):
+        # validate that the app path exists and is a directory, not a file
+        if not os.path.isdir(self.python_app_path):
+            self.skip_flutter_doctor = True
+            if os.path.isfile(self.python_app_path):
+                self.cleanup(
+                    1,
+                    f"Path to Flet app must be a directory, not a file: "
+                    f"{escape(str(self.python_app_path))}",
+                )
             self.cleanup(
                 1,
                 f"Path to Flet app does not exist or is not a directory: "
-                f"{self.python_app_path}",
+                f"{escape(str(self.python_app_path))}",
             )
 
+        super().initialize_command()
+
         self.rel_out_dir = self.options.output_dir or os.path.join(
             "build", self.platforms[self.target_platform]["dist"]
         )
@@ -1366,10 +1396,8 @@ class BaseBuildCommand(BaseFlutterCommand):
             deep_linking_scheme = self.options.deep_linking_scheme
             deep_linking_host = self.options.deep_linking_host
 
-        target_arch = (
-            self.options.target_arch
-            or self.get_pyproject(f"tool.flet.{self.config_platform}.target_arch")
-            or self.get_pyproject("tool.flet.target_arch")
+        target_arch = self.options.target_arch or self.get_platform_setting(
+            "target_arch"
         )
         target_arch = (
             target_arch
@@ -2532,11 +2560,7 @@ class BaseBuildCommand(BaseFlutterCommand):
 
         dev_packages_configured = False
         if len(toml_dependencies) > 0:
-            dev_packages = (
-                self.get_pyproject(f"tool.flet.{self.config_platform}.dev_packages")
-                or self.get_pyproject("tool.flet.dev_packages")
-                or []
-            )
+            dev_packages = self.get_platform_setting("dev_packages", {})
             if len(dev_packages) > 0:
                 for i in range(0, len(toml_dependencies)):
                     package_name = Requirement(toml_dependencies[i]).name
@@ -2616,25 +2640,63 @@ class BaseBuildCommand(BaseFlutterCommand):
         )
 
         # exclude
-        exclude_list = ["build"]
-
-        app_exclude = (
-            self.options.exclude
-            or self.get_pyproject(f"tool.flet.{self.config_platform}.app.exclude")
-            or self.get_pyproject("tool.flet.app.exclude")
+        app_exclude = self.options.exclude or self.get_platform_setting(
+            "app.exclude", []
         )
-        if app_exclude:
-            exclude_list.extend(app_exclude)
+        explicit_excludes = [
+            "build",
+            *app_exclude,
+            *(["assets"] if self.target_platform == "web" else []),
+        ]
 
-        if self.target_platform == "web":
-            exclude_list.append("assets")
-        package_args.extend(["--exclude", ",".join(exclude_list)])
+        default_excludes: list[str] = []
+        if self.get_bool_setting(
+            self.options.default_excludes, "app.default_excludes", True
+        ):
+            app_include = self.options.include or self.get_platform_setting(
+                "app.include", []
+            )
+            default_excludes = find_default_excludes(
+                self.package_app_path, app_include, explicit_excludes
+            )
+
+        exclude_list = list(dict.fromkeys(explicit_excludes + default_excludes))
+        # one flag per path: serious_python (>= 5.0.0) doesn't split values on
+        # commas, so paths containing `,` survive
+        for path in exclude_list:
+            package_args.extend(["--exclude", path])
+
+        if default_excludes:
+            console.log(
+                "Excluded from app package by default: "
+                f"{', '.join(default_excludes)} "
+                "(use --include <path> or --no-default-excludes to package them)",
+                markup=False,
+            )
+            env_files = [
+                p for p in default_excludes if p == ".env" or p.startswith(".env.")
+            ]
+            if env_files:
+                it = "it" if len(env_files) == 1 else "them"
+                console.log(
+                    f"Warning: {', '.join(env_files)} not packaged. If the app "
+                    f"loads {it} at runtime (e.g. with python-dotenv), package "
+                    f"{it} with `--include {' '.join(env_files)}` or "
+                    f"`include = {json.dumps(env_files)}` under [tool.flet.app] "
+                    "in pyproject.toml.",
+                    style=warning_style,
+                    markup=False,
+                )
+        if self.verbose > 0:
+            console.log(
+                f"App package exclude list: {exclude_list}",
+                style=verbose1_style,
+                markup=False,
+            )
 
         # source-packages
-        source_packages = (
-            self.options.source_packages
-            or self.get_pyproject(f"tool.flet.{self.config_platform}.source_packages")
-            or self.get_pyproject("tool.flet.source_packages")
+        source_packages = self.options.source_packages or self.get_platform_setting(
+            "source_packages"
         )
         if source_packages:
             package_env["SERIOUS_PYTHON_ALLOW_SOURCE_DISTRIBUTIONS"] = ",".join(
@@ -2651,11 +2713,7 @@ class BaseBuildCommand(BaseFlutterCommand):
         if self.package_platform == "Android":
             user_extract_packages = (
                 self.options.android_extract_packages
-                or self.get_pyproject(
-                    f"tool.flet.{self.config_platform}.extract_packages"
-                )
-                or self.get_pyproject("tool.flet.extract_packages")
-                or []
+                or self.get_platform_setting("extract_packages", [])
             )
             self.android_extract_packages = list(
                 dict.fromkeys(ANDROID_DEFAULT_EXTRACT_PACKAGES + user_extract_packages)
@@ -2678,42 +2736,34 @@ class BaseBuildCommand(BaseFlutterCommand):
 
         if cleanup_app_files := (
             self.options.cleanup_app_files
-            or self.get_pyproject(f"tool.flet.{self.config_platform}.cleanup.app_files")
-            or self.get_pyproject("tool.flet.cleanup.app_files")
+            or self.get_platform_setting("cleanup.app_files")
         ):
             if isinstance(cleanup_app_files, str):
                 cleanup_app_files = [
                     value.strip() for value in cleanup_app_files.split(",")
                 ]
             if isinstance(cleanup_app_files, list):
-                package_args.extend(
-                    [
-                        "--cleanup-app-files",
-                        ",".join([v.strip() for v in cleanup_app_files if v.strip()]),
-                    ]
-                )
+                for glob_pattern in cleanup_app_files:
+                    if glob_pattern.strip():
+                        package_args.extend(
+                            ["--cleanup-app-files", glob_pattern.strip()]
+                        )
                 cleanup_app = True
 
         if cleanup_package_files := (
             self.options.cleanup_package_files
-            or self.get_pyproject(
-                f"tool.flet.{self.config_platform}.cleanup.package_files"
-            )
-            or self.get_pyproject("tool.flet.cleanup.package_files")
+            or self.get_platform_setting("cleanup.package_files")
         ):
             if isinstance(cleanup_package_files, str):
                 cleanup_package_files = [
                     value for value in cleanup_package_files.split(",")
                 ]
             if isinstance(cleanup_package_files, list):
-                package_args.extend(
-                    [
-                        "--cleanup-package-files",
-                        ",".join(
-                            [v.strip() for v in cleanup_package_files if v.strip()]
-                        ),
-                    ]
-                )
+                for glob_pattern in cleanup_package_files:
+                    if glob_pattern.strip():
+                        package_args.extend(
+                            ["--cleanup-package-files", glob_pattern.strip()]
+                        )
                 cleanup_packages = True
 
         if cleanup_app:
@@ -2722,6 +2772,15 @@ class BaseBuildCommand(BaseFlutterCommand):
         if cleanup_packages:
             package_args.append("--cleanup-packages")
 
+        if self.verbose > 0:
+            console.log(
+                f"Compile app: {'--compile-app' in package_args}, "
+                f"cleanup app: {cleanup_app}, cleanup packages: {cleanup_packages} "
+                "(cleanup removes serious_python's default junk globs plus any "
+                "--cleanup-app-files/--cleanup-package-files)",
+                style=verbose1_style,
+            )
+
         if self.verbose > 1:
             package_args.append("--verbose")
 
@@ -2840,24 +2899,39 @@ class BaseBuildCommand(BaseFlutterCommand):
             Resolved boolean-like setting value.
         """
 
-        assert self.get_pyproject
         return (
             cli_option
             if cli_option is not None
-            else (
-                self.get_pyproject(f"tool.flet.{self.config_platform}.{pyproj_setting}")
-                if self.get_pyproject(
-                    f"tool.flet.{self.config_platform}.{pyproj_setting}"
-                )
-                is not None
-                else (
-                    self.get_pyproject(f"tool.flet.{pyproj_setting}")
-                    if self.get_pyproject(f"tool.flet.{pyproj_setting}") is not None
-                    else default_value
-                )
-            )
+            else self.get_platform_setting(pyproj_setting, default_value)
         )
 
+    def get_platform_setting(self, pyproj_setting, default_value=None):
+        """
+        Resolve a pyproject setting with precedence: platform, global, default.
+
+        The platform value wins whenever it is set, even when it is empty, so
+        `[]` or `{}` under `tool.flet.<platform>.` clears a global list or table
+        for that platform.
+
+        Args:
+            pyproj_setting: Relative key under `tool.flet.<platform>.` and
+                `tool.flet.`.
+            default_value: Fallback value when neither key is defined.
+
+        Returns:
+            Resolved setting value.
+        """
+
+        assert self.get_pyproject
+        for key in (
+            f"tool.flet.{self.config_platform}.{pyproj_setting}",
+            f"tool.flet.{pyproj_setting}",
+        ):
+            value = self.get_pyproject(key)
+            if value is not None:
+                return value
+        return default_value
+
     def add_flutter_command_args(self, args: list[str]):
         """
         Hook for subclasses to append command-specific Flutter arguments.
@@ -3001,10 +3075,7 @@ class BaseBuildCommand(BaseFlutterCommand):
 
         flutter_build_args = (
             self.options.flutter_build_args
-            or self.get_pyproject(
-                f"tool.flet.{self.config_platform}.flutter.build_args"
-            )
-            or self.get_pyproject("tool.flet.flutter.build_args")
+            or self.get_platform_setting("flutter.build_args")
         )
         if flutter_build_args:
             if isinstance(flutter_build_args, (list, tuple)):

{flet_cli-1.0.0.dev2 → flet_cli-1.0.2}/src/flet_cli/commands/debug.py

@@ -13,6 +13,8 @@ class Command(BaseBuildCommand):
     """
     Run a Flet Python app in debug mode on a specified platform (desktop, web, mobile).
 
+    Arguments after `--` are passed down to the underlying `flutter run`.
+
     Detailed usage guide: https://flet.dev/blog/flet-debug-the-new-cli-for-testing-flet-apps-on-mobile-devices
     """
 

flet_cli-1.0.2/src/flet_cli/commands/options.py

@@ -0,0 +1,78 @@
+import argparse
+from typing import Any
+
+
+class Option:
+    """A reusable option object which delegates all arguments
+    to parser.add_argument().
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        self.args = args
+        self.kwargs = kwargs
+
+    def add_to_parser(self, parser: argparse._ActionsContainer) -> None:
+        """
+        Add this option definition to an argument parser or compatible container.
+
+        Args:
+            parser: Parser-like object exposing `add_argument()`.
+        """
+
+        parser.add_argument(*self.args, **self.kwargs)
+
+    def add_to_group(self, group: argparse._ArgumentGroup) -> None:
+        """
+        Add this option definition to an argument group.
+
+        Args:
+            group: Argument group that receives the option.
+        """
+
+        group.add_argument(*self.args, **self.kwargs)
+
+
+class PassThroughArgsAction(argparse.Action):
+    """
+    Collect the values of each occurrence of an option that passes arguments on
+    to another program, as one list per occurrence.
+
+    A value that starts with `-` is read as an option of its own unless it is
+    attached with `=`, which leaves the occurrence without values and hands the
+    value to whichever Flet option it names. An occurrence without values is
+    therefore rejected, with a hint to attach the value or to pass it after
+    `--`.
+    """
+
+    def __init__(self, option_strings, dest, example: str, **kwargs):
+        """
+        Args:
+            option_strings: The option strings of the option.
+            dest: The attribute that receives the collected values.
+            example: A value that starts with `-`, shown in the hint.
+            **kwargs: The other `add_argument()` arguments.
+        """
+
+        super().__init__(option_strings, dest, **kwargs)
+        self.example = example
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        if not values:
+            raise argparse.ArgumentError(
+                self,
+                "expected at least one argument - attach one that starts with "
+                f"`-` using `=`, e.g. `{self.option_strings[0]}={self.example}`, "
+                "or pass it after `--`",
+            )
+        collected = getattr(namespace, self.dest, None) or []
+        setattr(namespace, self.dest, [*collected, values])
+
+
+verbose_option = Option(
+    "-v",
+    "--verbose",
+    action="count",
+    default=0,
+    help="Enable verbose output. "
+    "Use -v for standard verbose logging and -vv for more detailed output",
+)

{flet_cli-1.0.0.dev2 → flet_cli-1.0.2}/src/flet_cli/commands/pack.py

@@ -13,6 +13,7 @@ from pathlib import Path
 import flet_cli.__pyinstaller.config as hook_config
 from flet.utils import is_linux, is_macos, is_windows
 from flet_cli.commands.base import BaseCommand
+from flet_cli.commands.options import PassThroughArgsAction
 
 
 class Command(BaseCommand):
@@ -20,6 +21,8 @@ class Command(BaseCommand):
     Package a Flet application into a standalone desktop executable or app bundle
     using PyInstaller.
 
+    Arguments after `--` are passed down to PyInstaller.
+
     Detailed usage guide: https://flet.dev/docs/publish/using-pyinstaller
     """
 
@@ -152,9 +155,12 @@ class Command(BaseCommand):
         parser.add_argument(
             "--pyinstaller-build-args",
             dest="pyinstaller_build_args",
-            action="append",
+            action=PassThroughArgsAction,
+            example="--clean",
             nargs="*",
-            help="Additional raw arguments to the underlying pyinstaller build command",
+            help="Additional raw arguments to the underlying pyinstaller build "
+            "command. Attach an argument that starts with `-` using `=`, e.g. "
+            "`--pyinstaller-build-args=--clean`, or pass the arguments after `--`",
         )
         parser.add_argument(
             "-y",