Getting Started

The first step is to create a new command.

from powercli import Command

cmd = Command(
    name="prog",
    description="Short one-sentence description",
    long_description="Longer multi-sentence description.",
    add_common_flags=True,  # Add "help" and "list" flags
    add_common_subcommands=True,  # Add "help" and "list" subcommands
)

Register Flags

The simplest way to register flags is by using the powercli.command.Command.flag() method:

# ...

cmd.flag(
    identifier="foo",  # Unique identifier used to reference this argument
    short="f",  # A name that can be used when using the short prefix (commonly `-`)
    long="foo",  # A name that can be used when using the long prefix (commonly `--`)
    description="Short one-sentence description",
    long_description="Longer multi-sentence description",
)

Multiple flags can be combined when using their short name:

prog -fg

Register Positionals

The simplest way to register positionals is by using the powercli.command.Command.pos() method:

# ...

from pathlib import Path

cmd.pos(
    identifier="file",  # Unique identifier used to reference this argument
    description="Short one-sentence description",
    long_description="Longer multi-sentence description",
    into=Path,  # Serialize the input (string) into a `Path` object
)

Parsing Arguments

The powercli.command.Command.parse_args() method parses arguments passed to the program. Alternatively you can explicitly specify which arguments should be parsed instead of sys.argv by providing a list of strings as an argument:

# ...

if __name__ == "__main__":
    args = cmd.parse_args()
    
    if not args.raw_args:
        # Invoke help when no argument was provided by user
        args.parse_args([f"{cmd.prefix_long}help"])
        assert False, "unreachable"  # When the help flag is supplied then further execution stops
    
    if args.is_present("foo"):
        print("FOO")

    filepath = args.value_of("file")
    print(filepath.read_text())