docs/plugins.md
Plugins add installation logic, environment directives, or bootstrap package managers to mise. Most tools can use a built-in backend directly, even when they have no registry shorthand. Start there before installing a plugin.
For release binaries, prefer packslip when the publisher provides signed manifests, then aqua, github, or gitlab. Use a plugin when your integration needs custom behavior those backends cannot provide.
Plugin code can read files, make requests, and run processes with your permissions. Lua's cross-platform runtime does not make a plugin an OS sandbox. Review the source and its updates; new asdf and vfox tool plugins are not accepted into the mise registry.
| Type | Use it for | Configuration | Author guide |
|---|---|---|---|
| Backend | Several versioned tools managed by one integration | [tools], my-backend:tool | Backend development |
| Tool | One versioned tool with download/install hooks | [tools], the installed plugin name | Tool development |
| Environment | Variables or PATH entries without a tool installation | [env], _.my-plugin | Environment development |
| Package | Host-managed packages for machine bootstrap | [bootstrap.packages] | Package development |
| asdf | An existing shell-based tool integration | [tools], an asdf backend | Legacy plugins |
Register a package manager in [bootstrap.plugins], or install it as package:<name>,
before declaring its requests in [bootstrap.packages]. See the
package plugin setup for a complete configuration.
The Lua runtime is available on Windows, macOS, and Linux. Each plugin must still support the selected platform and any external programs it invokes. asdf plugins use shell scripts and are disabled by default on Windows.
A backend plugin implements BackendListVersions, BackendInstall, and
BackendExecEnv. The prefix is the name under which you install the plugin:
# Replace this example repository and tool with your plugin's values.
mise plugin install my-backend https://github.com/your-org/my-backend
mise use my-backend:[email protected]
mise exec -- some-tool --version
See Using Plugins for installation, local development, and updates. The backend template provides a starting point.
A tool plugin manages one tool through hooks such as Available, PreInstall, and
EnvKeys. Use its installed name as the tool name:
mise plugin install my-tool https://github.com/your-org/my-tool-plugin
mise use [email protected]
mise exec -- my-tool --version
These repository and executable names are placeholders. Start with the tool template when writing your own.
An environment plugin implements MiseEnv and optionally MisePath. Install it before
using its directive:
mise plugin install my-env-plugin https://github.com/your-org/my-env-plugin
[env]
_.my-env-plugin = {
api_url = "https://api.example.com",
debug = true,
}
The fields are defined by the plugin. See environment plugin development for return values, cache behavior, and the environment template.
Package plugins implement a host package manager for bootstrap packages. They operate on batches of package requests and report installed state. Their installations belong to the host manager, unlike versioned tools stored under mise's data directory. See Package Plugin Development for the hook contract.
Using Plugins explains repository URLs, archive installation, local links, pinning plugin revisions, and diagnostics. List what is already installed with:
mise plugins ls --urls
mise can run existing asdf plugins with scripts such as bin/list-all, bin/install, and
bin/exec-env. Use the legacy guide to maintain one, or the
hook migration table to port it to Lua.
The mise-plugins organization hosts community plugins. Contact the maintainers through a GitHub discussion to discuss hosting. Hosting a plugin and adding a registry shorthand are separate decisions; see the publishing guide.
Plugins define custom options in their tool configuration. For example, a plugin that
supports a mirror option could accept:
[tools]
my-tool = {
version = "1.0.0",
mirror = "https://mirror.example.com",
}
For asdf and version-specific vfox lifecycle hooks, that option is exposed as
MISE_TOOL_OPTS__MIRROR. These variables are scoped to hook execution, not exported into
your shell. mise-managed fields such as depends, install_env, and os are handled by
mise instead. Backend plugin hooks receive typed options through ctx.options, including
arrays and nested tables; see backend context.
Repository values in [plugins] support templates. Prefer a normal SSH
or HTTPS repository URL and your Git credential setup for private repositories; embedding
credentials in a URL can expose them in configuration or logs.
[plugins]
my-backend = "[email protected]:your-org/my-backend.git"