Use CLI JSON output =================== The `Flower CLIs `_ come with a built-in JSON output mode. This mode is useful when you want to consume the output of a Flower CLI programmatically. For example, you might want to use the output of the ``flwr`` CLI in a script or a continuous integration pipeline. .. note:: The JSON output mode is currently only available when using the Flower CLIs with a `SuperLink `_. Learn more about the `SuperLink` in the `Flower Architecture Overview `_ page. In this guide, we'll show you how to specify a JSON output with the ``flwr run``, ``flwr ls``, and ``flwr stop`` commands. We will also provide examples of the JSON output for each of these commands. .. |flwr_run| replace:: ``flwr run`` .. |flwr_ls| replace:: ``flwr ls`` .. |flwr_stop| replace:: ``flwr stop`` .. _flwr_ls: ref-api-cli.html#flwr-ls .. _flwr_run: ref-api-cli.html#flwr-run .. _flwr_stop: ref-api-cli.html#flwr-stop ``flwr run`` JSON output ------------------------ The |flwr_run|_ command runs a Flower app from a provided directory. Note that if the app path argument is not passed to ``flwr run``, the current working directory is used as the default Flower app directory. By default, executing the ``flwr run`` command prints the status of the app build and run process as follows: .. code-block:: bash $ flwr run Loading project configuration... Success ๐ŸŽŠ Successfully built flwrlabs.myawesomeapp.1-0-0.014c8eb3.fab ๐ŸŽŠ Successfully started run 1859953118041441032 To get the output in JSON format, pass an additional ``--format json`` flag: .. code-block:: bash $ flwr run --format json { "success": true, "run-id": 1859953118041441032, "fab-id": "flwrlabs/myawesomeapp", "fab-name": "myawesomeapp", "fab-version": "1.0.0", "fab-hash": "014c8eb3", "fab-filename": "flwrlabs.myawesomeapp.1-0-0.014c8eb3.fab" } The JSON output for ``flwr run`` contains the following fields: - ``success``: A boolean indicating whether the command was successful. - ``run-id``: The ID of the run. - ``fab-id``: The ID of the Flower app. - ``fab-name``: The name of the Flower app. - ``fab-version``: The version of the Flower app. - ``fab-hash``: The short hash of the Flower app. - ``fab-filename``: The filename of the Flower app. If the command fails, the JSON output will contain two fields, ``success`` with the value of ``false`` and ``error-message``. For example, if the command fails to find the name of the federation on the SuperLink, the output will look like this: .. _json_error_output: .. code-block:: bash $ flwr run --format json { "success": false, "error-message": "Loading project configuration... \nSuccess\n There is no `[missing]` federation declared in the `pyproject.toml`.\n The following federations were found:\n\nfed-existing-1\nfed-existing-2\n\n" } ``flwr ls`` JSON output ----------------------- The |flwr_ls|_ command lists all the runs in the current project. Similar to ``flwr run``, if the app path argument is not passed to ``flwr ls``, the current working directory is used as the Flower app directory. By default, the command list the details of all runs in a Flower federation in a tabular format: .. code-block:: bash $ flwr ls Loading project configuration... Success ๐Ÿ“„ Listing all runs... โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”“ โ”ƒ Run ID โ”ƒ FAB โ”ƒ Status โ”ƒ Elapsed โ”ƒ Created At โ”ƒ Running At โ”ƒ Finished At โ”ƒ โ”กโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ฉ โ”‚ 185995311804 โ”‚ flwrlabs/myโ€ฆ โ”‚ finished:coโ€ฆ โ”‚ 00:00:55 โ”‚ 2024-12-16 โ”‚ 2024-12-16 โ”‚ 2024-12-16 โ”‚ โ”‚ 1441032 โ”‚ (v1.0.0) โ”‚ โ”‚ โ”‚ 11:12:33Z โ”‚ 11:12:33Z โ”‚ 11:13:29Z โ”‚ โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”‚ 142007406570 โ”‚ flwrlabs/myโ€ฆ โ”‚ running โ”‚ 00:00:05 โ”‚ 2024-12-16 โ”‚ 2024-12-16 โ”‚ N/A โ”‚ โ”‚ 11601420 โ”‚ (v1.0.0) โ”‚ โ”‚ โ”‚ 12:18:39Z โ”‚ 12:18:39Z โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ To get the output in JSON format, simply pass the ``--format json`` flag: .. code-block:: bash $ flwr ls --format json { "success": true, "runs": [ { "run-id": 1859953118041441032, "fab-id": "flwrlabs/myawesomeapp1", "fab-name": "myawesomeapp1", "fab-version": "1.0.0", "fab-hash": "014c8eb3", "status": "finished:completed", "elapsed": "00:00:55", "created-at": "2024-12-16 11:12:33Z", "running-at": "2024-12-16 11:12:33Z", "finished-at": "2024-12-16 11:13:29Z" }, { "run-id": 14200740657011601420, "fab-id": "flwrlabs/myawesomeapp2", "fab-name": "myawesomeapp2", "fab-version": "1.0.0", "fab-hash": "014c8eb3", "status": "running", "elapsed": "00:00:09", "created-at": "2024-12-16 12:18:39Z", "running-at": "2024-12-16 12:18:39Z", "finished-at": "N/A" }, ] } The JSON output for ``flwr ls`` contains similar fields as ``flwr run`` with the addition of the ``status``, ``elapsed``, ``created-at``, ``running-at``, and ``finished-at`` fields. The ``runs`` key contains a list of dictionaries, each representing a run. The additional fields are: - ``status``: The status of the run, either pending, starting, running, or finished. - ``elapsed``: The time elapsed since the run started, formatted as ``HH:MM:SS``. - ``created-at``: The time the run was created. - ``running-at``: The time the run started running. - ``finished-at``: The time the run finished. All timestamps adhere to ISO 8601, UTC and are formatted as ``YYYY-MM-DD HH:MM:SSZ``. You can also use the ``--run-id`` flag to list the details for one run. In this case, the JSON output will have the same structure as above with only one entry in the ``runs`` key. For more details of this command, see the |flwr_ls|_ documentation. If the command fails, the JSON output will return two fields, ``success`` and ``error-message``, as shown in :ref:`the above example `. Note that the content of the error message will be different depending on the error that occurred. ``flwr stop`` JSON output ------------------------- The |flwr_stop|_ command stops a running Flower app for a provided run ID. Similar to ``flwr run``, if the app path argument is not passed to ``flwr stop``, the current working directory is used as the Flower app directory. By default, the command prints the status of the stop process as follows: .. code-block:: bash $ flwr stop 1859953118041441032 Loading project configuration... Success โœ‹ Stopping run ID 1859953118041441032... โœ… Run 1859953118041441032 successfully stopped. To get the output in JSON format, simply pass the ``--format json`` flag: .. code-block:: bash $ flwr stop 1859953118041441032 --format json { "success": true, "run-id": 1859953118041441032, } If the command fails, the JSON output will contain two fields ``success`` with the value of ``false`` and ``error-message``, as shown in :ref:`the above example `. Note that the content of the error message will be different depending on the error that occurred.