Flower CLI reference¶
Basic Commands¶
flwr
CLI¶
flwr¶
flwr is the Flower command line interface.
flwr [OPTIONS] COMMAND [ARGS]...
Options
- --install-completion¶
Install completion for the current shell.
- --show-completion¶
Show completion for the current shell, to copy it or customize the installation.
build¶
Build a Flower App into a Flower App Bundle (FAB).
You can run flwr build
without any arguments to bundle the app located in the
current directory. Alternatively, you can you can specify a path using the --app
option to bundle an app located at the provided path. For example:
flwr build --app ./apps/flower-hello-world
.
flwr build [OPTIONS]
Options
- --app <app>¶
Path of the Flower App to bundle into a FAB
install¶
Install a Flower App Bundle.
It can be ran with a single FAB file argument:
flwr install ./target_project.fab
The target install directory can be specified with --flwr-dir
:
flwr install ./target_project.fab --flwr-dir ./docs/flwr
This will install target_project
to ./docs/flwr/
. By default,
flwr-dir
is equal to:
$FLWR_HOME/
if$FLWR_HOME
is defined
$XDG_DATA_HOME/.flwr/
if$XDG_DATA_HOME
is defined
$HOME/.flwr/
in all other cases
flwr install [OPTIONS] source
Options
- --flwr-dir <flwr_dir>¶
The desired install path.
Arguments
- source¶
Optional argument
The source FAB file to install.
log¶
Get logs from a Flower project run.
flwr log [OPTIONS] RUN_ID [APP] [FEDERATION]
Options
- --stream, --show¶
Flag to stream or print logs from the Flower run
- Default:
True
Arguments
- RUN_ID¶
Required argument
The Flower run ID to query
- APP¶
Optional argument
Path of the Flower project to run
- FEDERATION¶
Optional argument
Name of the federation to run the app on
login¶
Login to Flower SuperLink.
flwr login [OPTIONS] [APP] [FEDERATION]
Arguments
- APP¶
Optional argument
Path of the Flower App to run.
- FEDERATION¶
Optional argument
Name of the federation to login into.
ls¶
List runs.
flwr ls [OPTIONS] [APP] [FEDERATION]
Options
- --runs¶
List all runs
- Default:
False
- --run-id <run_id>¶
Specific run ID to display
- --format <output_format>¶
Format output using ‘default’ view or ‘json’
- Default:
'default'
Arguments
- APP¶
Optional argument
Path of the Flower project
- FEDERATION¶
Optional argument
Name of the federation
new¶
Create new Flower App.
flwr new [OPTIONS] [APP_NAME]
Options
- --framework <framework>¶
The ML framework to use
- Options:
PyTorch | TensorFlow | sklearn | HuggingFace | JAX | MLX | NumPy | FlowerTune | Flower Baseline
- --username <username>¶
The Flower username of the author
Arguments
- APP_NAME¶
Optional argument
The name of the Flower App
run¶
Run Flower App.
flwr run [OPTIONS] [APP] [FEDERATION]
Options
- -c, --run-config <config_overrides>¶
Override configuration key-value pairs, should be of the format:
–run-config ‘key1=”value1” key2=”value2”’ –run-config ‘key3=”value3”’
Note that key1, key2, and key3 in this example need to exist inside the pyproject.toml in order to be properly overriden.
- --stream¶
Use –stream with flwr run to display logs; logs are not streamed by default.
- Default:
False
- --format <output_format>¶
Format output using ‘default’ view or ‘json’
- Default:
'default'
Arguments
- APP¶
Optional argument
Path of the Flower App to run.
- FEDERATION¶
Optional argument
Name of the federation to run the app on.
stop¶
Stop a run.
flwr stop [OPTIONS] RUN_ID [APP] [FEDERATION]
Arguments
- RUN_ID¶
Required argument
The Flower run ID to stop
- APP¶
Optional argument
Path of the Flower project
- FEDERATION¶
Optional argument
Name of the federation
flower-superlink
¶
Start a Flower SuperLink
usage: flower-superlink [-h] [--insecure] [--flwr-dir FLWR_DIR]
[--ssl-certfile SSL_CERTFILE]
[--ssl-keyfile SSL_KEYFILE]
[--ssl-ca-certfile SSL_CA_CERTFILE]
[--isolation {subprocess,process}]
[--database DATABASE] [--storage-dir STORAGE_DIR]
[--auth-list-public-keys AUTH_LIST_PUBLIC_KEYS]
[--auth-superlink-private-key AUTH_SUPERLINK_PRIVATE_KEY]
[--auth-superlink-public-key AUTH_SUPERLINK_PUBLIC_KEY]
[--user-auth-config USER_AUTH_CONFIG]
[--serverappio-api-address SERVERAPPIO_API_ADDRESS]
[--fleet-api-type {grpc-rere,grpc-adapter,rest}]
[--fleet-api-address FLEET_API_ADDRESS]
[--fleet-api-num-workers FLEET_API_NUM_WORKERS]
[--exec-api-address EXEC_API_ADDRESS]
[--executor EXECUTOR] [--executor-dir EXECUTOR_DIR]
[--executor-config EXECUTOR_CONFIG]
[--simulationio-api-address SIMULATIONIO_API_ADDRESS]
Named Arguments¶
- --insecure
Run the server without HTTPS, regardless of whether certificate paths are provided. By default, the server runs with HTTPS enabled. Use this flag only if you understand the risks.
Default: False
- --flwr-dir
- The path containing installed Flower Apps.
The default directory is:
$FLWR_HOME/ if $FLWR_HOME is defined
$XDG_DATA_HOME/.flwr/ if $XDG_DATA_HOME is defined
$HOME/.flwr/ in all other cases
- --ssl-certfile
Fleet API server SSL certificate file (as a path str) to create a secure connection.
- --ssl-keyfile
Fleet API server SSL private key file (as a path str) to create a secure connection.
- --ssl-ca-certfile
Fleet API server SSL CA certificate file (as a path str) to create a secure connection.
- --isolation
Possible choices: subprocess, process
Isolation mode when running a ServerApp (subprocess by default, possible values: subprocess, process). Use subprocess to configure SuperLink to run a ServerApp in a subprocess. Use process to indicate that a separate independent process gets created outside of SuperLink.
Default: “subprocess”
- --database
A string representing the path to the database file that will be opened. Note that passing ‘:memory:’ will open a connection to a database that is in RAM, instead of on disk. If nothing is provided, Flower will just create a state in memory.
Default: “:flwr-in-memory-state:”
- --storage-dir
The base directory to store the objects for the Flower File System.
Default: /home/runner/.flwr/superlink/ffs
- --auth-list-public-keys
A CSV file (as a path str) containing a list of known public keys to enable authentication.
- --auth-superlink-private-key
The SuperLink’s private key (as a path str) to enable authentication.
- --auth-superlink-public-key
The SuperLink’s public key (as a path str) to enable authentication.
- --user-auth-config
The path to the user authentication configuration YAML file.
- --serverappio-api-address
ServerAppIo API (gRPC) server address (IPv4, IPv6, or a domain name). By default, it is set to 0.0.0.0:9091.
Default: “0.0.0.0:9091”
- --fleet-api-type
Possible choices: grpc-rere, grpc-adapter, rest
Start a gRPC-rere or REST (experimental) Fleet API server.
Default: “grpc-rere”
- --fleet-api-address
Fleet API server address (IPv4, IPv6, or a domain name).
- --fleet-api-num-workers
Set the number of concurrent workers for the Fleet API server.
Default: 1
- --exec-api-address
Exec API server address (IPv4, IPv6, or a domain name) By default, it is set to 0.0.0.0:9093.
Default: “0.0.0.0:9093”
- --executor
For example: deployment:exec or project.package.module:wrapper.exec. The default is flwr.superexec.deployment:executor
Default: “flwr.superexec.deployment:executor”
- --executor-dir
The directory for the executor.
Default: “.”
- --executor-config
Key-value pairs for the executor config, separated by spaces. For example:
–executor-config ‘verbose=true root-certificates=”certificates/superlink-ca.crt”’
- --simulationio-api-address
SimulationIo API (gRPC) server address (IPv4, IPv6, or a domain name).By default, it is set to 0.0.0.0:9096.
Default: “0.0.0.0:9096”
flower-supernode
¶
Start a Flower SuperNode
usage: flower-supernode [-h] [--insecure]
[--grpc-rere | --grpc-adapter | --rest]
[--root-certificates ROOT_CERT] [--server SERVER]
[--superlink SUPERLINK] [--max-retries MAX_RETRIES]
[--max-wait-time MAX_WAIT_TIME]
[--auth-supernode-private-key AUTH_SUPERNODE_PRIVATE_KEY]
[--auth-supernode-public-key AUTH_SUPERNODE_PUBLIC_KEY]
[--node-config NODE_CONFIG] [--flwr-dir FLWR_DIR]
[--isolation {subprocess,process}]
[--clientappio-api-address CLIENTAPPIO_API_ADDRESS]
[app]
Positional Arguments¶
- app
(REMOVED) This argument is removed. The SuperNode now automatically uses the ClientApp delivered from the SuperLink, so there is no need to provide the app directory manually. This argument will be removed in a future version.
Named Arguments¶
- --insecure
Run the client without HTTPS. By default, the client runs with HTTPS enabled. Use this flag only if you understand the risks.
Default: False
- --grpc-rere
Use grpc-rere as a transport layer for the client.
Default: “grpc-rere”
- --grpc-adapter
Use grpc-adapter as a transport layer for the client.
- --rest
Use REST as a transport layer for the client.
- --root-certificates
Specifies the path to the PEM-encoded root certificate file for establishing secure HTTPS connections.
- --server
Server address
Default: “0.0.0.0:9092”
- --superlink
SuperLink Fleet API (gRPC-rere) address (IPv4, IPv6, or a domain name)
Default: “0.0.0.0:9092”
- --max-retries
The maximum number of times the client will try to reconnect to theSuperLink before giving up in case of a connection error. By default,it is set to None, meaning there is no limit to the number of tries.
- --max-wait-time
The maximum duration before the client stops trying toconnect to the SuperLink in case of connection error. By default, itis set to None, meaning there is no limit to the total time.
- --auth-supernode-private-key
The SuperNode’s private key (as a path str) to enable authentication.
- --auth-supernode-public-key
The SuperNode’s public key (as a path str) to enable authentication.
- --node-config
A space separated list of key/value pairs (separated by =) to configure the SuperNode. E.g. –node-config ‘key1=”value1” partition-id=0 num-partitions=100’
- --flwr-dir
- The path containing installed Flower Apps.
The default directory is:
$FLWR_HOME/ if $FLWR_HOME is defined
$XDG_DATA_HOME/.flwr/ if $XDG_DATA_HOME is defined
$HOME/.flwr/ in all other cases
- --isolation
Possible choices: subprocess, process
Isolation mode when running a ClientApp (subprocess by default, possible values: subprocess, process). Use subprocess to configure SuperNode to run a ClientApp in a subprocess. Use process to indicate that a separate independent process gets created outside of SuperNode.
Default: “subprocess”
- --clientappio-api-address
ClientAppIo API (gRPC) server address (IPv4, IPv6, or a domain name). By default, it is set to 0.0.0.0:9094.
Default: “0.0.0.0:9094”
Advanced Commands¶
flwr-serverapp
¶
Run a Flower ServerApp
usage: flwr-serverapp [-h] [--serverappio-api-address SERVERAPPIO_API_ADDRESS]
[--run-once] [--flwr-dir FLWR_DIR] [--insecure]
Named Arguments¶
- --serverappio-api-address
Address of SuperLink’s ServerAppIo API (IPv4, IPv6, or a domain name).By default, it is set to 127.0.0.1:9091.
Default: “127.0.0.1:9091”
- --run-once
When set, this process will start a single ServerApp for a pending Run. If there is no pending Run, the process will exit.
Default: False
- --flwr-dir
- The path containing installed Flower Apps.
By default, this value is equal to:
$FLWR_HOME/ if $FLWR_HOME is defined
$XDG_DATA_HOME/.flwr/ if $XDG_DATA_HOME is defined
$HOME/.flwr/ in all other cases
- --insecure
Run the server without HTTPS, regardless of whether certificate paths are provided. By default, the server runs with HTTPS enabled. Use this flag only if you understand the risks.
Default: False
flwr-clientapp
¶
Run a Flower ClientApp
usage: flwr-clientapp [-h] [--clientappio-api-address CLIENTAPPIO_API_ADDRESS]
[--token TOKEN] [--flwr-dir FLWR_DIR] [--insecure]
Named Arguments¶
- --clientappio-api-address
Address of SuperNode’s ClientAppIo API (IPv4, IPv6, or a domain name).By default, it is set to 127.0.0.1:9094.
Default: “127.0.0.1:9094”
- --token
Unique token generated by SuperNode for each ClientApp execution
- --flwr-dir
- The path containing installed Flower Apps.
By default, this value is equal to:
$FLWR_HOME/ if $FLWR_HOME is defined
$XDG_DATA_HOME/.flwr/ if $XDG_DATA_HOME is defined
$HOME/.flwr/ in all other cases
- --insecure
Run the server without HTTPS, regardless of whether certificate paths are provided. By default, the server runs with HTTPS enabled. Use this flag only if you understand the risks.
Default: False
Technical Commands¶
flower-simulation
¶
Start a Flower simulation
usage: flower-simulation [-h] --app APP --num-supernodes NUM_SUPERNODES
[--run-config RUN_CONFIG] [--backend BACKEND]
[--backend-config BACKEND_CONFIG]
[--enable-tf-gpu-growth] [--delay-start DELAY_START]
[--verbose] [--flwr-dir FLWR_DIR] [--run-id RUN_ID]
Named Arguments¶
- --app
Path to a directory containing a FAB-like structure with a pyproject.toml.
- --num-supernodes
Number of simulated SuperNodes.
- --run-config
Override configuration key-value pairs.
- --backend
Simulation backend that executes the ClientApp.
Default: “ray”
- --backend-config
A JSON formatted stream, e.g ‘{“<keyA>”:<value>, “<keyB>”:<value>}’ to configure a backend. Values supported in <value> are those included by flwr.common.typing.ConfigsRecordValues.
Default: “{}”
- --enable-tf-gpu-growth
Enables GPU growth on the main thread. This is desirable if you make use of a TensorFlow model on your ServerApp while having your ClientApp running on the same GPU. Without enabling this, you might encounter an out-of-memory error because TensorFlow by default allocates all GPU memory.Read more about how tf.config.experimental.set_memory_growth() works in the TensorFlow documentation: https://www.tensorflow.org/api/stable.
Default: False
- --delay-start
Buffer time (in seconds) to delay the start the simulation engine after the ServerApp, which runs in a separate thread, has been launched.
Default: 3
- --verbose
When unset, only INFO, WARNING and ERROR log messages will be shown. If set, DEBUG-level logs will be displayed.
Default: False
- --flwr-dir
- The path containing installed Flower Apps.
By default, this value is equal to:
$FLWR_HOME/ if $FLWR_HOME is defined
$XDG_DATA_HOME/.flwr/ if $XDG_DATA_HOME is defined
$HOME/.flwr/ in all other cases
- --run-id
Sets the ID of the run started by the Simulation Engine.
Deprecated Commands¶
flower-server-app
¶
Warning
Note that from version 1.13.0
, flower-server-app
is deprecated. Instead, you
only need to execute flwr run
to start the run.
flower-superexec
¶
Warning
Note that from version 1.13.0
, flower-superexec
is deprecated. Instead, you
only need to execute flower-superlink
.