fairseq2.recipes.cli

Classes

class fairseq2.recipes.cli.Cli(name, origin_module, *, version, description=None)[source]

Bases: object

Represents the entry point of a command line program.

Parameters:
  • name (str) – The name of the program.

  • origin_module (str) – The name of the origin Python module of the command line program.

  • version (str) – The version of the program.

  • description (str | None) – The description of the program.

add_group(name, *, help=None, origin_module=None)[source]

Add a sub-group.

Return type:

CliGroup

get_group(name)[source]

Get a sub-group.

Return type:

CliGroup

init_parser(parser)[source]

Initialize parser with program-specific arguments.

run()[source]

Run the program.

Return type:

int

property name: str

The name of the program.

property description: str | None

The description of the program.

property origin_module: str

The name of the origin Python module of the command line program.

property version: str

The version of the program.

class fairseq2.recipes.cli.CliGroup(name, origin_module, *, help=None)[source]

Bases: object

Represents a command group of a command line program.

add_group(name, *, help=None, origin_module=None)[source]

Add a sub-group.

Return type:

CliGroup

get_group(name)[source]

Get a sub-group.

Return type:

CliGroup

add_command(name, handler, *, help=None, origin_module=None)[source]

Add a command.

Parameters:
  • name (str) – The name of the command.

  • handler (CliCommandHandler) – The handler of the command.

  • origin_module (str | None) – The name of origin Python module of the command.

  • help (str | None) – The help text of the command.

Return type:

CliCommand

get_command(name)[source]

Return the command of name.

Return type:

CliCommand

init_parser(parser)[source]

Initialize parser with command group-specific arguments.

property name: str

The name of the command group.

property help: str | None

The help text of the command group.

property origin_module: str

The name of the origin Python module of the command group.

class fairseq2.recipes.cli.CliCommand(name, handler, origin_module, *, help=None)[source]

Bases: object

Represents a command of a command line program.

init_parser(parser)[source]

Initialize parser with command group-specific arguments.

run(args)[source]

Run the command.

Return type:

int

property name: str

The name of the command.

property help: str | None

The help text of the command.

property origin_module: str

The name of the origin Python module of the command.

class fairseq2.recipes.cli.CliCommandHandler[source]

Bases: ABC

Represents the handler of a command of a command line program.

abstract init_parser(parser)[source]

Initialize parser with command-specific arguments.

abstract run(args)[source]

Run the command.

Return type:

int

final class fairseq2.recipes.cli.RecipeCommandHandler(loader, preset_configs, default_preset, *, extra_sweep_keys=None)[source]

Bases: CliCommandHandler, Generic[ConfigT]

Runs a recipe over command line.

Parameters:
  • loader (RecipeLoader[ConfigT]) – The recipe loader.

  • preset_configs (ConfigProvider[ConfigT]) – The registry containing the preset recipe configurations.

  • default_preset (str) – The name of the default preset.

  • extra_sweep_keys (Set[Hashable] | None) – The recipe specific configuration keys to include in the sweep directory name.

init_parser(parser)[source]

Initialize parser with command-specific arguments.

run(args)[source]

Run the command.

Return type:

int

Examples

Creating a Custom CLI

To create a custom CLI, you’ll need to:

  1. Create a CLI group

  2. Add commands to the group

  3. Register your CLI extension

Here’s a complete example:

from fairseq2.recipes.cli import Cli, CliCommandHandler, RecipeCommandHandler

def setup_custom_cli(cli: Cli) -> None:
    # Create a new command group
    group = cli.add_group(
        "custom",
        help="Custom recipes and utilities"
    )

    # Add a command using RecipeCommandHandler
    custom_handler = RecipeCommandHandler(
        loader=load_custom_recipe,      # this is the recipe entrypoint callback function
        preset_configs=custom_presets,  # this is the preset configs registry
        default_preset="default",       # this is the default preset name
        sweep_allowed_keys=["model", "dataset"]  # Optional
    )

    group.add_command(
        name="custom_command",
        handler=custom_handler,
        help="Run custom recipe"
    )

You can find more examples in our recipe examples:

Recipe Command Handler

The RecipeCommandHandler class provides a standardized way to handle recipe commands. It automatically sets up:

  • Configuration management (presets, files, overrides)

  • Output directory handling

  • Logging setup

  • Environment setup for distributed training

Example implementation:

from dataclasses import dataclass
from pathlib import Path
from typing import Callable

@dataclass
class CustomConfig:
    param1: str
    param2: int

def load_custom_recipe(config: CustomConfig, output_dir: Path) -> Callable[[], None]:
    def run_recipe() -> None:
        # Recipe implementation
        pass

    return run_recipe

# Create preset configs
custom_presets = ConfigRegistry(CustomConfig)
custom_presets.register("default", CustomConfig(param1="value", param2=42))

CLI Initialization Process

The CLI system is initialized in the following order:

  1. Cli instance is created in fairseq2.recipes.main()

  2. Core CLI groups are registered in fairseq2.recipes._setup_cli()

  3. Extension CLI groups are registered via fairseq2.recipes._setup_cli_extensions()

To add your own CLI extension:

  1. Create a Python package for your extension

  2. Create an entry point in your package’s setup.py:

setup(
    name="my_fairseq2_extension",
    entry_points={
        "fairseq2.cli": [
            "custom = my_extension.cli:setup_custom_cli"
        ]
    }
)