CLI API

​

Constructing a CLI

from runegraft import cli

app = cli.CLI(name="forge", description="Package builder")

• name: controls how usage is rendered and becomes the default shell prompt (forge>).
• description: printed at the top of help output.

​

Registering commands

@app.command("install <url:url> [target:path]")
def install(url: str, target: Path | None = None):
    """Download and stage a package."""
    ...

• Route strings are parsed by parse_route and enforce positional types; an error is raised at startup if a reserved shell command name is reused.
• The first line of the docstring becomes the summary column in help.
• All function annotations are available during parsing, so you can combine route tokens and type hints (e.g., type hints drive option coercion).

​

Options and flags

@app.command("ship <pkg:str>")
def ship(pkg: str, dry_run: bool = False, retries: int = 1):
    ...

• dry_run automatically becomes --dry-run and, because it is typed as bool, behaves like a flag (--dry-run sets the value to True).
• Non-bool parameters expect a value: --retries 3.
• Defaults come from the function signature; use runegraft.cli.option to override the long/short flag names or add help text.

from runegraft.cli import option

@app.command("echo <text:str>")
def echo(
    text: str,
    upper: bool = option("--upper", "-U", default=False, help="Uppercase output", is_flag=True),
):
    ...

​

Custom converters

@app.type("semver")
def parse_semver(raw: str) -> tuple[int, int, int]:
    ...

@app.command("bump <version:semver>")
def bump(version):
    ...

​

Execution helpers

• CLI.run(argv: Optional[List[str]]): dispatch arguments (or sys.argv[1:] by default). Automatically handles --help and empty input.
• CLI.invoke(tokens: List[str]): run one command when you already parsed the leading command name.
• CLI.shell(): construct and run the interactive loop from shell.py.
• CLI.print_help(): render the Rich table shown in the shell.