Create and run plugin-based command-line tools.

Quickstart

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/

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 -a

This opens your editor to modify the plugin configuration. Omit -a if you don’t want changes applied automatically.

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
pip3 install $(multitool plugins show -n mdelotavo-multitool-plugins --show-dependencies-only)

multitool run examples -h

Updating

Install new plugins and update existing ones:

multitool plugins update

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

If a plugin declares Python dependencies in multitool-info.json, install them with:

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]
mdelotavo-multitool-plugins = https://github.com/mdelotavo/multitool-plugins.git

should expose commands using a unique name such as:

mdelotavo-multitool-plugins

This reduces the likelihood of collisions when multiple repositories expose plugins with the same command name.

If duplicate command names are detected, Multitool will display an error prompting you to delete the detected conflicting plugin repositories and, if applicable, remove the corresponding remote sources from your plugin configuration.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.10.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for mdelotavo from gravatar.com mdelotavo

Credits

Author: Matthew Delotavo

License expression

MIT
View SPDX License List

Requires

Python >=3.7

Tags

cli tooling automation

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

multitool-0.7.2.tar.gz (13.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

multitool-0.7.2-py3-none-any.whl (13.3 kB view details)

Uploaded Python 3

File details

Details for the file multitool-0.7.2.tar.gz.

File metadata

  • Download URL: multitool-0.7.2.tar.gz
  • Upload date:
  • Size: 13.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.10.12

File hashes

Hashes for multitool-0.7.2.tar.gz
Algorithm Hash digest
SHA256 81d9ca86a94526cbd77406cf133206efa29f2ce80fd3eee5bbdf7f240b57ea58
MD5 725577aa31232285599584c278e82086
BLAKE2b-256 e326d6f9e8772859c1082b719a11f4d053748364f9f4293d7b66693b66b23a3d

See more details on using hashes here.

File details

Details for the file multitool-0.7.2-py3-none-any.whl.

File metadata

  • Download URL: multitool-0.7.2-py3-none-any.whl
  • Upload date:
  • Size: 13.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.10.12

File hashes

Hashes for multitool-0.7.2-py3-none-any.whl
Algorithm Hash digest
SHA256 474c2bdc7c98a6b3c315fd5724a810b939907df191853d91eb1bd801a75dddec
MD5 299f9e9fa51da16460b7ac1e806b393e
BLAKE2b-256 1d1cb9f37d84dda294f314799e87b2abc2c7fb1a8a38d3417a68cdd0237d2128

See more details on using hashes here.

Release history Release notifications | RSS feed

0.10.1

2 files

0.10.0

2 files

0.9.0

2 files

0.8.0

2 files

This release

0.7.2 This release

2 files

0.7.1

2 files

0.7.0

2 files

0.6.0

2 files

0.5.0

2 files

0.4.0

2 files

0.3.2

2 files

0.3.1

2 files

0.3.0

2 files

0.2.4

2 files

0.2.3

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page