Recipe Command

nvflare recipe lists built-in Job Recipe API recipes and shows structured metadata that agents and scripts can use to choose a recipe.

Command Usage

nvflare recipe -h

usage: nvflare recipe [-h]  ...

recipe subcommands:
  list      list available recipes (default)
  show      show structured metadata for a recipe

List Recipes

Use nvflare recipe list to display the available built-in recipes:

nvflare recipe list

In text mode, the command prints Loading installed recipe catalog... before importing and inspecting installed recipe metadata. This is a local Python environment operation; it does not connect to a FLARE server.

Filter by framework:

nvflare recipe list --framework pytorch

--framework is a shorthand for --filter framework=<framework>.

Supported framework filter values:

core
numpy
pytorch
tensorflow
sklearn
xgboost

Filter by recipe metadata:

nvflare recipe list --filter framework=pytorch --filter algorithm=fedavg
nvflare recipe list --filter privacy=homomorphic_encryption

Supported --filter keys:

framework
privacy
algorithm
aggregation
state_exchange

--filter is repeatable. Filters for different keys are combined together; repeating the same key matches any of the provided values. Hyphens and underscores are normalized in filter values, so homomorphic-encryption and homomorphic_encryption are equivalent.

Metadata Filter Values

Filter values are recipe metadata values. A value is valid only when at least one recipe in the installed catalog declares that value. In practice, most metadata values apply to specific frameworks, so combine metadata filters with framework when you want a precise result.

Algorithm values:

Value	Frameworks	Example
`cyclic`	`core`, `pytorch`, `tensorflow`	`nvflare recipe list --filter algorithm=cyclic`
`fedavg`	`core`, `numpy`, `pytorch`, `sklearn`, `tensorflow`	`nvflare recipe list --filter algorithm=fedavg`
`fedavg_logistic_regression`	`numpy`	`nvflare recipe list --filter algorithm=fedavg_logistic_regression`
`fedeval`	`pytorch`	`nvflare recipe list --filter algorithm=fedeval`
`fedopt`	`pytorch`, `tensorflow`	`nvflare recipe list --filter algorithm=fedopt`
`fedprox`	`pytorch`, `tensorflow`	`nvflare recipe list --filter algorithm=fedprox`
`fedstats`	`core`	`nvflare recipe list --filter algorithm=fedstats`
`kmeans`	`sklearn`	`nvflare recipe list --filter algorithm=kmeans`
`scaffold`	`pytorch`, `tensorflow`	`nvflare recipe list --filter algorithm=scaffold`
`svm`	`sklearn`	`nvflare recipe list --filter algorithm=svm`
`swarm`	`pytorch`	`nvflare recipe list --filter algorithm=swarm`
`xgboost_bagging`	`xgboost`	`nvflare recipe list --filter algorithm=xgboost_bagging`
`xgboost_horizontal`	`xgboost`	`nvflare recipe list --filter algorithm=xgboost_horizontal`
`xgboost_vertical`	`xgboost`	`nvflare recipe list --filter algorithm=xgboost_vertical`

Aggregation values:

Value	Frameworks	Example
`cluster_centers`	`sklearn`	`nvflare recipe list --filter framework=sklearn --filter aggregation=cluster_centers`
`server_optimizer`	`pytorch`, `tensorflow`	`nvflare recipe list --filter aggregation=server_optimizer`
`support_vectors`	`sklearn`	`nvflare recipe list --filter framework=sklearn --filter aggregation=support_vectors`
`tree_ensemble`	`xgboost`	`nvflare recipe list --filter framework=xgboost --filter aggregation=tree_ensemble`
`weighted_average`	`core`, `numpy`, `pytorch`, `sklearn`, `tensorflow`	`nvflare recipe list --filter aggregation=weighted_average`

State exchange values:

Value	Frameworks	Example
`cluster_centers`	`sklearn`	`nvflare recipe list --filter state_exchange=cluster_centers`
`full_model`	`core`, `numpy`, `pytorch`, `sklearn`, `tensorflow`	`nvflare recipe list --filter state_exchange=full_model`
`model_weights`	`numpy`	`nvflare recipe list --filter state_exchange=model_weights`
`support_vectors`	`sklearn`	`nvflare recipe list --filter state_exchange=support_vectors`
`trees`	`xgboost`	`nvflare recipe list --filter state_exchange=trees`
`weight_diff`	`pytorch`, `tensorflow`	`nvflare recipe list --filter state_exchange=weight_diff`

Privacy values:

Value	Frameworks	Example
`homomorphic_encryption`	`pytorch`	`nvflare recipe list --filter privacy=homomorphic_encryption`

