Implementation:Bentoml BentoML CLI Utils

Knowledge Sources	Bentoml_BentoML
Domains	CLI, Utilities
Last Updated	2026-02-13 15:00 GMT

Overview

Provides the core BentoMLCommandGroup Click command group class and shared CLI utility functions used across all BentoML CLI commands.

Description

The utils.py module is the foundation of the BentoML CLI infrastructure. It defines:

Core Class - BentoMLCommandGroup: A custom click.Group subclass that adds several features to every CLI command:

Common global options -- Automatically adds --quiet/--verbose (verbosity control), --do-not-track (analytics opt-out), and --context (BentoCloud context) to every command via bentoml_common_params().
Usage tracking -- Wraps command callbacks with bentoml_track_usage() to send anonymized analytics events with timing and error information.
Error handling -- Wraps command callbacks with raise_click_exception() to convert BentoMLException into styled Click error messages, with full tracebacks in debug mode.
Command aliases -- Supports alias names for commands (e.g., serve-http as alias for serve) via the AliasCommand class.
Fuzzy matching -- Overrides resolve_command() to suggest similar command names when a typo is detected using difflib.get_close_matches().
Subcommand aggregation -- add_subcommands() merges commands from another group, preserving aliases.

Utility Functions:

kwargs_transformers() -- Decorator that applies a transformer function to all keyword arguments of a Click callback.
validate_container_tag() / validate_docker_tag() -- Click parameter callbacks that validate Docker/container image tag names against the Docker naming specification.
normalize_none_type() -- Normalizes empty sequences to None for Click parameter handling.
flatten_opt_tuple() -- Unwraps single-element tuples returned by Click's multiple option handling.
opt_callback() -- Click callback for parsing key-value options in the format --opt key=value or --opt key:value, supporting one-to-many value relationships.
setup_verbosity() -- Callback that configures BentoML logging verbosity from the CLI flag.
setup_track() -- Callback that sets the BENTOML_DO_NOT_TRACK environment variable.
setup_cloud_client() -- Callback that configures the BentoCloud context for authenticated operations.
is_valid_bento_tag() / is_valid_bento_name() -- Validation helpers for bento tag and name formats.
get_entry_points() -- Compatible wrapper for importlib.metadata.entry_points() supporting Python < 3.10.
set_build_args() / set_build_args_from_file() -- Click callbacks for parsing build arguments from CLI flags or YAML files.
build_args_option() -- Decorator that adds --arg and --arg-file options to a Click command.

Usage

This module is used by virtually every BentoML CLI command. The BentoMLCommandGroup is the standard cls parameter for all @click.group() decorators in the CLI, and the utility functions are used as Click callbacks and validators throughout the CLI codebase.

Code Reference

Source Location

Repository: Bentoml_BentoML
File: src/bentoml_cli/utils.py
Lines: 1-537

Signature

class AliasCommand(click.Command):
    def __init__(self, *args, aliases: list[str] | None = None, **kwargs) -> None: ...

class BentoMLCommandGroup(click.Group):
    NUMBER_OF_COMMON_PARAMS = 5

    @staticmethod
    def bentoml_common_params(f: F[P]) -> ClickFunctionWrapper[P]: ...

    @staticmethod
    def bentoml_track_usage(func: F[P], cmd_group: click.Group, name: str | None) -> F[P]: ...

    @staticmethod
    def raise_click_exception(func: F[P], cmd_group: click.Group, name: str | None) -> F[P]: ...

    def __init__(self, *args, **kwargs) -> None: ...
    def add_subcommands(self, group: click.Group) -> None: ...
    def add_command(self, cmd: Command, name: str | None = None) -> None: ...
    def resolve_alias(self, cmd_name: str): ...
    def get_command(self, ctx: Context, cmd_name: str) -> Command | None: ...
    def format_commands(self, ctx: Context, formatter: HelpFormatter) -> None: ...
    def resolve_command(self, ctx, args) -> tuple[str | None, Command | None, list[str]]: ...

def kwargs_transformers(f=None, *, transformer, pass_click_context=False) -> F: ...
def validate_container_tag(ctx, param, tag) -> str | tuple[str] | None: ...
def validate_docker_tag(ctx, param, tag) -> str | tuple[str] | None: ...
def normalize_none_type(value) -> ClickParamType | t.Mapping[str, t.Any]: ...
def flatten_opt_tuple(value: t.Any) -> t.Any: ...
def opt_callback(ctx: Context, param: Parameter, value: ClickParamType): ...
def setup_verbosity(ctx: Context, param: Parameter, value: int) -> int: ...
def setup_track(ctx: Context, param: Parameter, value: bool) -> bool: ...
def setup_cloud_client(ctx: Context, param: Parameter, value: str | None) -> str | None: ...
def is_valid_bento_tag(value: str) -> bool: ...
def is_valid_bento_name(value: str) -> bool: ...
def get_entry_points(group: str) -> t.Iterable[EntryPoint]: ...
def set_build_args(ctx: Context, param: Parameter, value: str | tuple[str]) -> None: ...
def set_build_args_from_file(ctx: Context, param: Parameter, value: str) -> None: ...
def build_args_option(f: t.Callable[..., t.Any]): ...

Import

from bentoml_cli.utils import BentoMLCommandGroup, AliasCommand
from bentoml_cli.utils import validate_container_tag, opt_callback
from bentoml_cli.utils import is_valid_bento_tag, is_valid_bento_name
from bentoml_cli.utils import build_args_option

I/O Contract

Inputs

Name	Type	Required	Description
--quiet / -q	flag	No	Suppress all warnings and info logs (sets verbosity to -1)
--verbose / --debug	flag	No	Enable debug-level logging (sets verbosity to 1)
--do-not-track	flag	No	Disable anonymized usage analytics
--context	str	No	BentoCloud context name for authenticated operations
--arg	str (multiple)	No	Build arguments in KEY=VALUE format
--arg-file	path	No	YAML file containing build arguments
tag (validator)	str or tuple[str]	Yes	Docker/container image tag to validate

Outputs

Name	Type	Description
BentoMLCommandGroup	click.Group subclass	Custom command group with common params, tracking, and error handling
validate_container_tag return	tuple[str] \| None	Validated container tag(s) or None
is_valid_bento_tag return	bool	True if the string is a valid bento tag format
is_valid_bento_name return	bool	True if the string is a valid bento name (alphanumeric and underscores)
opt_callback return	ClickParamType	Parsed and memoized option values

Usage Examples

# Define a CLI group using BentoMLCommandGroup
import click
from bentoml_cli.utils import BentoMLCommandGroup

@click.group(cls=BentoMLCommandGroup)
def cli():
    """My BentoML CLI."""
    pass

@cli.command()
def serve():
    """Serve a bento."""
    pass

# Define a command with aliases
from bentoml_cli.utils import AliasCommand

@cli.command(cls=AliasCommand, aliases=["serve-http"])
def serve():
    """Serve a bento (alias: serve-http)."""
    pass

# Validate a container tag in a Click option
from bentoml_cli.utils import validate_container_tag

@cli.command()
@click.option("--tag", callback=validate_container_tag)
def build(tag):
    pass

# Use build args options decorator
from bentoml_cli.utils import build_args_option

@cli.command()
@build_args_option
def build_bento():
    """Build with --arg KEY=VALUE and --arg-file support."""
    pass

# Check if a string is a valid bento tag
from bentoml_cli.utils import is_valid_bento_tag
assert is_valid_bento_tag("my_model:v1")
assert not is_valid_bento_tag("invalid tag!")

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment