Commands

provide.foundation.hub.commands

Command registration and management for the hub.

This module re-exports from the split modules for convenience.

Classes

CommandInfo

Framework-agnostic command information.

Stores metadata about a registered command without framework-specific dependencies. The parameters field contains introspected parameter information that can be used by any CLI adapter.

Attributes:

Name	Type	Description
name	str	Command name
func	Callable[..., Any]	Command function/callable
description	str | None	Command description (help text)
aliases	list[str]	Alternative names for the command
hidden	bool	Whether command is hidden from help
category	str | None	Command category for organization
metadata	dict[str, Any]	Additional custom metadata
parent	str | None	Parent command path (for nested commands)
parameters	list[ParameterInfo] | None	Introspected parameter information (lazy-loaded)

Functions

create_command_group

create_command_group(
    name: str = "cli",
    commands: list[str] | None = None,
    registry: Any = None,
    **kwargs: Any
) -> Any

Create command group (imports on first call to avoid circular import).

Source code in provide/foundation/hub/commands.py

def create_command_group(
    name: str = "cli",
    commands: list[str] | None = None,
    registry: Any = None,
    **kwargs: Any,
) -> Any:
    """Create command group (imports on first call to avoid circular import)."""
    if not _check_click():
        raise ImportError("CLI feature 'create_command_group' requires: pip install 'provide-foundation[cli]'")
    from provide.foundation.cli.click.builder import create_command_group as real_func

    return real_func(name, commands, registry, **kwargs)

get_command_registry

get_command_registry() -> Registry

Get the global command registry.

Source code in provide/foundation/hub/registry.py

def get_command_registry() -> Registry:
    """Get the global command registry."""
    return _command_registry

register_command

register_command(
    name: str | None = None,
    *,
    description: str | None = None,
    aliases: list[str] | None = None,
    hidden: bool = False,
    category: str | None = None,
    group: bool = False,
    replace: bool = False,
    registry: Registry | None = None,
    **metadata: Any
) -> Callable[[F], F]

register_command(func: F) -> F

register_command(
    name_or_func: str | F | None = None,
    *,
    description: str | None = None,
    aliases: list[str] | None = None,
    hidden: bool = False,
    category: str | None = None,
    group: bool = False,
    replace: bool = False,
    registry: Registry | None = None,
    **metadata: Any
) -> Any

Register a CLI command in the hub.

Can be used as a decorator with or without arguments:

@register_command
def my_command():
    pass

@register_command("custom-name", aliases=["cn"], category="utils")
def my_command():
    pass

# Nested commands using dot notation - groups are auto-created
@register_command("container.status")
def container_status():
    pass

@register_command("container.volumes.backup")
def container_volumes_backup():
    pass

# Explicit group with custom description (optional)
@register_command("container", group=True, description="Container management")
def container_group():
    pass

Parameters:

Name	Type	Description	Default
name_or_func	str | F | None	Command name using dot notation for nesting (e.g., "container.status")	None
description	str | None	Command description (defaults to docstring)	None
aliases	list[str] | None	Alternative names for the command	None
hidden	bool	Whether to hide from help listing	False
category	str | None	Command category for grouping	None
group	bool	Whether this is a command group (not a command)	False
replace	bool	Whether to replace existing registration	False
registry	Registry | None	Custom registry (defaults to global)	None
**metadata	Any	Additional metadata stored in CommandInfo.metadata	{}

Returns:

Type	Description
Any	Decorator function or decorated function

Source code in provide/foundation/hub/decorators.py

def register_command(  # type: ignore[misc]
    name_or_func: str | F | None = None,
    *,
    description: str | None = None,
    aliases: list[str] | None = None,
    hidden: bool = False,
    category: str | None = None,
    group: bool = False,
    replace: bool = False,
    registry: Registry | None = None,
    **metadata: Any,
) -> Any:
    """Register a CLI command in the hub.

    Can be used as a decorator with or without arguments:

        @register_command
        def my_command():
            pass

        @register_command("custom-name", aliases=["cn"], category="utils")
        def my_command():
            pass

        # Nested commands using dot notation - groups are auto-created
        @register_command("container.status")
        def container_status():
            pass

        @register_command("container.volumes.backup")
        def container_volumes_backup():
            pass

        # Explicit group with custom description (optional)
        @register_command("container", group=True, description="Container management")
        def container_group():
            pass

    Args:
        name_or_func: Command name using dot notation for nesting (e.g., "container.status")
        description: Command description (defaults to docstring)
        aliases: Alternative names for the command
        hidden: Whether to hide from help listing
        category: Command category for grouping
        group: Whether this is a command group (not a command)
        replace: Whether to replace existing registration
        registry: Custom registry (defaults to global)
        **metadata: Additional metadata stored in CommandInfo.metadata

    Returns:
        Decorator function or decorated function

    """
    # Handle @register_command (without parens)
    if callable(name_or_func) and not isinstance(name_or_func, str):
        func = name_or_func
        return _register_command_func(
            func,
            name=None,
            description=description,
            aliases=aliases,
            hidden=hidden,
            category=category,
            group=group,
            replace=replace,
            registry=registry,
            **metadata,
        )

    # Handle @register_command(...) (with arguments)
    # At this point, name_or_func must be str | None (not F)
    name_str: str | None = name_or_func if isinstance(name_or_func, str) or name_or_func is None else None

    def decorator(func: F) -> F:
        return _register_command_func(
            func,
            name=name_str,
            description=description,
            aliases=aliases,
            hidden=hidden,
            category=category,
            group=group,
            replace=replace,
            registry=registry,
            **metadata,
        )

    return decorator