Plugin System

Under Construction

Extend PySH with Python packages. Build, configure, test, and publish plugins.

Overview

Every PySH plugin is a standard Python package. Plugins register commands using a decorator, declare metadata in a TOML file, and are distributed via PyPI. A plugin can add new shell commands, automation workflows, or integrations with external tools.

Plugin anatomy

✓A Python package directory with __init__.py
✓A plugin.py (or similar) with @plugin.command decorated functions
✓A plugin.toml file with metadata and command mappings
✓An optional pyproject.toml or setup.cfg for PyPI distribution
✓Tests in a tests/ directory using pytest

Building a plugin

plugin.py

from pysh import plugin

@plugin.command("hello")

def hello_command() -> None:

"""Say hello from a PySH plugin."""

print("Hello from PySH plugin!")

plugin.toml

[plugin]

name = "hello"

version = "1.0.0"

description = "Example PySH plugin"

[commands]

hello = "hello_command"

Publishing a plugin

PySH plugins are standard Python packages and can be published to PyPI with standard tooling. Once published, users can install them with pip install your-plugin and enable them in .pysh.toml.

Build and publish

# Build the distribution

$ python -m build

# Upload to PyPI

$ twine upload dist/*

Info: For a complete guide to plugin development including testing and quality gates, see PySH Academy Track 4: Plugin Development.