Pass custom arguments to the app script from flet run

[FeodorFitsner]

Summary

flet run had no way to pass arguments to the app script - the child process was always launched as python -u <script>, so a flag meant for the app was consumed by the CLI's own parser:

$ flet run main.py --manual
flet: error: unrecognized arguments: --manual

Everything after a bare -- separator is now forwarded to the script and arrives there as sys.argv[1:]:

flet run --web main.py -- --dataset big.csv --verbose

options = parser.parse_args(sys.argv[1:])   # --dataset big.csv --verbose

Behavior

• The separator is stripped in main() before the parser (and set_default_subparser) sees the command line, so app arguments can never be read as Flet's own options, and flet main.py -- build no longer suppresses the default run subcommand.
• Flet's options keep working anywhere before the separator: flet run -w main.py -- --web runs Flet's web mode and passes --web to the app.
• Arguments that don't look like options need no separator: flet run main.py big.csv.
• Mistyped Flet options are still errors - now with a hint:

  flet: error: unrecognized arguments: --manual
  If these are arguments for your app script, put them after a `--` separator, e.g. `flet run main.py -- --manual`
  

• Using -- with any other command errors explicitly instead of silently dropping the arguments.
• Forwarded arguments are re-applied on every hot reload, and work in all run modes (desktop, --web, --ios, --android) and with -m module invocations.

Incidental fix

get_parser() no longer mutates sys.argv. set_default_subparser now takes and returns an argv list instead of inserting into the global - the crocodocs CLI doc generator imports get_parser() and was having its own sys.argv rewritten as a side effect.

Tests

New packages/flet-cli/tests/test_run_script_args.py covers separator handling, option/argument precedence, the implicit run subcommand, subcommand-named script arguments, and both error paths. Verified end-to-end that the child process is launched as python3 -u app.py --manual -x 1.

Docs: new Passing arguments to your app section; the flet run CLI reference page is generated from the parser and picks up the new positional automatically.

Summary by Sourcery

Allow passing custom command-line arguments to app scripts invoked via flet run, while tightening CLI parsing behavior around default subcommands and separators.

New Features:

• Support forwarding arguments after a -- separator from flet run to the app script, exposed as sys.argv[1:] and honored across all run modes and module invocations.

Enhancements:

• Refactor CLI parsing to avoid mutating sys.argv, make run the default subcommand via an argv-based helper, and provide clearer errors and hints when options are unrecognized or separators are misused.

Documentation:

• Add "Passing arguments to your app" documentation describing the -- separator, script argument handling, and behavior across run modes.
• Update the changelog to document the new flet run argument forwarding capability and its behavior.

Tests:

• Add tests for flet run script argument handling, including separator semantics, interaction with Flet options, implicit run subcommand behavior, subcommand-like script arguments, and error cases for invalid options and separator use.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}