diff --git a/docs/manuals/cli/index.md b/docs/manuals/cli/index.md index 63cf4b359..5f5ad0260 100644 --- a/docs/manuals/cli/index.md +++ b/docs/manuals/cli/index.md @@ -10,6 +10,9 @@ commands to streamline your web application development. Here is a list of avail - [:material-arrow-right: taipy create](create.md): With this command, you can easily initiate a new Taipy application by utilizing a template as a starting point for your project. +- [:material-arrow-right: taipy run](run.md): This command allows you to run your Taipy application with arguments + both supported and unsupported by Taipy. + - [:material-arrow-right: taipy manage-versions](manage-versions.md): This command empowers you to efficiently manage the versions of your user application and their related data. diff --git a/docs/manuals/cli/run.md b/docs/manuals/cli/run.md new file mode 100644 index 000000000..21a0356d0 --- /dev/null +++ b/docs/manuals/cli/run.md @@ -0,0 +1,110 @@ +# Run application in Taipy CLI + +Assume that you have a "main.py" file containing your Taipy application. +To start the Taipy application, you can run + +```console +$ python main.py +``` + +However, when working with command-line arguments, Taipy supported arguments can be confused with +arguments of other libraries or your application's arguments. To avoid this confusion, Taipy CLI +provides a run command to run your Taipy application, supporting both Taipy supported and unsupported arguments. + +## With Taipy supported arguments + +Taipy CLI will parse Taipy supported arguments and pass the rest of the arguments to your Taipy application. +To display the list of Taipy supported arguments, you can run `taipy help run` command. +Alternatively, you can use the `--help` or `-h` options by running `taipy run --help` or `taipy run -h`. + +```console +$ taipy help run +usage: taipy run [-h] [--port [PORT]] [--host [HOST]] [--ngrok-token [NGROK_TOKEN]] + [--webapp-path [WEBAPP_PATH]] [--debug | --no-debug] + [--use-reloader | --no-reloader] [--development | --experiment [VERSION] | + --production [VERSION]] [--force | --no-force] + application_main_file {external-args} ... + +positional arguments: + application_main_file + +options: + -h, --help show this help message and exit + --port [PORT], -P [PORT] + Specify server port + --host [HOST], -H [HOST] + Specify server host + --ngrok-token [NGROK_TOKEN] + Specify NGROK Authtoken + --webapp-path [WEBAPP_PATH] + The path to the web app to be used. The default is the webapp directory + under gui in the Taipy GUI package directory. + --debug Turn on debug + --no-debug Turn off debug + --use-reloader Auto reload on code changes + --no-reloader No reload on code changes + --development When execute Taipy application in `development` mode, all entities from + the previous development version will be deleted before running new Taipy + application. + --experiment [VERSION] + When execute Taipy application in `experiment` mode, the current Taipy + application is saved to a new version. If version name already exists, + check for compatibility with current Python Config and run the + application. Without being specified, the version number will be a random + string. + --production [VERSION] + When execute in `production` mode, the current version is used in + production. All production versions should have the same configuration and + share all entities. Without being specified, the latest version is used. + --force Force override the configuration of the version if existed and run the + application. Default to False. + --no-force Stop the application if any Config conflict exists. + +subcommands: + {external-args} + external-args Arguments defined after this keyword will be considered as external + arguments to be passed to the application +``` + +To start your application in the Taipy CLI, you can run + +```console +$ taipy run main.py +``` + +You can also provide Taipy supported arguments to the run command. + +```console +$ taipy run main.py --port 8080 --experiment "0.1" --debug +``` + +In this example, your Taipy application will be started in experiment mode with version name "0.1" +with debug on, and on the port "8080" of the server. + +!!! info + + By providing the arguments to the taipy run command, you are specifying that these arguments are + Taipy's arguments. Your application and other libraries would not be able to use these arguments. + +## With Taipy unsupported arguments + +Assume that the "main.py" file containing some custom arguments for your application: + +- `--host`: specify the host of the data server to read from. +- `--port`: specify the port of the data server to read from. +- `--debug`: turn on debug mode on your data processing pipeline. + +In a normal Python CLI, your application arguments will conflict with Taipy supported arguments. +Passing the host of your data server would also change the host of your Taipy application, which +is not a good problem to have. + +To solve this problem, Taipy CLI provides the "external-args" subcommand to pass Taipy unsupported +arguments to your application. + +```console +$ taipy run main.py --port 8080 external-args --host data.server.com --port 2714 --debug +``` + +In this example, your Taipy application will be started on *localhost:8080* with debug off since we +do not specify debug mode for Taipy. Meanwhile, your data processing pipeline will be reading data +from *data.server.com:2714*, and the pipeline will be run with debug on. diff --git a/mkdocs.yml_template b/mkdocs.yml_template index 60ea46932..870115811 100644 --- a/mkdocs.yml_template +++ b/mkdocs.yml_template @@ -88,6 +88,7 @@ nav: - manuals/cli/index.md - "help": manuals/cli/help.md - "create": manuals/cli/create.md + - "run": manuals/cli/run.md - "manage-versions": manuals/cli/manage-versions.md - "version": manuals/cli/version.md - "Running & Deploying":