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.

app¶

Manage Apps

flwr app [OPTIONS] COMMAND [ARGS]...
publish¶

Publish a Flower App to the Flower Platform.

This command uploads your app project to the Flower Platform. Files are filtered based on .gitignore patterns and allowed file extensions.

flwr app publish [OPTIONS] [APP]

Arguments

APP¶

Optional argument

Project directory to upload (defaults to current directory).

review¶

Download a FAB for <APP-ID>, unpack it for manual review, and upon confirmation sign & submit the review to the Platform.

flwr app review [OPTIONS] APP_SPEC

Arguments

APP_SPEC¶

Required argument

App specifier (e.g., “@account/app” or “@account/app==1.0.0”). Version is optional; defaults to the latest.

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

config¶

Manage Configuration

flwr config [OPTIONS] COMMAND [ARGS]...
list¶

List all SuperLink connections (alias: ls).

flwr config list [OPTIONS]

Options

--format <output_format>¶

Format output using “default” view or “json”

Default:

'default'

federation¶

Manage Federations

flwr federation [OPTIONS] COMMAND [ARGS]...
list¶

List available federations or details of a specific federation (alias: ls).

flwr federation list [OPTIONS] [SUPERLINK]

Options

--format <output_format>¶

Format output using “default” view or “json”

Default:

'default'

--federation <federation>¶

Name of the federation to display

Arguments

Optional argument

Name of the SuperLink connection.

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.

list¶

List the details of one provided run ID or all runs (alias: ls).

The following details are displayed:

  • Run ID: Unique identifier for the run.

  • Federation: The federation to which the run belongs.

  • App: The App associated with the run (<APP_ID>==<APP_VERSION>).

  • Status: Current status of the run (pending, starting, running, finished).

  • Elapsed: Time elapsed since the run started (HH:MM:SS).

  • Status Changed @: Timestamp of the most recent status change.

All timestamps follow ISO 8601, UTC and are formatted as YYYY-MM-DD HH:MM:SSZ.

flwr list [OPTIONS] [SUPERLINK]

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

Optional argument

Name of the SuperLink connection.

log¶

Get logs from a run.

Retrieve and display logs from a Flower run. Logs can be streamed in real-time (with –stream) or printed once (with –show).

flwr log [OPTIONS] RUN_ID [SUPERLINK]

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

Optional argument

Name of the SuperLink connection.

login¶

Login to Flower SuperLink.

flwr login [OPTIONS] [SUPERLINK]

Arguments

Optional argument

Name of the SuperLink connection.

new¶

Create new Flower App.

flwr new [OPTIONS] [APP_SPEC]

Options

--framework <framework>¶

Deprecated. The ML framework to use

--username <username>¶

Deprecated. The Flower username of the author

Arguments

APP_SPEC¶

Optional argument

Flower app specifier. Use the format “@account_name/app_name” or “@account_name/app_name==x.y.z”. Version is optional (defaults to latest).

pull¶

Pull artifacts from a Flower run.

Retrieve a download URL for artifacts generated during a completed Flower run. The artifacts can then be downloaded from the provided URL.

flwr pull [OPTIONS] RUN_ID [SUPERLINK]

Arguments

RUN_ID¶

Required argument

Run ID to pull artifacts from.

Optional argument

Name of the SuperLink connection.

run¶

Run Flower App.

flwr run [OPTIONS] [APP] [SUPERLINK]

Options

--federation <federation>¶

The federation to submit the run to; must be in the format @<account>/<federation>.

-c, --run-config <run_config_overrides>¶

Override run configuration values using one of the following formats:

–run-config “<k1>=<v1> <k2>=<v2>” | –run-config “<k1>=<v1>” –run-config “<k2>=<v2>” | –run-config <path/to/your/toml>

When providing key-value pairs, values can be of any type supported by TOML (e.g., bool, int, float, string). The specified keys (<k1> and <k2> in the example) must exist in the run configuration under the [tool.flwr.app.config] section of pyproject.toml to be overridden. Alternatively, provide a TOML file containing overrides.

--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.

Optional argument

Name of the SuperLink connection.

stop¶

Stop a Flower run.

This command stops a running Flower App execution by sending a stop request to the SuperLink via the Control API.

flwr stop [OPTIONS] RUN_ID [SUPERLINK]

Options

--format <output_format>¶

Format output using “default” view or “json”

Default:

'default'

Arguments

RUN_ID¶

Required argument

The Flower run ID to stop

Optional argument

Name of the SuperLink connection.

supernode¶

Manage SuperNodes

flwr supernode [OPTIONS] COMMAND [ARGS]...
list¶

List SuperNodes in the federation (alias: ls).

flwr supernode list [OPTIONS] [SUPERLINK]

Options

--format <output_format>¶

Format output using “default” view or “json”

Default:

'default'

-v, --verbose¶

Enable verbose output

Default:

False

Arguments

Optional argument

Name of the SuperLink connection.

register¶

Add a SuperNode to the federation.

flwr supernode register [OPTIONS] PUBLIC_KEY [SUPERLINK]

Options

--format <output_format>¶

Format output using “default” view or “json”

Default:

'default'

Arguments

PUBLIC_KEY¶

Required argument

Path to a P-384 (or any other NIST EC curve) public key file.

Optional argument

Name of the SuperLink connection.

unregister¶

Unregister a SuperNode from the federation.

flwr supernode unregister [OPTIONS] NODE_ID [SUPERLINK]

Options

--format <output_format>¶

Format output using “default” view or “json”

Default:

'default'

Arguments

NODE_ID¶

Required argument

ID of the SuperNode to remove.

Optional argument

Name of the SuperLink connection.

flower-supernode¶

Start a Flower SuperNode

usage: flower-supernode [-h] [--insecure]
                        [--grpc-rere | --grpc-adapter | --rest]
                        [--root-certificates ROOT_CERT]
                        [--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]
                        [--trusted-entities YAML_FILE]
                        [--health-server-address HEALTH_SERVER_ADDRESS]

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.

--superlink

SuperLink Fleet API address (IPv4, IPv6, or a domain name). If using the REST (experimental) transport, ensure your address is in the form http://… or https://… when TLS is enabled.

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

Path to the SuperNode’s private key to enable authentication.

--auth-supernode-public-key

This argument is deprecated and will be removed in a future release.

--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 »

--trusted-entities

Path to a YAML file defining trusted entities. The file must map public key IDs to public keys. Example: { fpk_UUID1: “ssh-ed25519 <key1> [comment1]”, fpk_UUID2: “ssh-ed25519 <key2> [comment2]” }

--health-server-address

Health service gRPC server address (IPv4, IPv6, or a domain name) with no TLS. If not set, the health server will not be started.

Advanced Commands¶

flower-superexec¶

Run Flower SuperExec.

usage: flower-superexec [-h] --appio-api-address APPIO_API_ADDRESS
                        --plugin-type {clientapp,serverapp,simulation}
                        [--insecure] [--flwr-dir FLWR_DIR]
                        [--parent-pid PARENT_PID]
                        [--health-server-address HEALTH_SERVER_ADDRESS]

Named Arguments¶

--appio-api-address

Address of the AppIO API

--plugin-type

Possible choices: clientapp, serverapp, simulation

The type of plugin to use.

--insecure

Connect to the AppIO API without TLS. Data transmitted between the client and server is not encrypted. Use this flag only if you understand the risks.

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

--parent-pid

The PID of the parent process. When set, the process will terminate when the parent process exits.

--health-server-address

Health service gRPC server address (IPv4, IPv6, or a domain name) with no TLS. If not set, the health server will not be started.