multitool 0.8.0

Creating plugins

Create a new plugin scaffold with:

multitool plugins new PLUGIN_NAME

This creates a local plugin repository under:

~/.multitool/plugins/PLUGIN_NAME/

The generated structure includes:

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

The generated plugin contains a Click command group named PLUGIN_NAME and an example hello command. Add additional commands to the generated plugin_<unique-id>.py module.

Test the plugin locally with:

multitool run PLUGIN_NAME -h

To distribute the plugin:

1. Initialize the plugin directory as a Git repository:

   cd ~/.multitool/plugins/PLUGIN_NAME
   git init

2. Commit and push it to a remote Git repository such as GitHub or GitLab.

3. Add the repository URL to the Multitool configuration:

   [sources]
   PLUGIN_NAME = https://github.com/<user>/PLUGIN_NAME.git

4. Install or update plugins:

   multitool plugins update

Alternatively, copy the plugin directory directly into another Multitool plugins directory to use it locally.

Configuring

Configure plugin repositories with:

multitool plugins configure

This opens your editor to modify the plugin configuration. After saving your changes, apply them with:

multitool plugins update

To automatically apply the configuration changes after saving and closing the file (install new plugins, update existing plugins, and prune removed plugins), use:

multitool plugins configure -a

Example configuration:

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

After saving, Multitool clones each configured repository into:

~/.multitool/plugins/

You can configure multiple repositories as long as each key is unique.

Installing

Install the example plugins:

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

multitool plugins update

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

multitool run examples -h

Updating

Install new plugins, update existing ones, and automatically install any Python dependencies declared in the Requires field of the plugin’s multitool-info.json file:

multitool plugins update

Update a specific plugin only:

multitool plugins update -n PLUGIN_NAME

The Requires field is where a plugin declares the Python packages it depends on. Any packages listed will be installed automatically when multitool plugins update is run. For example:

{
  "Homepage": "",
  "Requires": "click>=8.1.3 click-aliases>=1.0.1 click-option-group>=0.5.5 GitPython>=3.1.30",
  "Maintainer": "",
  "Description-en": ""
}

If one or more dependencies could not be installed automatically, multitool will report the failures and display the appropriate pip command to install the remaining packages manually. For example:

Updating plugins
----------------
Updating mdelotavo-multitool-plugins... Done
Updating test... Skipped Git pull (not a Git repository)

Checking Python package dependencies
------------------------------------
Checked GitPython (GitPython>=3.1.30)... 3.1.50 installed
Installing asdfasdfasdf... Failed
Checked click-aliases (click-aliases>=1.0.1)... 1.0.1 installed
Checked click-option-group (click-option-group>=0.5.5)... 0.5.5 installed
Checked click (click>=8.1.3)... 8.1.8 installed
Installing qwerqwerqwer>=8.1.3... Failed
Checked tabulate (tabulate)... 0.9.0 installed

The following dependencies could not be installed automatically:
  asdfasdfasdf
  qwerqwerqwer>=8.1.3

Try installing them manually:
  /usr/bin/python3 -m pip install asdfasdfasdf qwerqwerqwer>=8.1.3

You can also display a plugin’s declared dependencies at any time:

multitool plugins show --name PLUGIN_NAME --show-dependencies-only

Pruning

Remove repositories no longer listed in the configuration:

multitool plugins prune

Showing

Show configured repositories:

multitool plugins show

Or inspect a specific repository:

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