flet debug: script path treated as unrecognized argument when placed after platform-specific flags

Description

flet debug <platform> ... <script.py> fails with unrecognized arguments: <script.py> when the script path is placed after flags like --device-id or --route, instead of immediately after the platform argument.

Repro

uv run flet debug ios --device-id D3463E8E-AC7A-45B1-82A6-B0E989B29132 examples/extensions/code_editor/selection_handling/main.py -v

usage: flet [-h] [--version] [--json] {create,run,build,clean,debug,test,pack,publish,serve,emulators,devices,doctor,mcp} ...
flet: error: unrecognized arguments: examples/extensions/code_editor/selection_handling/main.py

Root cause

sdk/python/packages/flet-cli/src/flet_cli/commands/debug.py registers platform as a positional argument with nargs="?" in Command.add_arguments(), then calls super().add_arguments(parser) (BaseBuildCommand), which registers a second positional, python_app_path, also with nargs="?".

argparse consumes positional arguments in contiguous runs (a maximal sequence of non-option tokens). When --device-id VALUE sits between the platform and the script path, the two tokens land in separate runs:

• Run 1: ["ios"]
• Run 2 (after --device-id VALUE): ["examples/.../main.py"]

Because both positionals are nargs="?", argparse greedily fills both positional slots from the first run alone (platform="ios", python_app_path matched with 0 args/default), leaving no positional actions available to consume the second run. The script path is then reported as an unrecognized extra argument.

This is a minimal, verified repro of the underlying argparse behavior:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("platform", nargs="?", choices=["ios", "android"])
parser.add_argument("--device-id")
parser.add_argument("python_app_path", nargs="?")
parser.parse_args(["ios", "--device-id", "X", "script.py"])
# error: unrecognized arguments: script.py

Workaround

Place the script path immediately after the platform, before any flags:

uv run flet debug ios examples/extensions/code_editor/selection_handling/main.py --device-id D3463E8E-AC7A-45B1-82A6-B0E989B29132 -v

Suggested fix

Avoid two consecutive optional (nargs="?") positional arguments split across other flags. Options include:

• Making python_app_path a required positional placed before platform, or
• Using an explicit --script/--app flag instead of a bare positional, or
• Reordering so platform and python_app_path are always adjacent in the parser's positional list and documented as such.

Environment

• OS: macOS (Darwin)
• Command: flet debug ios --device-id <id> <script.py> -v