Writing plugins

better-pkg supports a flexible plugin system, allowing you to extend its functionality without modifying the core script. Plugins are written in Python and can add new commands, hooks, setup options, or custom handlers.

Where to Place Plugins

• Place your plugin .py file in:
  ~/.local/share/better-tools/plugins/
• The filename should end with .py and not start with _.

Plugin Structure

Each plugin must define a register() function with the following signature:

def register(command_handlers, hooks, setup_functions, package_groups_extensions, custom_json_handlers):
    # Your plugin logic here

• command_handlers: Dictionary of CLI commands (add your own command here)
• hooks: Dictionary of hooks for update/upgrade/cleanup
• setup_functions: Dictionary for adding new setup options
• package_groups_extensions: List for extending package groups
• custom_json_handlers: Dictionary for handling custom keys in setup-custom JSON

Example: Simple Command Plugin

# ~/.local/share/better-tools/plugins/hello.py

def hello_command(args):
    print("Hello from better-pkg plugin!")

def register(command_handlers, hooks, setup_functions, package_groups_extensions, custom_json_handlers):
    command_handlers["hello"] = hello_command

After saving, run:

better-pkg hello

Example: Add a Setup Option

def setup_fun():
    print("Installing my favorite tools...")
    # You can call install_package(["mytool"], "apt") etc.

def register(command_handlers, hooks, setup_functions, package_groups_extensions, custom_json_handlers):
    setup_functions["mysetup"] = setup_fun

Now you can run:

better-pkg setup mysetup

Example: Add an Update Hook

def my_update_hook(args):
    print("This runs after every update!")

def register(command_handlers, hooks, setup_functions, package_groups_extensions, custom_json_handlers):
    hooks["update-plugin"].append(my_update_hook)

Tips

• Use only standard Python and better-pkg’s public functions.
• Avoid dangerous operations (better-pkg checks if plugins contains dangerous operations and will warn user).
• You can import modules, but keep dependencies minimal.
• For advanced plugins, see the source code of official plugins.

Debugging

• Errors in plugins are shown when better-pkg starts.
• Remove or fix broken plugins in the plugins directory.

Sharing Plugins

• You can share your plugin by uploading the .py file.
• To install a plugin from the official repo:

  better-pkg install -c <plugin_name>