CLI Tools Plugin

Advanced development and automation tools for Structum framework.

Plugin License

Overview

The CLI Tools plugin extends the base Structum CLI with industry-grade features for security, testing, profiling, release automation, and more.

Architecture

The plugin respects Structum’s Zero-Dependency philosophy by separating core from advanced tools:

┌──────────────────────────────────────┐
│ structum (Meta Package)              │
│ ├─ check      (Ruff/Black)           │ ← Zero-Dep Core
│ ├─ build-docs (Sphinx)               │
│ └─ license    (REUSE)                │
├──────────────────────────────────────┤
│ structum-cli-tools (This Plugin)     │
│ ├─ security   (Bandit, Safety)       │ ← Batteries-Included
│ ├─ test       (pytest, coverage)     │
│ ├─ profile    (py-spy, memory)       │
│ ├─ release    (semantic-release)     │
│ ├─ api        (griffe)                │
│ ├─ plugin     (marketplace)           │
│ ├─ validate   (contract testing)      │
│ ├─ i18n       (babel)                 │
│ └─ telemetry  (opt-in analytics)      │
└──────────────────────────────────────┘

Auto-Discovery: Commands automatically register when plugin is installed (via entry points).

Installation

With Meta Package

# Recommended: Full tooling
pip install structum structum-cli-tools

Standalone

# Plugin only (requires structum)
pip install structum-cli-tools

Development

# Clone repository
git clone https://github.com/PythonWoods/structum.git
cd structum

# Install with workspace
uv sync --extra dev

Features

🔒 Security Scanning

Static code analysis + dependency vulnerability checking:

structum security scan              # Bandit code scan
structum security audit             # Full audit (Bandit + Safety)
structum security report -o sec.json  # JSON report

See: :doc:/cli/security | :doc:/security/scanning

🧪 Testing & Coverage

pytest integration with enforced thresholds:

structum test                       # Run tests
structum test --cov                 # With coverage
structum test --cov --cov-fail-under=90  # Enforce 90%

Configuration: .coveragerc, pyproject.toml [tool.pytest]

See: :doc:/cli/testing

⚡ Performance Profiling

CPU and memory profiling for optimization:

structum profile run app.py         # CPU profiling
structum profile memory app.py      # Memory tracking
structum profile benchmark          # Run benchmarks

Tools: py-spy, memory_profiler, pytest-benchmark

See: :doc:/cli/profiling

🚀 Release Automation

Semantic versioning and changelog generation:

structum release prepare            # Bump version + changelog
structum release validate           # Pre-release checks
structum release publish            # Publish to PyPI

Based on: Conventional Commits, semantic-release

See: :doc:/cli/release | :doc:/contributing/releasing

📜 API Stability

Detect breaking changes in public API:

structum api diff v0.1.0..HEAD      # Compare versions
structum api validate               # Check current API

Tool: griffe (Python API inspector)

See: :doc:/cli/api

🔌 Plugin Marketplace

Discover and install community plugins:

structum plugin search redis        # Search plugins
structum plugin install structum-redis  # Install
structum plugin verify structum-redis   # Verify signatures

Registry: registry/plugins.json (GitHub Pages)

See: :doc:/cli/plugins | :doc:/plugins/marketplace

✅ Contract Testing

Validate plugin compliance with protocols:

structum validate plugin packages/auth/
structum validate all

Validates: Protocol implementation, type safety

See: :doc:/cli/validation | :doc:/plugins/development

🌍 Internationalization

Multi-language CLI support:

structum i18n extract               # Extract messages
structum i18n compile               # Compile .mo files
structum --lang=it check            # Italian messages

Platform: GNU gettext + Babel

See: :doc:/cli/i18n | :doc:/contributing/i18n

📈 Telemetry (Opt-in)

Privacy-first anonymous analytics:

structum telemetry enable           # Opt-in
structum telemetry status           # Check status
structum telemetry disable          # Opt-out

What’s collected: Command usage, error types (NO personal data)

See: :doc:/cli/telemetry | :doc:/privacy/policy

Development

Adding New Commands

  1. Create module in src/structum/plugins/cli_tools/:

# src/structum/plugins/cli_tools/mycommand.py
import typer

mycommand_app = typer.Typer(
    name="mycommand",
    help="My new command",
)

@mycommand_app.command()
def run():
    """Run my command."""
    print("Hello!")

  1. Register in __init__.py:

def register_commands(app: typer.Typer) -> None:
    from structum.plugins.cli_tools.mycommand import mycommand_app
    app.add_typer(mycommand_app, name="mycommand")

  1. Document:

    • Add docs/cli/mycommand.rst

    • Update docs/cli/index.md

    • Add cross-references

  2. Test:

    • Create tests/cli_tools/test_mycommand.py

    • Verify help text

    • Integration test

Architecture Details

Entry Points

Plugin registration via pyproject.toml:

[project.entry-points."structum.cli_plugins"]
cli_tools = "structum.plugins.cli_tools:register_commands"

Auto-Discovery

Meta CLI loads plugins automatically:

# In structum.cli (Meta package)
from importlib.metadata import entry_points

for ep in entry_points(group="structum.cli_plugins"):
    register_func = ep.load()
    register_func(app)

Graceful Degradation

If plugin not installed, commands unavailable but no errors:

$ structum security scan
# Without structum-cli-tools:
# Error: Unknown command 'security'
# Install with: pip install structum-cli-tools

Dependencies

Security

  • bandit[toml]>=1.7.5 - Code vulnerability scanner

  • safety>=3.0.0 - Dependency CVE checker

Testing

  • pytest>=7.4.0 - Test framework

  • pytest-cov>=4.1.0 - Coverage plugin

  • coverage[toml]>=7.3.0 - Coverage measurement

Profiling

  • py-spy>=0.3.14 - Sampling profiler

  • memory-profiler>=0.61.0 - Memory tracking

  • pytest-benchmark>=4.0.0 - Benchmarking

Release

  • python-semantic-release>=8.5.0 - Semantic versioning

  • towncrier>=23.11.0 - Changelog generation

Others

  • griffe>=0.38.0 - API inspection

  • requests>=2.31.0 - HTTP client (marketplace)

  • keyring>=24.3.0 - Secure credential storage

  • babel>=2.14.0 - Internationalization

Contributing

See main CONTRIBUTING for guidelines.

Plugin-specific:

  • All commands must have comprehensive docstrings

  • Sphinx cross-references required

  • Examples in both docstrings and .rst files

  • Unit tests + integration tests

  • Ruff/Black compliant

License

Apache-2.0 - See LICENSE

See Also

  • :doc:/cli/index - Complete CLI reference

  • :doc:/plugins/development - Plugin development guide

  • :doc:/architecture/cli-design - CLI plugin system design

  • :mod:structum.cli - Base CLI module

  • :mod:structum.plugins.cli_tools - Plugin API reference