CLI Tools Plugin API Reference

Complete API reference for the Structum CLI Tools plugin.

Overview

The CLI Tools plugin provides industry-grade development tools for Structum projects. All commands are automatically registered with the main CLI when the plugin is installed.

Installation:

pip install structum-cli-tools

Package Structure

structum.plugins.cli_tools/
├── __init__.py          # Plugin registration
├── security.py          # Security scanning commands
├── testing.py           # Test and coverage commands
├── profiling.py         # Performance profiling
├── release.py           # Release automation
├── api.py               # API stability checking
├── plugins.py           # Plugin marketplace
├── validation.py        # Contract testing
├── i18n.py              # Internationalization
└── telemetry.py         # Opt-in analytics

Module Contents

Plugin Registration

The main entry point called by the Meta CLI to register all plugin commands.

Security Commands

Testing Commands

Profiling Commands

Release Commands

API Commands

Development

Creating New Commands

Example structure for adding a new command:

# src/structum/plugins/cli_tools/newcommand.py
import typer
from rich.console import Console

newcommand_app = typer.Typer(
    name="newcommand",
    help="Description of new command",
)

console = Console()

@newcommand_app.command()
def run(
    arg: str = typer.Argument(..., help="Argument description"),
    opt: bool = typer.Option(False, "--opt", help="Option description"),
) -> None:
    """Command description.

    Detailed explanation of what the command does.

    Args:
        arg: Argument documentation
        opt: Option documentation

    Example:
        .. code-block:: bash

            structum newcommand myarg --opt

    See Also:
        :func:`related_function`
        :doc:`/cli/newcommand`
    """
    console.print(f"Running with {arg}")

Then register in __init__.py:

def register_commands(app: typer.Typer) -> None:
    # ... existing registrations ...
    try:
        from structum.plugins.cli_tools.newcommand import newcommand_app
        app.add_typer(newcommand_app, name="newcommand")
    except ImportError:
        pass

Testing

All commands should have comprehensive tests:

# tests/cli_tools/test_newcommand.py
from typer.testing import CliRunner
from structum.plugins.cli_tools.newcommand import newcommand_app

runner = CliRunner()

def test_newcommand_help():
    result = runner.invoke(newcommand_app, ["--help"])
    assert result.exit_code == 0
    assert "Description of new command" in result.stdout

def test_newcommand_run():
    result = runner.invoke(newcommand_app, ["run", "test"])
    assert result.exit_code == 0

Documentation

Complete documentation package includes:

  1. Docstrings with Sphinx cross-references

  2. RST file in docs/cli/newcommand.rst

  3. Update docs/cli/index.md

  4. Update this file (docs/reference/cli-tools.rst)

See Also