multitool 0.7.0

TL;DR

This section shows how to start prototyping plugins on your local machine. See the sections below to learn how to distribute your commands as remote plugins that can be installed and updated from Git repositories.

Create a new local plugin:

multitool plugins new test

Show the generated command help:

multitool run test hello --help

Run the example command:

multitool run test hello \
    "Hello, World!" \
    --count 3 \
    --format json \
    -vv \
    --enabled \
    --tag alpha \
    --tag beta \
    --output result.json

Edit the generated source code:

vim ~/.multitool/plugins/test/plugin_*.py

Usage

Usage: multitool [OPTIONS] COMMAND [ARGS]...

  Create and run plugin-based command-line tools.

Options:
  -V, --version  Show the version and exit.
  -h, --help     Show this message and exit.

Commands:
  plugins  Manage plugin repositories.
  run      Run installed plugin commands.

Managing plugins

Plugins are distributed as Git repositories containing Click commands.

The plugins command manages plugin repositories, while installed plugin commands are available under multitool run.

Git is required to install or update plugins. If Git is unavailable, the plugins command cannot install repositories, although plugins can still be installed manually by copying them into:

~/.multitool/plugins/PLUGIN_NAME/

multitool plugins new PLUGIN_NAME

~/.multitool/plugins/PLUGIN_NAME/

PLUGIN_NAME/
├── __init__.py
├── plugin_<unique-id>.py
├── multitool-info.json
├── README.md
└── LICENSE

multitool run PLUGIN_NAME -h

multitool plugins configure -a

[sources]
public = https://github.com/mdelotavo/multitool-plugins.git

~/.multitool/plugins/

echo -e '[sources]\npublic = https://github.com/mdelotavo/multitool-plugins.git' >> ~/.multitool/plugins/config

multitool plugins update
multitool plugins show
multitool plugins show -n public
multitool plugins show -n public --show-commit-only
multitool plugins show -n public --show-dependencies-only
pip3 install $(multitool plugins show -n public --show-dependencies-only)

multitool run examples -h

multitool plugins update

multitool plugins prune

multitool plugins show

multitool plugins show -n PLUGIN_NAME --show-commit-only
multitool plugins show -n PLUGIN_NAME --show-dependencies-only

pip3 install $(multitool plugins show -n PLUGIN_NAME --show-dependencies-only)

Troubleshooting

If a plugin fails to install or load, check the log file:

~/.multitool/multitool.log

It contains installation, dependency, and Git-related errors.

Limitations

Plugin command names must be unique across all installed repositories.

To avoid naming conflicts, plugin modules should follow the convention of including the repository owner and repository name in the command name.

For example, a repository configured as:

[sources]
public = https://github.com/mdelotavo/multitool-plugins.git

should expose commands using a unique name such as:

mdelotavo-multitool-plugins

This prevents duplicate command names when multiple repositories provide plugins with the same module name. If two plugins expose commands with the same name, only one can be loaded and the duplicate plugin will be skipped.

If two repositories expose the same command name, Multitool will fail to load the duplicate plugin and raise an error similar to:

Duplicate plugin command "examples" found in
/home/user/.multitool/plugins/PLUGIN_NAME/__init__.py.
Already loaded from plugins_modules.examples

To resolve the issue, remove the conflicting plugin repository from your local plugins directory:

~/.multitool/plugins/PLUGIN_NAME/

and remove the repository from the configured sources.

You can edit the configuration file manually:

~/.multitool/plugins/config

or open it using:

multitool plugins configure

After removing the conflicting repository, update the installed plugins:

multitool plugins update