# How to Configure mise Plugins: Complete TOML and CLI Guide > Master mise plugin configuration with our TOML and CLI guide. Learn to declare plugins in mise.toml and reference tools efficiently. Enhance your workflow now. - Repository: [jdx/mise](https://github.com/jdx/mise) - Tags: how-to-guide - Published: 2026-08-09 --- **To configure mise plugins, declare them in the `[plugins]` table of your [`mise.toml`](https://github.com/jdx/mise/blob/main/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`](https://github.com/jdx/mise/blob/main/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`](https://github.com/jdx/mise/blob/main/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: ```toml [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`](https://github.com/jdx/mise/blob/main/mise.toml) location: ```toml [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: ```toml [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`](https://github.com/jdx/mise/blob/main/src/system/packages/plugin.rs) and documented in [`docs/plugin-usage.md`](https://github.com/jdx/mise/blob/main/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): ```toml [tools] "vfox-npm:prettier" = "latest" "vfox-npm:eslint" = "8.0.0" ``` **Tool plugin syntax** (single tool per plugin): ```toml [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 `_.` syntax, as implemented in the hooks defined in [`docs/plugins.md`](https://github.com/jdx/mise/blob/main/docs/plugins.md): ```toml [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`](https://github.com/jdx/mise/blob/main/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`](https://github.com/jdx/mise/blob/main/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`](https://github.com/jdx/mise/blob/main/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`](https://github.com/jdx/mise/blob/main/mise.toml) with a relative path such as `my-plugin = "./plugins/my-plugin"`. Relative paths resolve from the directory containing the [`mise.toml`](https://github.com/jdx/mise/blob/main/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`](https://github.com/jdx/mise/blob/main/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 `. Regular updates ensure you receive bug fixes and new tool versions supported by the plugin backends.