Implementation:Huggingface Optimum Optimum CLI Main

Knowledge Sources	Huggingface_Optimum Optimum Docs
Domains	CLI, Plugin_Architecture
Last Updated	2026-02-15 00:00 GMT

Overview

Concrete tool for the `optimum-cli` main entry point, subcommand registration, and plugin discovery provided by the Huggingface Optimum library.

Description

This module defines the `optimum-cli` entry point via the main() function. It assembles the CLI by:

1. Creating a RootOptimumCLICommand instance
2. Registering built-in subcommands (export, env)
3. Loading subpackage plugins via load_subpackages()
4. Discovering and registering additional commands from the `optimum.commands.register` namespace
5. Parsing arguments and dispatching to the appropriate command's `run()` method

The optimum_cli_subcommand decorator allows third-party packages to declaratively register CLI subcommands. The resolve_command_to_command_instance function traverses the command tree to map command classes to their instantiated counterparts.

Usage

The main() function is the console_scripts entry point for `optimum-cli`. Use the optimum_cli_subcommand decorator in subpackages to register custom commands that will be discovered when `optimum-cli` starts.

Code Reference

Source Location

• Repository: Huggingface_Optimum
• File: optimum/commands/optimum_cli.py
• Lines: 1-224

Signature

def optimum_cli_subcommand(parent_command: Optional[Type[BaseOptimumCLICommand]] = None):
    """Decorator to declare optimum-cli subcommands.

    Args:
        parent_command: The class of the parent command or None for top-level.
    """

def resolve_command_to_command_instance(
    root: RootOptimumCLICommand,
    commands: List[Type[BaseOptimumCLICommand]]
) -> Dict[Type[BaseOptimumCLICommand], BaseOptimumCLICommand]:
    """Map command classes to their instances in the CLI tree."""

def load_optimum_namespace_cli_commands() -> List[Tuple[Union[Type[BaseOptimumCLICommand], CommandInfo], Optional[Type[BaseOptimumCLICommand]]]]:
    """Load commands from the optimum.commands.register namespace."""

def register_optimum_cli_subcommand(
    command_or_command_info: Union[Type[BaseOptimumCLICommand], CommandInfo],
    parent_command: BaseOptimumCLICommand,
):
    """Register a command as a subcommand of parent_command."""

def main():
    """Entry point for optimum-cli."""

Import

from optimum.commands.optimum_cli import main, optimum_cli_subcommand

I/O Contract

Inputs

Name	Type	Required	Description
parent_command (decorator)	Type[BaseOptimumCLICommand]	No	Parent command class for nesting; None means top-level
sys.argv	List[str]	Yes	Command-line arguments parsed by argparse

Outputs

Name	Type	Description
main()	None	Parses args and dispatches to the matched command's run() method
optimum_cli_subcommand	Callable	Decorator that registers a class as a CLI subcommand

Usage Examples

Registering a Custom CLI Subcommand

from optimum.commands.optimum_cli import optimum_cli_subcommand
from optimum.commands.base import BaseOptimumCLICommand, CommandInfo

@optimum_cli_subcommand()
class QuantizeCommand(BaseOptimumCLICommand):
    COMMAND = CommandInfo(name="quantize", help="Quantize a model")

    @staticmethod
    def parse_args(parser):
        parser.add_argument("--model", type=str, required=True)
        parser.add_argument("--bits", type=int, default=4)

    def run(self):
        print(f"Quantizing {self.args.model} to {self.args.bits} bits")

Registering Under an Existing Parent

from optimum.commands.optimum_cli import optimum_cli_subcommand
from optimum.commands.export.base import ExportCommand

@optimum_cli_subcommand(ExportCommand)
class ExportTFLiteCommand(BaseOptimumCLICommand):
    COMMAND = CommandInfo(name="tflite", help="Export model to TFLite format")

    @staticmethod
    def parse_args(parser):
        parser.add_argument("--model", type=str, required=True)

    def run(self):
        print(f"Exporting {self.args.model} to TFLite")

Related Pages

• Environment:Huggingface_Optimum_Python_Core_Dependencies