The privacy filter matches privacy features declared by a recipe entry. If a recipe does not declare a privacy value, that does not mean the underlying algorithm is incompatible with privacy-enhancing technologies. For example, FedAvg can be combined with multiple PETs through additional configuration or components, but the generic FedAvg recipe does not enable one by default.

More examples:

nvflare recipe list --filter framework=pytorch --filter algorithm=fedopt
nvflare recipe list --filter framework=tensorflow --filter aggregation=server_optimizer
nvflare recipe list --filter framework=xgboost --filter state_exchange=trees
nvflare recipe list --filter framework=sklearn --filter aggregation=cluster_centers
nvflare recipe list --filter privacy=homomorphic_encryption

Other options:

Omitting --framework returns all available recipes.
--schema: print the command schema as JSON and exit.

Behavior notes:

The command lists all documented built-in recipe variants, including recipe variants whose optional framework dependencies are not installed locally.
optional_dependencies reports the packages needed to run a recipe whose framework is not currently installed.
Valid metadata filters that match no available recipes return an empty list.
The command combines a documented recipe manifest with dynamic recipe module discovery. When a recipe module cannot be imported because an optional dependency is missing, the CLI still returns the documented metadata and derives constructor parameters statically from source where possible.

The CLI prints a human-readable table in text mode and also emits the machine- readable result envelope.

Example JSON response:

{
  "schema_version": "1",
  "status": "ok",
  "exit_code": 0,
  "data": [
    {
      "name": "fedavg-pt",
      "description": "FedAvg for PyTorch nn.Module models",
      "framework": "pytorch",
      "module": "nvflare.app_opt.pt.recipes.fedavg",
      "class": "FedAvgRecipe",
      "algorithm": "fedavg",
      "aggregation": "weighted_average",
      "state_exchange": "full_model",
      "privacy": []
    }
  ]
}

Show Recipe

Use nvflare recipe show with a name returned by nvflare recipe list to get one recipe’s queryable metadata:

nvflare recipe show fedavg-pt --format json

In text mode, the command prints Loading installed recipe metadata for '<name>'... while it imports and inspects the selected recipe metadata. The human output summarizes the main fields and points to the exact JSON command for full constructor parameter details.

The JSON response includes list-time metadata plus framework support, privacy compatibility, client requirements, constructor parameters, optional dependencies, and template references. Parameter metadata is derived from the recipe constructor signature or static source parsing; the command does not instantiate the recipe.

For recipes with a configurable parameter transfer type, text output reports the default state exchange and the transfer setting. For example, FedAvg reports state_exchange: full_model (default; params_transfer_type=FULL, supports FULL or DIFF) because the default transfer is the full model, but the recipe can be configured to send diffs.

Example JSON response:

{
  "schema_version": "1",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "name": "fedavg-pt",
    "description": "FedAvg for PyTorch nn.Module models",
    "framework": "pytorch",
    "module": "nvflare.app_opt.pt.recipes.fedavg",
    "class": "FedAvgRecipe",
    "algorithm": "fedavg",
    "aggregation": "weighted_average",
    "state_exchange": "full_model",
    "privacy": [],
    "client_requirements": {
      "state_exchange": "full_model",
      "requires_training_script": true,
      "requires_per_site_config": true,
      "requires_site_list": false,
      "min_clients": {"required": true, "default": null}
    },
    "framework_support": ["pytorch"],
    "heterogeneity_support": ["horizontal"],
    "privacy_compatible": [],
    "parameters": [
      {
        "name": "min_clients",
        "type": "int",
        "required": true,
        "default": null,
        "kind": "keyword_only"
      }
    ],
    "optional_dependencies": ["pip install nvflare[PT]", "pip install torch"],
    "template_references": []
  }
}

Typical Workflow

nvflare recipe list is a discovery tool. A common workflow is:

nvflare recipe list --filter framework=pytorch --filter algorithm=fedavg
nvflare recipe show fedavg-pt --format json
python job.py --export --export-dir /tmp/nvflare/hello-pt
nvflare job submit -j /tmp/nvflare/hello-pt

nvflare recipe list replaces the deprecated nvflare job list_templates discovery flow for new examples and recipes.

JSON Output and Help

Use --schema for machine-readable command discovery:

nvflare recipe list --schema
nvflare recipe show --schema

The top-level CLI also supports JSON output mode:

nvflare recipe list --format json
nvflare recipe list --framework sklearn --format json
nvflare recipe list --filter framework=pytorch --filter state_exchange=full_model --format json
nvflare recipe show fedavg-pt --format json

Human-readable argument errors print help first, followed by the specific error. JSON mode prints only the JSON envelope.