How to Configure mise Plugins: Complete TOML and CLI Guide

To configure mise plugins, declare them in the [plugins] table of your mise.toml file with a name and source URL or path, then reference tools using the plugin:tool syntax in the [tools] section or environment variables via _.plugin_name in [env].

The jdx/mise repository supports a flexible plugin architecture that extends beyond the core runtime to manage custom tools, environment variables, and commands. When you configure mise plugins, you leverage the core implementation found in src/system/packages/plugin.rs, which handles backend trait resolution, path expansion, and hook execution for both local development and production workflows.

Declaring Plugins in mise.toml

Plugins are defined under the top-level [plugins] table in your configuration file. Each entry maps a plugin name to its source, which can be a remote Git repository, a local directory, or a downloadable archive.

According to docs/plugin-usage.md, path handling follows standard mise resolution rules: absolute paths, ~/ home directory expansion, and relative paths (./ or ../) are resolved relative to the configuration file containing the declaration.

Remote Git Repositories

Reference public or private Git repositories via HTTPS or SSH URLs:

[plugins]
vfox-npm = "https://github.com/jdx/vfox-npm"

Local Development Paths

For plugins under active development, use relative or absolute paths. Relative paths resolve from the mise.toml location:

[plugins]
my-plugin = "./plugins/my-plugin"
dev-tool = "~/projects/mise-plugins/dev-tool"

Archive Sources

You can also point to zip archives hosted on HTTPS endpoints:

[plugins]
tiny = "https://github.com/mise-plugins/mise-tiny/archive/refs/heads/main.zip"

Understanding Backend vs. Tool Plugins

The plugin system distinguishes between two architectural models, as defined in src/system/packages/plugin.rs and documented in docs/plugin-usage.md.

Backend Plugins

Backend plugins implement the modern trait system, specifically BackendListVersions, BackendInstall, and BackendExecEnv. These plugins manage multiple tools through a single installation using the plugin:tool syntax. This approach provides better performance and cross-platform support by handling version listing, installation, and environment execution within a unified backend.

Tool Plugins

Tool plugins follow the classic hook-based model where one plugin manages exactly one tool. Use this pattern when a tool requires custom installation logic, specific environment manipulation, or legacy compatibility that doesn't fit the backend trait architecture.

Referencing Plugin Tools in the Configuration

Once declared in [plugins], you consume the tools in your [tools] table. The syntax varies by plugin type:

Backend plugin syntax (multiple tools per plugin):

[tools]
"vfox-npm:prettier" = "latest"
"vfox-npm:eslint"   = "8.0.0"

Tool plugin syntax (single tool per plugin):

[tools]
my-tool = "1.2.3"

Mise resolves these references through the appropriate backend or hook system, then applies standard version-resolution logic to fetch and activate the specified versions.

Configuring Environment Plugins

Some plugins exclusively manage environment variables and PATH entries without installing binary tools. Configure these in the [env] section using the _.<plugin-name> syntax, as implemented in the hooks defined in docs/plugins.md:

[env]
_.my-env-plugin = { api_url = "https://api.example.com", debug = true }

The plugin implements MiseEnv and/or MisePath hooks, and mise injects the supplied key-value pairs into the child process environment at runtime.

Managing Plugins via the CLI

While TOML configuration handles declaration, the CLI provides lifecycle management commands:

• List installed plugins: mise plugins ls --urls displays all plugins with their source URLs
• Update a specific plugin: mise plugin update vfox-npm
• Update all plugins: mise plugin update --all
• Remove a plugin: mise plugin remove vfox-npm (also removes associated tools)
• Link a local plugin: mise plugin link my-plugin /path/to/dir creates a symbolic link for development

Security Best Practices for mise Plugins

Plugins execute arbitrary Lua code during both installation and runtime operations. As noted in docs/plugin-usage.md, observe these precautions:

• Source verification: Install only from trusted, audited repositories
• Code review: Examine plugin source code before adding to your configuration
• Version pinning: Pin specific plugin versions in mise.toml or lock them in mise.lock to prevent unexpected upgrades that could introduce breaking changes or malicious code

Summary

• Configure plugins in the [plugins] table of mise.toml by mapping names to Git URLs, local paths, or archives
• Use backend plugins for managing multiple tools with the plugin:tool syntax and trait-based implementation
• Use tool plugins for single tools requiring custom hook-based installation logic
• Configure environment-only plugins via [env] using the _.plugin_name syntax
• Manage plugin lifecycle (list, update, remove, link) through mise plugin CLI commands
• Security: Review plugin code before execution and pin versions to prevent automatic updates

Frequently Asked Questions

What is the difference between backend plugins and tool plugins in mise?

Backend plugins implement Rust traits including BackendListVersions, BackendInstall, and BackendExecEnv to manage multiple tools per plugin instance using the plugin:tool syntax. Tool plugins use a legacy hook-based architecture constrained to one tool per plugin, which is useful when you need custom installation logic or environment manipulation that doesn't conform to the backend trait system.

How do I reference a local plugin during development?

You have two options: Use mise plugin link my-plugin /absolute/path/to/dir to create a symbolic link to your development directory, or declare it in mise.toml with a relative path such as my-plugin = "./plugins/my-plugin". Relative paths resolve from the directory containing the mise.toml file, supporting ~/ expansion and ../ traversal.

Can mise plugins configure environment variables without installing binaries?

Yes. Environment plugins do not install binaries but instead inject variables into the process environment. Declare them in the [env] table using the syntax _.plugin-name = { key = "value" }. The plugin must implement the MiseEnv and/or MisePath hooks to handle the configuration, as documented in docs/plugins.md.

How do I update all mise plugins simultaneously?

Run mise plugin update --all to fetch the latest versions of all declared plugins. To update a specific plugin only, use mise plugin update <plugin-name>. Regular updates ensure you receive bug fixes and new tool versions supported by the plugin backends.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}