Cli - Package auto assembler

Skip to content

# CLI Interface

## About

PAA supports packaging package-specific CLI modules and exposing them through installed entrypoints. The package CLI source is expected in `cli/<module_name>.py` (or configured `cli_dir`). Core dependency used under the hood: Click. PAA expects one CLI file per package, with filename matching the package/module name. For cross-component preflight checks before packaging, see `concepts/prepackaging_todo.md`.

## Quick Start

### 1. Initialize CLI scaffold for a package

    paa init-cli your-package-1

This creates `cli/your_package_1.py` (or configured `cli_dir`).

### 2. Package and install

    paa test-install your-package-1 --skip-deps-install

### 3. Run installed package CLI

Use the package entrypoint configured by that package (as defined in package metadata). Metadata field details (including CLI naming interactions) are documented in `components/package_metadata.md`.

## Operational Commands

Initialize CLI scaffold:

    paa init-cli your-package-1

Package/install and validate CLI wiring:

    paa test-install your-package-1 --skip-deps-install

Inspect available package metadata and requirements:

    paa show-module-info your-package-1
    paa show-module-requirements your-package-1

## Python File Layout

### CLI module file

- path: `cli/<module_name>.py` (or configured `cli_dir`)
- expected structure:
- `click` command group
- one or more commands bound to the group
- optional `if __name__ == "__main__":` runner for direct file execution

Recommended layout:

    import click
    from your_package_1.your_package_1 import *

    __cli_metadata__ = {
        "name": "your_package_1"
    }

    @click.group()
    def cli():
        """CLI for your-package-1."""

    @click.command()
    @click.option("--name", default="world")
    def ping(name: str):
        click.echo(f"pong: {name}")

    cli.add_command(ping, "ping")

    if __name__ == "__main__":
        cli()

For larger CLIs, explicit `cli.add_command(...)` registration is recommended to keep command wiring obvious.

### Optional CLI metadata

CLI module can define:

    __cli_metadata__ = {
        "name": "your_package_1"
    }

`name` controls generated console script command name. - default behavior (if metadata is omitted): package/module name without dashes - override behavior: set `__cli_metadata__["name"]` to desired command label

## Importing From Package

Default import style for CLI modules:

- `from <package>.<package> import *`

Guidance: - import from package namespace, not from PPR component file paths. - keep CLI modules lightweight; call into package functions/classes rather than embedding heavy logic in CLI handlers. - keep command names stable once users/scripts depend on them.

## Packaging Notes

During packaging, PAA copies package CLI module into installed package files as `cli.py`. If no CLI module exists for a package, no package-specific CLI script is prepared. Imports from the package CLI module are included in dependency extraction during packaging, similar to the main module.

## Notes

- Use `--help` on each command group for discoverability.
- Keep user-facing messages explicit and actionable for automation workflows.