Clypi

Subcommands allow you to group related commands under a single entry point. To implement subcommands, create separate Command classes for each subcommand and define a class-level attribute named subcommand in your main Command class. The type hint for subcommand should be a Union of the subcommand classes.

from clypi import Command, Positional, arg
from typing_extensions import override

class Greet(Command):
    """Say hi to someone"""
    name: Positional[str] = arg(help="Your name")

    @override
    async def run(self):
        print(f"Hello, {self.name}")

class Wave(Command):
    """Wave at someone"""
    name: Positional[str] = arg(help="Your name")

    @override
    async def run(self):
        print(f"👋 {self.name}")

class Cli(Command):
    """A very simple CLI"""
    subcommand: Greet | Wave

if __name__ == '__main__':
    cmd = Cli.parse()
    cmd.start()

To avoid redefining the same arguments across multiple subcommands, you can use argument inheritance. Define an argument in a parent Command and use arg(inherited=True) in the child commands. The child commands will automatically inherit the full definition (including help text, short flags, and groups) from the parent.

Note: The parent command must define the argument with its full configuration (help, short flags, etc.) for the child to receive the complete definition.

from clypi import Command, Positional, arg
from typing_extensions import override

class Wave(Command):
    """Wave at someone"""
    name: Positional[str]
    # Inherits the full definition from the parent 'Cli' command
    verbose: bool = arg(inherited=True)

    @override
    async def run(self) -> None:
        print(f"👋 Hey {self.name}")
        if self.verbose:
            print(f"👋👋👋 HEYYY {self.name}")

class Cli(Command):
    """A very simple CLI"""
    subcommand: Wave | None
    verbose: bool = arg(
        False, short="v", help="Whether to show verbose output", group="global"
    )

if __name__ == "__main__":
    cmd = Cli.parse()
    cmd.start()

For complex CLIs where an argument's necessity depends on other flags, use arg(defer=True).

When an argument is deferred, Clypi will not prompt the user for the value or require it to be passed during the initial parsing phase. Instead, the prompt or validation only occurs at the moment the attribute is actually accessed in your code. This allows you to implement conditional logic where certain arguments are only requested if specific conditions are met during execution.

from clypi import Command, arg
from typing_extensions import override

class Cli(Command):
    single_threaded: bool = arg(False)
    num_cores: int = arg(
        defer=True,
        prompt="How many CPU cores do you want to use?"
    )

    @override
    async def run(self):
        # Accessing single_threaded does not trigger the num_cores prompt
        print("Running single threaded:", self.single_threaded)
        
        if self.single_threaded:
            print("Running single threaded...")
        else:
            # The prompt for 'num_cores' is triggered here because the attribute is accessed
            threads = self.num_cores // 4
            print("Running with threads:", threads)

if __name__ == "__main__":
    cmd = Cli.parse()
    cmd.start()