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.1.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.1-py3-none-any.whl (13.3 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: multitool-0.7.1.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.1.tar.gz
Algorithm Hash digest
SHA256 47a8a08e452aef683cd160709b01487602c21312236ce218c5b49929bca25f9a
MD5 c1c9e0b8c6738e1dddc83d7f0e5fce69
BLAKE2b-256 5705dffa2cbf41eac733e9b509c37d5b7e1c5c718e982373eddd5851ad6b748e

See more details on using hashes here.

File details

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

File metadata

  • Download URL: multitool-0.7.1-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.1-py3-none-any.whl
Algorithm Hash digest
SHA256 469a61a9b7ef857d9ee410b70c4dbbb147aa1033fbf9401f3d26827d173a95fc
MD5 0f0095e6351d50fcace52c0eceb61a4e
BLAKE2b-256 1a6799cebeab66626f74e9493b71491039085bdc516f080168348437c0cf9a6b

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

0.7.2

2 files

This release

0.7.1 This release

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