---
url: /lang/dotnet.md
---
# .NET

The core .NET plugin installs .NET SDKs using Microsoft's official install script. All SDK versions are
installed side-by-side under a shared `DOTNET_ROOT` directory, matching .NET's native multi-version model.
This means `dotnet --list-sdks` will see every version you've installed through mise.

Unlike most tools, the SDKs don't live inside `~/.local/share/mise/installs` because they share a
common root. mise symlinks the install path to `DOTNET_ROOT` and sets environment variables so the
correct SDK is picked up.

::: info
This plugin manages the **.NET SDK** itself. To install .NET global tools (e.g., `dotnet-ef`),
use the [`dotnet` backend](/dev-tools/backends/dotnet.html) with `dotnet:ToolName` syntax.
:::

## Usage

Use the latest .NET SDK:

```sh
mise use -g dotnet@latest
dotnet --version
```

Use a specific version:

```sh
mise use -g dotnet@8.0.400
dotnet --version
```

Install multiple SDKs side-by-side for multi-targeting:

```sh
mise use dotnet@8
mise use dotnet@9
dotnet --list-sdks
```

## `global.json` support

mise recognizes `global.json` as an idiomatic version file. If your project contains a `global.json`
with an SDK version, mise will automatically use it:

```json
{
  "sdk": {
    "version": "8.0.100"
  }
}
```

Enable idiomatic version file support:

```sh
mise settings set idiomatic_version_file_enable_tools dotnet
```

## Isolated Mode

By default, all SDK versions share a single `DOTNET_ROOT` directory. This matches .NET's native
side-by-side model and means `dotnet --list-sdks` shows every installed version.

If you prefer the traditional mise approach where each version gets its own directory, enable
isolated mode:

```sh
mise settings set dotnet.isolated true
```

In isolated mode each SDK version is installed under `~/.local/share/mise/installs/dotnet/<version>/`,
just like most other mise-managed tools. `dotnet --list-sdks` will only report the currently active
version.

|                      | Shared (default)       | Isolated                     |
| -------------------- | ---------------------- | ---------------------------- |
| `dotnet --list-sdks` | All installed versions | Active version only          |
| Install location     | `DOTNET_ROOT`          | `installs/dotnet/<version>/` |
| Multi-targeting      | Works out of the box   | Requires switching versions  |

## Environment Variables

The plugin sets the following environment variables:

| Variable                      | Value                                                      |
| ----------------------------- | ---------------------------------------------------------- |
| `DOTNET_ROOT`                 | Shared SDK install directory (or install path if isolated) |
| `DOTNET_MULTILEVEL_LOOKUP`    | `0`                                                        |
| `DOTNET_CLI_TELEMETRY_OPTOUT` | Only set when `dotnet.cli_telemetry_optout` is configured  |

## Settings

---

---
url: /cli/activate.md
---
# `mise activate`

* **Usage**: `mise activate [FLAGS] [SHELL_TYPE]`
* **Source code**: [`src/cli/activate.rs`](https://github.com/jdx/mise/blob/main/src/cli/activate.rs)

Initializes mise in the current shell session

This should go into your shell's rc file or login shell.
Otherwise, it will only take effect in the current session.
(e.g. ~/.zshrc, ~/.zprofile, ~/.zshenv, ~/.bashrc, ~/.bash\_profile, ~/.profile, ~/.config/fish/config.fish, or $PROFILE for powershell)

Typically, this can be added with something like the following:

```
echo 'eval "$(mise activate zsh)"' >> ~/.zshrc
```

However, this requires that "mise" is in your PATH. If it is not, you need to
specify the full path like this:

```
echo 'eval "$(/path/to/mise activate zsh)"' >> ~/.zshrc
```

Customize status output with `status` settings.

## Arguments

### `[SHELL_TYPE]`

Shell type to generate the script for

**Choices:**

* `bash`
* `elvish`
* `fish`
* `nu`
* `xonsh`
* `zsh`
* `pwsh`

## Flags

### `-q --quiet`

Suppress non-error messages

### `--no-hook-env`

Do not automatically call hook-env

This can be helpful for debugging mise. If you run `eval "$(mise activate --no-hook-env)"`, then you can call `mise hook-env` manually which will output the env vars to stdout without actually modifying the environment. That way you can do things like `mise hook-env --trace` to get more information or just see the values that hook-env is outputting.

### `--shims`

Use shims instead of modifying PATH
Effectively the same as:

```
PATH="$HOME/.local/share/mise/shims:$PATH"
```

`mise activate --shims` does not support all the features of `mise activate`.
See <https://mise.jdx.dev/dev-tools/shims.html#shims-vs-path> for more information

Examples:

```
eval "$(mise activate bash)"
eval "$(mise activate zsh)"
mise activate fish | source
execx($(mise activate xonsh))
(&mise activate pwsh) | Out-String | Invoke-Expression
```

---

---
url: /cli/backends/ls.md
---
# `mise backends ls`

* **Usage**: `mise backends ls`
* **Aliases**: `list`
* **Source code**: [`src/cli/backends/ls.rs`](https://github.com/jdx/mise/blob/main/src/cli/backends/ls.rs)

List built-in backends

Examples:

```
$ mise backends ls
aqua
asdf
cargo
core
dotnet
gem
go
npm
pipx
spm
ubi
vfox
```

---

---
url: /cli/backends.md
---
# `mise backends`

* **Usage**: `mise backends <SUBCOMMAND>`
* **Aliases**: `b`
* **Source code**: [`src/cli/backends/mod.rs`](https://github.com/jdx/mise/blob/main/src/cli/backends/mod.rs)

Manage backends

## Subcommands

* [`mise backends ls`](/cli/backends/ls.md)

---

---
url: /cli/bin-paths.md
---
# `mise bin-paths`

* **Usage**: `mise bin-paths [TOOL@VERSION]…`
* **Source code**: [`src/cli/bin_paths.rs`](https://github.com/jdx/mise/blob/main/src/cli/bin_paths.rs)

List all the active runtime bin paths

## Arguments

### `[TOOL@VERSION]…`

Tool(s) to look up
e.g.: ruby@3

---

---
url: /cli/cache/clear.md
---
# `mise cache clear`

* **Usage**: `mise cache clear [PLUGIN]…`
* **Aliases**: `c`
* **Source code**: [`src/cli/cache/clear.rs`](https://github.com/jdx/mise/blob/main/src/cli/cache/clear.rs)

Deletes all cache files in mise

## Arguments

### `[PLUGIN]…`

Plugin(s) to clear cache for e.g.: node, python

---

---
url: /cli/cache/path.md
---
# `mise cache path`

* **Usage**: `mise cache path`
* **Aliases**: `dir`
* **Source code**: [`src/cli/cache/path.rs`](https://github.com/jdx/mise/blob/main/src/cli/cache/path.rs)

Show the cache directory path

---

---
url: /cli/cache/prune.md
---
# `mise cache prune`

* **Usage**: `mise cache prune [-v --verbose…] [--dry-run] [PLUGIN]…`
* **Aliases**: `p`
* **Source code**: [`src/cli/cache/prune.rs`](https://github.com/jdx/mise/blob/main/src/cli/cache/prune.rs)

Removes stale mise cache files

By default, this command will remove files that have not been accessed in 30 days.
Change this with the MISE\_CACHE\_PRUNE\_AGE environment variable.

## Arguments

### `[PLUGIN]…`

Plugin(s) to clear cache for e.g.: node, python

## Flags

### `-v --verbose…`

Show pruned files

### `--dry-run`

Just show what would be pruned

---

---
url: /cli/cache.md
---
# `mise cache`

* **Usage**: `mise cache <SUBCOMMAND>`
* **Source code**: [`src/cli/cache/mod.rs`](https://github.com/jdx/mise/blob/main/src/cli/cache/mod.rs)

Manage the mise cache

Run `mise cache` with no args to view the current cache directory.

## Subcommands

* [`mise cache clear [PLUGIN]…`](/cli/cache/clear.md)
* [`mise cache path`](/cli/cache/path.md)
* [`mise cache prune [-v --verbose…] [--dry-run] [PLUGIN]…`](/cli/cache/prune.md)

---

---
url: /cli/completion.md
---
# `mise completion`

* **Usage**: `mise completion [--include-bash-completion-lib] [SHELL]`
* **Source code**: [`src/cli/completion.rs`](https://github.com/jdx/mise/blob/main/src/cli/completion.rs)

Generate shell completions

## Arguments

### `[SHELL]`

Shell type to generate completions for

**Choices:**

* `bash`
* `fish`
* `powershell`
* `zsh`

## Flags

### `--include-bash-completion-lib`

Include the bash completion library in the bash completion script

This is required for completions to work in bash, but it is not included by default
you may source it separately or enable this flag to enable it in the script.

Examples:

```
mise completion bash --include-bash-completion-lib > ~/.local/share/bash-completion/completions/mise
mise completion zsh  > /usr/local/share/zsh/site-functions/_mise
mise completion fish > ~/.config/fish/completions/mise.fish
mise completion powershell >> $PROFILE
```

---

---
url: /cli/config/get.md
---
# `mise config get`

* **Usage**: `mise config get [-f --file <FILE>] [KEY]`
* **Source code**: [`src/cli/config/get.rs`](https://github.com/jdx/mise/blob/main/src/cli/config/get.rs)

Display the value of a setting in a mise.toml file

## Arguments

### `[KEY]`

The path of the config to display

## Flags

### `-f --file <FILE>`

The path to the mise.toml file to edit

If not provided, the nearest mise.toml file will be used

Examples:

```
$ mise toml get tools.python
3.12
```

---

---
url: /cli/config/ls.md
---
# `mise config ls`

* **Usage**: `mise config ls [FLAGS]`
* **Aliases**: `list`
* **Source code**: [`src/cli/config/ls.rs`](https://github.com/jdx/mise/blob/main/src/cli/config/ls.rs)

List config files currently in use

## Flags

### `-J --json`

Output in JSON format

### `--no-header`

Do not print table header

### `--tracked-configs`

List all tracked config files

Examples:

```
$ mise config ls
Path                        Tools
~/.config/mise/config.toml  pitchfork
~/src/mise/mise.toml        actionlint, bun, cargo-binstall, cargo:cargo-edit, cargo:cargo-insta
```

---

---
url: /cli/config/set.md
---
# `mise config set`

* **Usage**: `mise config set [-f --file <FILE>] [-t --type <TYPE>] <KEY> [VALUE]`
* **Source code**: [`src/cli/config/set.rs`](https://github.com/jdx/mise/blob/main/src/cli/config/set.rs)

Set the value of a setting in a mise.toml file

## Arguments

### `<KEY>`

The path of the config to display

### `[VALUE]`

The value to set the key to (optional if provided as KEY=VALUE)

## Flags

### `-f --file <FILE>`

The path to the mise.toml file to edit

If not provided, the nearest mise.toml file will be used

### `-t --type <TYPE>`

**Choices:**

* `infer`
* `string`
* `integer`
* `float`
* `bool`
* `list`
* `set`

**Default:** `infer`

Examples:

```
$ mise config set tools.python 3.12
$ mise config set settings.always_keep_download true
$ mise config set env.TEST_ENV_VAR ABC
$ mise config set settings.disable_tools --type list node,rust

# Type for `settings` is inferred
$ mise config set settings.jobs 4
```

---

---
url: /cli/config.md
---
# `mise config`

* **Usage**: `mise config [FLAGS] <SUBCOMMAND>`
* **Aliases**: `cfg`
* **Source code**: [`src/cli/config/mod.rs`](https://github.com/jdx/mise/blob/main/src/cli/config/mod.rs)

Manage config files

## Flags

### `-J --json`

Output in JSON format

### `--no-header`

Do not print table header

### `--tracked-configs`

List all tracked config files

## Subcommands

* [`mise config get [-f --file <FILE>] [KEY]`](/cli/config/get.md)
* [`mise config ls [FLAGS]`](/cli/config/ls.md)
* [`mise config set [-f --file <FILE>] [-t --type <TYPE>] <KEY> [VALUE]`](/cli/config/set.md)

Examples:

```
$ mise config ls
Path                        Tools
~/.config/mise/config.toml  pitchfork
~/src/mise/mise.toml        actionlint, bun, cargo-binstall, cargo:cargo-edit, cargo:cargo-insta
```

---

---
url: /cli/deactivate.md
---
# `mise deactivate`

* **Usage**: `mise deactivate`
* **Source code**: [`src/cli/deactivate.rs`](https://github.com/jdx/mise/blob/main/src/cli/deactivate.rs)

Disable mise for current shell session

This can be used to temporarily disable mise in a shell session.

Examples:

```
mise deactivate
```

---

---
url: /cli/doctor/path.md
---
# `mise doctor path`

* **Usage**: `mise doctor path [-f --full]`
* **Source code**: [`src/cli/doctor/path.rs`](https://github.com/jdx/mise/blob/main/src/cli/doctor/path.rs)

Print the current PATH entries mise is providing

## Flags

### `-f --full`

Print all entries including those not provided by mise

Examples:

```
Get the current PATH entries mise is providing
$ mise doctor path
/home/user/.local/share/mise/installs/node/24.0.0/bin
/home/user/.local/share/mise/installs/rust/1.90.0/bin
/home/user/.local/share/mise/installs/python/3.10.0/bin
```

---

---
url: /cli/doctor.md
---
# `mise doctor`

* **Usage**: `mise doctor [-J --json] <SUBCOMMAND>`
* **Aliases**: `dr`
* **Source code**: [`src/cli/doctor/mod.rs`](https://github.com/jdx/mise/blob/main/src/cli/doctor/mod.rs)

Check mise installation for possible problems

## Flags

### `-J --json`

## Subcommands

* [`mise doctor path [-f --full]`](/cli/doctor/path.md)

Examples:

```
$ mise doctor
[WARN] plugin node is not installed
```

---

---
url: /cli/edit.md
---
# `mise edit`

* **Usage**: `mise edit [-n --dry-run] [-t --tool-versions <TOOL_VERSIONS>] [PATH]`
* **Source code**: [`src/cli/edit.rs`](https://github.com/jdx/mise/blob/main/src/cli/edit.rs)

Edit mise.toml interactively

## Arguments

### `[PATH]`

Path to the config file to create

## Flags

### `-n --dry-run`

Show what would be generated without writing to file

### `-t --tool-versions <TOOL_VERSIONS>`

Path to a .tool-versions file to import tools from

Examples:

```
mise edit             # edit mise.toml interactively
mise edit .mise.toml  # edit a specific file
mise edit -y          # skip interactive editor
mise edit -n          # preview without writing
```

---

---
url: /cli/en.md
---
# `mise en`

* **Usage**: `mise en [-s --shell <SHELL>] [DIR]`
* **Source code**: [`src/cli/en.rs`](https://github.com/jdx/mise/blob/main/src/cli/en.rs)

Starts a new shell with the mise environment built from the current configuration

This is an alternative to `mise activate` that allows you to explicitly start a mise session.
It will have the tools and environment variables in the configs loaded.
Note that changing directories will not update the mise environment.

## Arguments

### `[DIR]`

Directory to start the shell in

**Default:** `.`

## Flags

### `-s --shell <SHELL>`

Shell to start

Defaults to $SHELL

Examples:

```
$ mise en .
$ node -v
v20.0.0

Skip loading bashrc:
$ mise en -s "bash --norc"

Skip loading zshrc:
$ mise en -s "zsh -f"
```

---

---
url: /cli/env.md
---
# `mise env`

* **Usage**: `mise env [FLAGS] [TOOL@VERSION]…`
* **Aliases**: `e`
* **Source code**: [`src/cli/env.rs`](https://github.com/jdx/mise/blob/main/src/cli/env.rs)

Exports env vars to activate mise a single time

Use this if you don't want to permanently install mise. It's not necessary to
use this if you have `mise activate` in your shell rc file.

## Arguments

### `[TOOL@VERSION]…`

Tool(s) to use

## Flags

### `-D --dotenv`

Output in dotenv format

### `-J --json`

Output in JSON format

### `-s --shell <SHELL>`

Shell type to generate environment variables for

**Choices:**

* `bash`
* `elvish`
* `fish`
* `nu`
* `xonsh`
* `zsh`
* `pwsh`

### `--json-extended`

Output in JSON format with additional information (source, tool)

### `--redacted`

Only show redacted environment variables

### `--values`

Only show values of environment variables

Examples:

```
eval "$(mise env -s bash)"
eval "$(mise env -s zsh)"
mise env -s fish | source
execx($(mise env -s xonsh))
```

---

---
url: /cli/exec.md
---
# `mise exec`

* **Usage**: `mise exec [FLAGS] [TOOL@VERSION]… [-- COMMAND]…`
* **Aliases**: `x`
* **Source code**: [`src/cli/exec.rs`](https://github.com/jdx/mise/blob/main/src/cli/exec.rs)

Execute a command with tool(s) set

use this to avoid modifying the shell session or running ad-hoc commands with mise tools set.

Tools will be loaded from mise.toml, though they can be overridden with \<RUNTIME> args
Note that only the plugin specified will be overridden, so if a `mise.toml` file
includes "node 20" but you run `mise exec python@3.11`; it will still load node@20.

The "--" separates runtimes from the commands to pass along to the subprocess.

## Arguments

### `[TOOL@VERSION]…`

Tool(s) to start e.g.: node@20 python@3.10

### `[-- COMMAND]…`

Command string to execute (same as --command)

## Flags

### `-c --command <C>`

Command string to execute

### `-j --jobs <JOBS>`

Number of jobs to run in parallel
\[default: 4]

### `--fresh-env`

Bypass the environment cache and recompute the environment

### `--no-prepare`

Skip automatic dependency preparation

### `--raw`

Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1

Examples:

```
$ mise exec node@20 -- node ./app.js  # launch app.js using node-20.x
$ mise x node@20 -- node ./app.js     # shorter alias

# Specify command as a string:
$ mise exec node@20 python@3.11 --command "node -v && python -V"

# Run a command in a different directory:
$ mise x -C /path/to/project node@20 -- node ./app.js
```

---

---
url: /cli/fmt.md
---
# `mise fmt`

* **Usage**: `mise fmt [FLAGS]`
* **Source code**: [`src/cli/fmt.rs`](https://github.com/jdx/mise/blob/main/src/cli/fmt.rs)

Formats mise.toml

Sorts keys and cleans up whitespace in mise.toml

## Flags

### `-a --all`

Format all files from the current directory

### `-c --check`

Check if the configs are formatted, no formatting is done

### `-s --stdin`

Read config from stdin and write its formatted version into stdout

Examples:

```
mise fmt
```

---

---
url: /cli/generate/bootstrap.md
---
# `mise generate bootstrap`

* **Usage**: `mise generate bootstrap [FLAGS]`
* **Source code**: [`src/cli/generate/bootstrap.rs`](https://github.com/jdx/mise/blob/main/src/cli/generate/bootstrap.rs)

Generate a script to download+execute mise

This is designed to be used in a project where contributors may not have mise installed.

## Flags

### `-l --localize`

Sandboxes mise internal directories like MISE\_DATA\_DIR and MISE\_CACHE\_DIR into a `.mise` directory in the project

This is necessary if users may use a different version of mise outside the project.

### `-V --version <VERSION>`

Specify mise version to fetch

### `-w --write <WRITE>`

instead of outputting the script to stdout, write to a file and make it executable

### `--localized-dir <LOCALIZED_DIR>`

Directory to put localized data into

**Default:** `.mise`

Examples:

```
mise generate bootstrap >./bin/mise
chmod +x ./bin/mise
./bin/mise install – automatically downloads mise to .mise if not already installed
```

---

---
url: /cli/generate/config.md
---
# `mise generate config`

* **Usage**: `mise generate config [-n --dry-run] [-t --tool-versions <TOOL_VERSIONS>] [PATH]`
* **Source code**: [`src/cli/generate/config.rs`](https://github.com/jdx/mise/blob/main/src/cli/generate/config.rs)

Generate a mise.toml file

## Arguments

### `[PATH]`

Path to the config file to create

## Flags

### `-n --dry-run`

Show what would be generated without writing to file

### `-t --tool-versions <TOOL_VERSIONS>`

Path to a .tool-versions file to import tools from

Examples:

```
mise edit             # edit mise.toml interactively
mise edit .mise.toml  # edit a specific file
mise edit -y          # skip interactive editor
mise edit -n          # preview without writing
```

---

---
url: /cli/generate/devcontainer.md
---
# `mise generate devcontainer`

* **Usage**: `mise generate devcontainer [FLAGS]`
* **Source code**: [`src/cli/generate/devcontainer.rs`](https://github.com/jdx/mise/blob/main/src/cli/generate/devcontainer.rs)

Generate a devcontainer to execute mise

## Flags

### `-i --image <IMAGE>`

The image to use for the devcontainer

### `-m --mount-mise-data`

Bind the mise-data-volume to the devcontainer

### `-n --name <NAME>`

The name of the devcontainer

### `-w --write`

write to .devcontainer/devcontainer.json

Examples:

```
mise generate devcontainer
```

---

---
url: /cli/generate/git-pre-commit.md
---
# `mise generate git-pre-commit`

* **Usage**: `mise generate git-pre-commit [FLAGS]`
* **Aliases**: `pre-commit`
* **Source code**: [`src/cli/generate/git_pre_commit.rs`](https://github.com/jdx/mise/blob/main/src/cli/generate/git_pre_commit.rs)

Generate a git pre-commit hook

This command generates a git pre-commit hook that runs a mise task like `mise run pre-commit`
when you commit changes to your repository.

Staged files are passed to the task as `STAGED`.

For more advanced pre-commit functionality, see mise's sister project: <https://hk.jdx.dev/>

## Flags

### `-t --task <TASK>`

The task to run when the pre-commit hook is triggered

**Default:** `pre-commit`

### `-w --write`

write to .git/hooks/pre-commit and make it executable

### `--hook <HOOK>`

Which hook to generate (saves to .git/hooks/$hook)

**Default:** `pre-commit`

Examples:

```
mise generate git-pre-commit --write --task=pre-commit
git commit -m "feat: add new feature" # runs `mise run pre-commit`
```

---

---
url: /cli/generate/github-action.md
---
# `mise generate github-action`

* **Usage**: `mise generate github-action [FLAGS]`
* **Source code**: [`src/cli/generate/github_action.rs`](https://github.com/jdx/mise/blob/main/src/cli/generate/github_action.rs)

Generate a GitHub Action workflow file

This command generates a GitHub Action workflow file that runs a mise task like `mise run ci`
when you push changes to your repository.

## Flags

### `-t --task <TASK>`

The task to run when the workflow is triggered

**Default:** `ci`

### `-w --write`

write to .github/workflows/$name.yml

### `--name <NAME>`

the name of the workflow to generate

**Default:** `ci`

Examples:

```
mise generate github-action --write --task=ci
git commit -m "feat: add new feature"
git push # runs `mise run ci` on GitHub
```

---

---
url: /cli/generate/task-docs.md
---
# `mise generate task-docs`

* **Usage**: `mise generate task-docs [FLAGS]`
* **Source code**: [`src/cli/generate/task_docs.rs`](https://github.com/jdx/mise/blob/main/src/cli/generate/task_docs.rs)

Generate documentation for tasks in a project

## Flags

### `-i --inject`

inserts the documentation into an existing file

This will look for a special comment, `<!-- mise-tasks -->`, and replace it with the generated documentation.
It will replace everything between the comment and the next comment, `<!-- /mise-tasks -->` so it can be
run multiple times on the same file to update the documentation.

### `-I --index`

write only an index of tasks, intended for use with `--multi`

### `-m --multi`

render each task as a separate document, requires `--output` to be a directory

### `-o --output <OUTPUT>`

writes the generated docs to a file/directory

### `-r --root <ROOT>`

root directory to search for tasks

### `-s --style <STYLE>`

**Choices:**

* `simple`
* `detailed`

**Default:** `simple`

Examples:

```
mise generate task-docs
```

---

---
url: /cli/generate/task-stubs.md
---
# `mise generate task-stubs`

* **Usage**: `mise generate task-stubs [-d --dir <DIR>] [-m --mise-bin <MISE_BIN>]`
* **Source code**: [`src/cli/generate/task_stubs.rs`](https://github.com/jdx/mise/blob/main/src/cli/generate/task_stubs.rs)

Generates shims to run mise tasks

By default, this will build shims like ./bin/\<task>. These can be paired with `mise generate bootstrap`
so contributors to a project can execute mise tasks without installing mise into their system.

## Flags

### `-d --dir <DIR>`

Directory to create task stubs inside of

**Default:** `bin`

### `-m --mise-bin <MISE_BIN>`

Path to a mise bin to use when running the task stub.

Use `--mise-bin=./bin/mise` to use a mise bin generated from `mise generate bootstrap`

**Default:** `mise`

Examples:

```
$ mise tasks add test -- echo 'running tests'
$ mise generate task-stubs
$ ./bin/test
running tests
```

---

---
url: /cli/generate/tool-stub.md
---
# `mise generate tool-stub`

* **Usage**: `mise generate tool-stub [FLAGS] <OUTPUT>`
* **Source code**: [`src/cli/generate/tool_stub.rs`](https://github.com/jdx/mise/blob/main/src/cli/generate/tool_stub.rs)

Generate a tool stub for HTTP-based tools

This command generates tool stubs that can automatically download and execute
tools from HTTP URLs. It can detect checksums, file sizes, and binary paths
automatically by downloading and analyzing the tool.

When generating stubs with platform-specific URLs, the command will append new
platforms to existing stub files rather than overwriting them. This allows you
to incrementally build cross-platform tool stubs.

## Arguments

### `<OUTPUT>`

Output file path for the tool stub

## Flags

### `-b --bin <BIN>`

Binary path within the extracted archive

If not specified and the archive is downloaded, will auto-detect the most likely binary

### `--bootstrap`

Wrap stub in a bootstrap script that installs mise if not already present

When enabled, generates a bash script that:

1. Checks if mise is installed at the expected path
2. If not, downloads and installs mise using the embedded installer
3. Executes the tool stub using mise

### `--bootstrap-version <BOOTSTRAP_VERSION>`

Specify mise version for the bootstrap script

By default, uses the latest version from the install script.
Use this to pin to a specific version (e.g., "2025.1.0").

### `--fetch`

Fetch checksums and sizes for an existing tool stub file

This reads an existing stub file and fills in any missing checksum/size fields by downloading the files. URLs must already be present in the stub.

### `--http <HTTP>`

HTTP backend type to use

**Default:** `http`

### `--lock`

Resolve and embed lockfile data (exact version + platform URLs/checksums) into an existing stub file for reproducible installs without runtime API calls

### `--platform-bin… <PLATFORM_BIN>`

Platform-specific binary paths in the format platform:path

Examples: --platform-bin windows-x64:tool.exe --platform-bin linux-x64:bin/tool

### `--platform-url… <PLATFORM_URL>`

Platform-specific URLs in the format platform:url or just url (auto-detect platform)

When the output file already exists, new platforms will be appended to the existing platforms table. Existing platform URLs will be updated if specified again.

If only a URL is provided (without platform:), the platform will be automatically detected from the URL filename.

Examples: --platform-url linux-x64:https://... --platform-url <https://nodejs.org/dist/v22.17.1/node-v22.17.1-darwin-arm64.tar.gz>

### `--skip-download`

Skip downloading for checksum and binary path detection (faster but less informative)

### `-u --url <URL>`

URL for downloading the tool

Example: <https://github.com/owner/repo/releases/download/v2.0.0/tool-linux-x64.tar.gz>

### `--version <VERSION>`

Version of the tool

**Default:** `latest`

Examples:

```
Generate a tool stub for a single URL:
$ mise generate tool-stub ./bin/gh --url "https://github.com/cli/cli/releases/download/v2.336.0/gh_2.336.0_linux_amd64.tar.gz"

Generate a tool stub with platform-specific URLs:
$ mise generate tool-stub ./bin/rg \
    --platform-url linux-x64:https://github.com/BurntSushi/ripgrep/releases/download/14.0.3/ripgrep-14.0.3-x86_64-unknown-linux-musl.tar.gz \
    --platform-url darwin-arm64:https://github.com/BurntSushi/ripgrep/releases/download/14.0.3/ripgrep-14.0.3-aarch64-apple-darwin.tar.gz

Append additional platforms to an existing stub:
$ mise generate tool-stub ./bin/rg \
    --platform-url linux-x64:https://example.com/rg-linux.tar.gz
$ mise generate tool-stub ./bin/rg \
    --platform-url darwin-arm64:https://example.com/rg-darwin.tar.gz
# The stub now contains both platforms

Use auto-detection for platform from URL:
$ mise generate tool-stub ./bin/node \
    --platform-url https://nodejs.org/dist/v22.17.1/node-v22.17.1-darwin-arm64.tar.gz
# Platform 'macos-arm64' will be auto-detected from the URL

Generate with platform-specific binary paths:
$ mise generate tool-stub ./bin/tool \
    --platform-url linux-x64:https://example.com/tool-linux.tar.gz \
    --platform-url windows-x64:https://example.com/tool-windows.zip \
    --platform-bin windows-x64:tool.exe

Generate without downloading (faster):
$ mise generate tool-stub ./bin/tool --url "https://example.com/tool.tar.gz" --skip-download

Fetch checksums for an existing stub:
$ mise generate tool-stub ./bin/jq --fetch
# This will read the existing stub and download files to fill in any missing checksums/sizes

Generate a bootstrap stub that installs mise if needed:
$ mise generate tool-stub ./bin/tool --url "https://example.com/tool.tar.gz" --bootstrap
# The stub will check for mise and install it automatically before running the tool

Generate a bootstrap stub with a pinned mise version:
$ mise generate tool-stub ./bin/tool --url "https://example.com/tool.tar.gz" --bootstrap --bootstrap-version 2025.1.0

Lock an existing tool stub with pinned version and platform URLs/checksums:
$ mise generate tool-stub ./bin/node --lock

Bump the version in a locked stub:
$ mise generate tool-stub ./bin/node --lock --version 22
# Resolves the latest node 22.x, pins it, and updates platform URLs/checksums
```

---

---
url: /cli/generate.md
---
# `mise generate`

* **Usage**: `mise generate <SUBCOMMAND>`
* **Aliases**: `gen`
* **Source code**: [`src/cli/generate/mod.rs`](https://github.com/jdx/mise/blob/main/src/cli/generate/mod.rs)

Generate files for various tools/services

## Subcommands

* [`mise generate bootstrap [FLAGS]`](/cli/generate/bootstrap.md)
* [`mise generate config [-n --dry-run] [-t --tool-versions <TOOL_VERSIONS>] [PATH]`](/cli/generate/config.md)
* [`mise generate devcontainer [FLAGS]`](/cli/generate/devcontainer.md)
* [`mise generate git-pre-commit [FLAGS]`](/cli/generate/git-pre-commit.md)
* [`mise generate github-action [FLAGS]`](/cli/generate/github-action.md)
* [`mise generate task-docs [FLAGS]`](/cli/generate/task-docs.md)
* [`mise generate task-stubs [-d --dir <DIR>] [-m --mise-bin <MISE_BIN>]`](/cli/generate/task-stubs.md)
* [`mise generate tool-stub [FLAGS] <OUTPUT>`](/cli/generate/tool-stub.md)

---

---
url: /cli/implode.md
---
# `mise implode`

* **Usage**: `mise implode [-n --dry-run] [--config]`
* **Source code**: [`src/cli/implode.rs`](https://github.com/jdx/mise/blob/main/src/cli/implode.rs)

Removes mise CLI and all related data

Skips config directory by default.

## Flags

### `-n --dry-run`

List directories that would be removed without actually removing them

### `--config`

Also remove config directory

---

---
url: /cli/install-into.md
---
# `mise install-into`

* **Usage**: `mise install-into <TOOL@VERSION> <PATH>`
* **Source code**: [`src/cli/install_into.rs`](https://github.com/jdx/mise/blob/main/src/cli/install_into.rs)

Install a tool version to a specific path

Used for building a tool to a directory for use outside of mise

## Arguments

### `<TOOL@VERSION>`

Tool to install e.g.: node@20

### `<PATH>`

Path to install the tool into

Examples:

```
# install node@20.0.0 into ./mynode
$ mise install-into node@20.0.0 ./mynode && ./mynode/bin/node -v
20.0.0
```

---

---
url: /cli/install.md
---
# `mise install`

* **Usage**: `mise install [FLAGS] [TOOL@VERSION]…`
* **Aliases**: `i`
* **Source code**: [`src/cli/install.rs`](https://github.com/jdx/mise/blob/main/src/cli/install.rs)

Install a tool version

Installs a tool version to `~/.local/share/mise/installs/<PLUGIN>/<VERSION>`
Installing alone will not activate the tools so they won't be in PATH.
To install and/or activate in one command, use `mise use` which will create a `mise.toml` file
in the current directory to activate this tool when inside the directory.
Alternatively, run `mise exec <TOOL>@<VERSION> -- <COMMAND>` to execute a tool without creating config files.

Tools will be installed in parallel. To disable, set `--jobs=1` or `MISE_JOBS=1`

## Arguments

### `[TOOL@VERSION]…`

Tool(s) to install e.g.: node@20

## Flags

### `-f --force`

Force reinstall even if already installed

### `-j --jobs <JOBS>`

Number of jobs to run in parallel
\[default: 4]

### `-n --dry-run`

Show what would be installed without actually installing

### `-v --verbose…`

Show installation output

This argument will print plugin output such as download, configuration, and compilation output.

### `--before <BEFORE>`

Only install versions released before this date

Supports absolute dates like "2024-06-01" and relative durations like "90d" or "1y".

### `--dry-run-code`

Like --dry-run but exits with code 1 if there are tools to install

This is useful for scripts to check if tools need to be installed.

### `--raw`

Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1

Examples:

```
mise install node@20.0.0  # install specific node version
mise install node@20      # install fuzzy node version
mise install node         # install version specified in mise.toml
mise install              # installs everything specified in mise.toml
```

---

---
url: /cli/latest.md
---
# `mise latest`

* **Usage**: `mise latest [-i --installed] <TOOL@VERSION>`
* **Source code**: [`src/cli/latest.rs`](https://github.com/jdx/mise/blob/main/src/cli/latest.rs)

Gets the latest available version for a plugin

Supports prefixes such as `node@20` to get the latest version of node 20.

## Arguments

### `<TOOL@VERSION>`

Tool to get the latest version of

## Flags

### `-i --installed`

Show latest installed instead of available version

Examples:

```
$ mise latest node@20  # get the latest version of node 20
20.0.0

$ mise latest node     # get the latest stable version of node
20.0.0
```

---

---
url: /cli/link.md
---
# `mise link`

* **Usage**: `mise link [-f --force] <TOOL@VERSION> <PATH>`
* **Aliases**: `ln`
* **Source code**: [`src/cli/link.rs`](https://github.com/jdx/mise/blob/main/src/cli/link.rs)

Symlinks a tool version into mise

Use this for adding installs either custom compiled outside mise or built with a different tool.

## Arguments

### `<TOOL@VERSION>`

Tool name and version to create a symlink for

### `<PATH>`

The local path to the tool version
e.g.: ~/.nvm/versions/node/v20.0.0

## Flags

### `-f --force`

Overwrite an existing tool version if it exists

Examples:

```
# build node-20.0.0 with node-build and link it into mise
$ node-build 20.0.0 ~/.nodes/20.0.0
$ mise link node@20.0.0 ~/.nodes/20.0.0

# have mise use the node version provided by Homebrew
$ brew install node
$ mise link node@brew $(brew --prefix node)
$ mise use node@brew
```

---

---
url: /cli/lock.md
---
# `mise lock`

* **Usage**: `mise lock [FLAGS] [TOOL]…`
* **Source code**: [`src/cli/lock.rs`](https://github.com/jdx/mise/blob/main/src/cli/lock.rs)

Update lockfile checksums and URLs for all specified platforms

Updates checksums and download URLs for all platforms already specified in the lockfile.
If no lockfile exists, shows what would be created based on the current configuration.
This allows you to refresh lockfile data for platforms other than the one you're currently on.
Operates on the lockfile in the current config root. Use TOOL arguments to target specific tools.

## Arguments

### `[TOOL]…`

Tool(s) to update in lockfile
e.g.: node python
If not specified, all tools in lockfile will be updated

## Flags

### `-j --jobs <JOBS>`

Number of jobs to run in parallel

### `-n --dry-run`

Show what would be updated without making changes

### `-p --platform… <PLATFORM>`

Comma-separated list of platforms to target
e.g.: linux-x64,macos-arm64,windows-x64
If not specified, all platforms already in lockfile will be updated

### `--local`

Update mise.local.lock instead of mise.lock
Use for tools defined in .local.toml configs

Examples:

```
mise lock                       # update lockfile for all common platforms
mise lock node python           # update only node and python
mise lock --platform linux-x64  # update only linux-x64 platform
mise lock --dry-run             # show what would be updated
mise lock --local               # update mise.local.lock for local configs
```

---

---
url: /cli/ls-remote.md
---
# `mise ls-remote`

* **Usage**: `mise ls-remote [--all] [-J --json] [TOOL@VERSION] [PREFIX]`
* **Source code**: [`src/cli/ls_remote.rs`](https://github.com/jdx/mise/blob/main/src/cli/ls_remote.rs)

List runtime versions available for install.

Note that the results may be cached, run `mise cache clean` to clear the cache and get fresh results.

## Arguments

### `[TOOL@VERSION]`

Tool to get versions for

### `[PREFIX]`

The version prefix to use when querying the latest version
same as the first argument after the "@"

## Flags

### `--all`

Show all installed plugins and versions

### `-J --json`

Output in JSON format (includes version metadata like created\_at timestamps when available)

Examples:

```
$ mise ls-remote node
18.0.0
20.0.0

$ mise ls-remote node@20
20.0.0
20.1.0

$ mise ls-remote node 20
20.0.0
20.1.0

$ mise ls-remote github:cli/cli --json
[{"version":"2.62.0","created_at":"2024-11-14T15:40:35Z"},{"version":"2.61.0","created_at":"2024-10-23T19:22:15Z"}]
```

---

---
url: /cli/ls.md
---
# `mise ls`

* **Usage**: `mise ls [FLAGS] [INSTALLED_TOOL]…`
* **Aliases**: `list`
* **Source code**: [`src/cli/ls.rs`](https://github.com/jdx/mise/blob/main/src/cli/ls.rs)

List installed and active tool versions

This command lists tools that mise "knows about".
These may be tools that are currently installed, or those
that are in a config file (active) but may or may not be installed.

It's a useful command to get the current state of your tools.

## Arguments

### `[INSTALLED_TOOL]…`

Only show tool versions from \[TOOL]

## Flags

### `-c --current`

Only show tool versions currently specified in a mise.toml

### `-g --global`

Only show tool versions currently specified in the global mise.toml

### `-i --installed`

Only show tool versions that are installed (Hides tools defined in mise.toml but not installed)

### `-J --json`

Output in JSON format

### `-l --local`

Only show tool versions currently specified in the local mise.toml

### `-m --missing`

Display missing tool versions

### `--all-sources`

Display all tracked config sources for tools

### `--no-header`

Don't display headers

### `--outdated`

Display whether a version is outdated

### `--prefix <PREFIX>`

Display versions matching this prefix

### `--prunable`

List only tools that can be pruned with `mise prune`

Examples:

```
$ mise ls
node    20.0.0 ~/src/myapp/.tool-versions latest
python  3.11.0 ~/.tool-versions           3.10
python  3.10.0

$ mise ls --current
node    20.0.0 ~/src/myapp/.tool-versions 20
python  3.11.0 ~/.tool-versions           3.11.0

$ mise ls --json
{
  "node": [
    {
      "version": "20.0.0",
      "install_path": "/Users/jdx/.mise/installs/node/20.0.0",
      "source": {
        "type": "mise.toml",
        "path": "/Users/jdx/mise.toml"
      }
    }
  ],
  "python": [...]
}

$ mise ls --all-sources
node    20.0.0  ~/src/myapp/mise.toml  20
                ~/.config/mise/config.toml  latest
```

---

---
url: /cli/mcp.md
---
# `mise mcp`

* **Usage**: `mise mcp`
* **Source code**: [`src/cli/mcp.rs`](https://github.com/jdx/mise/blob/main/src/cli/mcp.rs)

\[experimental] Run Model Context Protocol (MCP) server

This command starts an MCP server that exposes mise functionality
to AI assistants over stdin/stdout using JSON-RPC protocol.

The MCP server provides access to:

* Installed and available tools
* Task definitions and execution
* Environment variables
* Configuration information
* Task execution via the run\_task tool

Resources available:

* mise://tools - List all tools (use ?include\_inactive=true to include inactive tools)
* mise://tasks - List all tasks with their configurations
* mise://env - List all environment variables
* mise://config - Show configuration files and project root

Tools available:

* install\_tool - Install a tool with an optional version (not yet implemented)
* run\_task - Execute a mise task with optional arguments

Note: This is primarily intended for integration with AI assistants like Claude,
Cursor, or other tools that support the Model Context Protocol.

Examples:

```
# Start the MCP server (typically used by AI assistant tools)
$ mise mcp

# Example integration with Claude Desktop (add to claude_desktop_config.json):
{
  "mcpServers": {
    "mise": {
      "command": "mise",
      "args": ["mcp"],
      "env": {
        "MISE_EXPERIMENTAL": "1"
      }
    }
  }
}

# Interactive testing with JSON-RPC commands:
$ echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | mise mcp

# Resources you can query:
- mise://tools - List active tools
- mise://tools?include_inactive=true - List all installed tools
- mise://tasks - List all tasks
- mise://env - List environment variables
- mise://config - Show configuration info

# Tools available:
- install_tool - Install a tool (not yet implemented)
- run_task - Execute a mise task with optional arguments
  Example: {"task": "build", "args": ["--verbose"]}
```

---

---
url: /cli/outdated.md
---
# `mise outdated`

* **Usage**: `mise outdated [FLAGS] [TOOL@VERSION]…`
* **Source code**: [`src/cli/outdated.rs`](https://github.com/jdx/mise/blob/main/src/cli/outdated.rs)

Shows outdated tool versions

See `mise upgrade` to upgrade these versions.

## Arguments

### `[TOOL@VERSION]…`

Tool(s) to show outdated versions for
e.g.: node@20 python@3.10
If not specified, all tools in global and local configs will be shown

## Flags

### `-J --json`

Output in JSON format

### `-l --bump`

Compares against the latest versions available, not what matches the current config

For example, if you have `node = "20"` in your config by default `mise outdated` will only
show other 20.x versions, not 21.x or 22.x versions.

Using this flag, if there are 21.x or newer versions it will display those instead of 20.x.

### `--no-header`

Don't show table header

Examples:

```
$ mise outdated
Plugin  Requested  Current  Latest
python  3.11       3.11.0   3.11.1
node    20         20.0.0   20.1.0

$ mise outdated node
Plugin  Requested  Current  Latest
node    20         20.0.0   20.1.0

$ mise outdated --json
{"python": {"requested": "3.11", "current": "3.11.0", "latest": "3.11.1"}, ...}
```

---

---
url: /cli/plugins/install.md
---
# `mise plugins install`

* **Usage**: `mise plugins install [FLAGS] [NEW_PLUGIN] [GIT_URL]`
* **Aliases**: `i`, `a`, `add`
* **Source code**: [`src/cli/plugins/install.rs`](https://github.com/jdx/mise/blob/main/src/cli/plugins/install.rs)

Install a plugin

note that mise automatically can install plugins when you install a tool
e.g.: `mise install cmake@3.30` will autoinstall the cmake plugin

This behavior can be modified in ~/.config/mise/config.toml

## Arguments

### `[NEW_PLUGIN]`

The name of the plugin to install
e.g.: cmake, poetry
Can specify multiple plugins: `mise plugins install cmake poetry`

### `[GIT_URL]`

The git url of the plugin

## Flags

### `-a --all`

Install all missing plugins
This will only install plugins that have matching shorthands.
i.e.: they don't need the full git repo url

### `-f --force`

Reinstall even if plugin exists

### `-j --jobs <JOBS>`

Number of jobs to run in parallel

### `-v --verbose…`

Show installation output

Examples:

```
# install the poetry via shorthand
$ mise plugins install poetry

# install the poetry plugin using a specific git url
$ mise plugins install poetry https://github.com/mise-plugins/mise-poetry.git

# install the poetry plugin using the git url only
# (poetry is inferred from the url)
$ mise plugins install https://github.com/mise-plugins/mise-poetry.git

# install the poetry plugin using a specific ref
$ mise plugins install poetry https://github.com/mise-plugins/mise-poetry.git#11d0c1e
```

---

---
url: /cli/plugins/link.md
---
# `mise plugins link`

* **Usage**: `mise plugins link [-f --force] <NAME> [DIR]`
* **Aliases**: `ln`
* **Source code**: [`src/cli/plugins/link.rs`](https://github.com/jdx/mise/blob/main/src/cli/plugins/link.rs)

Symlinks a plugin into mise

This is used for developing a plugin.

## Arguments

### `<NAME>`

The name of the plugin
e.g.: cmake, poetry

### `[DIR]`

The local path to the plugin
e.g.: ./vfox-cmake

## Flags

### `-f --force`

Overwrite existing plugin

Examples:

```
# essentially just `ln -s ./vfox-cmake ~/.local/share/mise/plugins/cmake`
$ mise plugins link cmake ./vfox-cmake

# infer plugin name as "cmake"
$ mise plugins link ./vfox-cmake
```

---

---
url: /cli/plugins/ls-remote.md
---
# `mise plugins ls-remote`

* **Usage**: `mise plugins ls-remote [-u --urls] [--only-names]`
* **Aliases**: `list-remote`, `list-all`
* **Source code**: [`src/cli/plugins/ls_remote.rs`](https://github.com/jdx/mise/blob/main/src/cli/plugins/ls_remote.rs)

List all available remote plugins

The full list is here: <https://github.com/jdx/mise/blob/main/registry/>

Examples:

```
mise plugins ls-remote
```

## Flags

### `-u --urls`

Show the git url for each plugin e.g.: <https://github.com/mise-plugins/mise-poetry.git>

### `--only-names`

Only show the name of each plugin by default it will show a "\*" next to installed plugins

---

---
url: /cli/plugins/ls.md
---
# `mise plugins ls`

* **Usage**: `mise plugins ls [-o --outdated] [-u --urls]`
* **Aliases**: `list`
* **Source code**: [`src/cli/plugins/ls.rs`](https://github.com/jdx/mise/blob/main/src/cli/plugins/ls.rs)

List installed plugins

Can also show remotely available plugins to install.

## Flags

### `-o --outdated`

Show plugins with available updates
Checks the remote for newer versions and only displays plugins that are outdated

### `-u --urls`

Show the git url for each plugin
e.g.: <https://github.com/mise-plugins/vfox-cmake.git>

Examples:

```
$ mise plugins ls
cmake
poetry

$ mise plugins ls --urls
cmake     https://github.com/mise-plugins/vfox-cmake.git
poetry    https://github.com/mise-plugins/vfox-poetry.git
```

---

---
url: /cli/plugins/uninstall.md
---
# `mise plugins uninstall`

* **Usage**: `mise plugins uninstall [-a --all] [-p --purge] [PLUGIN]…`
* **Aliases**: `remove`, `rm`
* **Source code**: [`src/cli/plugins/uninstall.rs`](https://github.com/jdx/mise/blob/main/src/cli/plugins/uninstall.rs)

Removes a plugin

## Arguments

### `[PLUGIN]…`

Plugin(s) to remove

## Flags

### `-a --all`

Remove all plugins

### `-p --purge`

Also remove the plugin's installs, downloads, and cache

Examples:

```
mise plugins uninstall cmake
```

---

---
url: /cli/plugins/update.md
---
# `mise plugins update`

* **Usage**: `mise plugins update [-j --jobs <JOBS>] [PLUGIN]…`
* **Aliases**: `up`, `upgrade`
* **Source code**: [`src/cli/plugins/update.rs`](https://github.com/jdx/mise/blob/main/src/cli/plugins/update.rs)

Updates a plugin to the latest version

note: this updates the plugin itself, not the runtime versions

## Arguments

### `[PLUGIN]…`

Plugin(s) to update

## Flags

### `-j --jobs <JOBS>`

Number of jobs to run in parallel
Default: 4

Examples:

```
mise plugins update              # update all plugins
mise plugins update cmake       # update only cmake
mise plugins update cmake#beta  # specify a ref
```

---

---
url: /cli/plugins.md
---
# `mise plugins`

* **Usage**: `mise plugins [FLAGS] <SUBCOMMAND>`
* **Aliases**: `p`
* **Source code**: [`src/cli/plugins/mod.rs`](https://github.com/jdx/mise/blob/main/src/cli/plugins/mod.rs)

Manage plugins

## Flags

### `-c --core`

The built-in plugins only
Normally these are not shown

### `-u --urls`

Show the git url for each plugin
e.g.: <https://github.com/mise-plugins/vfox-cmake.git>

### `--user`

List installed plugins

This is the default behavior but can be used with --core
to show core and user plugins

## Subcommands

* [`mise plugins install [FLAGS] [NEW_PLUGIN] [GIT_URL]`](/cli/plugins/install.md)
* [`mise plugins link [-f --force] <NAME> [DIR]`](/cli/plugins/link.md)
* [`mise plugins ls [-o --outdated] [-u --urls]`](/cli/plugins/ls.md)
* [`mise plugins ls-remote [-u --urls] [--only-names]`](/cli/plugins/ls-remote.md)
* [`mise plugins uninstall [-a --all] [-p --purge] [PLUGIN]…`](/cli/plugins/uninstall.md)
* [`mise plugins update [-j --jobs <JOBS>] [PLUGIN]…`](/cli/plugins/update.md)

---

---
url: /cli/prepare.md
---
# `mise prepare`

* **Usage**: `mise prepare [FLAGS] [PROVIDER]`
* **Aliases**: `prep`
* **Source code**: [`src/cli/prepare.rs`](https://github.com/jdx/mise/blob/main/src/cli/prepare.rs)

\[experimental] Ensure project dependencies are ready

Runs all applicable prepare steps for the current project.
This checks if dependency lockfiles are newer than installed outputs
(e.g., package-lock.json vs node\_modules/) and runs install commands
if needed.

Providers with `auto = true` are automatically invoked before `mise x` and `mise run`
unless skipped with the --no-prepare flag.

## Arguments

### `[PROVIDER]`

Provider to operate on (runs only this provider, or use with --explain)

## Flags

### `--explain`

Show why a provider is fresh or stale (requires a provider argument)

### `-f --force`

Force run all prepare steps even if outputs are fresh

### `-n --dry-run`

Only check if prepare is needed, don't run commands

### `--list`

Show what prepare steps are available

### `--only… <ONLY>`

Run specific prepare rule(s) only

### `--skip… <SKIP>`

Skip specific prepare rule(s)

Examples:

```
mise prepare              # Run all applicable prepare steps
mise prepare npm          # Run only npm prepare
mise prepare npm --explain # Show why npm is fresh or stale
mise prepare --dry-run    # Show what would run without executing
mise prepare --force      # Force run even if outputs are fresh
mise prepare --list       # List available prepare providers
mise prepare --skip npm   # Skip npm prepare
```

Configuration:

````
Configure prepare providers in mise.toml:

```toml
# Built-in npm provider (auto-detects lockfile)
[prepare.npm]
auto = true              # Auto-run before mise x/run

# Custom provider
[prepare.codegen]
auto = true
sources = ["schema/*.graphql"]
outputs = ["src/generated/"]
run = "npm run codegen"

[prepare]
disable = ["npm"]        # Disable specific providers at runtime
````

```
```

---

---
url: /cli/prune.md
---
# `mise prune`

* **Usage**: `mise prune [FLAGS] [INSTALLED_TOOL]…`
* **Source code**: [`src/cli/prune.rs`](https://github.com/jdx/mise/blob/main/src/cli/prune.rs)

Delete unused versions of tools

mise tracks which config files have been used in ~/.local/state/mise/tracked-configs
Versions which are no longer the latest specified in any of those configs are deleted.
Versions installed only with environment variables `MISE_<PLUGIN>_VERSION` will be deleted,
as will versions only referenced on the command line `mise exec <PLUGIN>@<VERSION>`.

You can list prunable tools with `mise ls --prunable`

## Arguments

### `[INSTALLED_TOOL]…`

Prune only these tools

## Flags

### `-n --dry-run`

Do not actually delete anything

### `--configs`

Prune only tracked and trusted configuration links that point to non-existent configurations

### `--dry-run-code`

Like --dry-run but exits with code 1 if there are tools to prune

This is useful for scripts to check if tools need to be pruned.

### `--tools`

Prune only unused versions of tools

Examples:

```
$ mise prune --dry-run
rm -rf ~/.local/share/mise/versions/node/20.0.0
rm -rf ~/.local/share/mise/versions/node/20.0.1
```

---

---
url: /cli/registry.md
---
# `mise registry`

* **Usage**: `mise registry [FLAGS] [NAME]`
* **Source code**: [`src/cli/registry.rs`](https://github.com/jdx/mise/blob/main/src/cli/registry.rs)

List available tools to install

This command lists the tools available in the registry as shorthand names.

For example, `poetry` is shorthand for `asdf:mise-plugins/mise-poetry`.

## Arguments

### `[NAME]`

Show only the specified tool's full name

## Flags

### `-b --backend <BACKEND>`

Show only tools for this backend

### `--hide-aliased`

Hide aliased tools

### `-J --json`

Output in JSON format

Examples:

```
$ mise registry
node    core:node
poetry  asdf:mise-plugins/mise-poetry
ubi     cargo:ubi-cli

$ mise registry poetry
asdf:mise-plugins/mise-poetry
```

---

---
url: /cli/reshim.md
---
# `mise reshim`

* **Usage**: `mise reshim [-f --force]`
* **Source code**: [`src/cli/reshim.rs`](https://github.com/jdx/mise/blob/main/src/cli/reshim.rs)

Creates new shims based on bin paths from currently installed tools.

This creates new shims in ~/.local/share/mise/shims for CLIs that have been added.
mise will try to do this automatically for commands like `npm i -g` but there are
other ways to install things (like using yarn or pnpm for node) that mise does
not know about and so it will be necessary to call this explicitly.

If you think mise should automatically call this for a particular command, please
open an issue on the mise repo. You can also setup a shell function to reshim
automatically (it's really fast so you don't need to worry about overhead):

```
npm() {
  command npm "$@"
  mise reshim
}
```

Note that this creates shims for *all* installed tools, not just the ones that are
currently active in mise.toml.

## Flags

### `-f --force`

Removes all shims before reshimming

Examples:

```
$ mise reshim
$ ~/.local/share/mise/shims/node -v
v20.0.0
```

---

---
url: /cli/run.md
---
# `mise run`

* **Usage**: `mise run [FLAGS]`
* **Aliases**: `r`
* **Source code**: [`src/cli/run.rs`](https://github.com/jdx/mise/blob/main/src/cli/run.rs)

Run task(s)

This command will run a task, or multiple tasks in parallel.
Tasks may have dependencies on other tasks or on source files.
If source is configured on a task, it will only run if the source
files have changed.

Tasks can be defined in mise.toml or as standalone scripts.
In mise.toml, tasks take this form:

```
[tasks.build]
run = "npm run build"
sources = ["src/**/*.ts"]
outputs = ["dist/**/*.js"]
```

Alternatively, tasks can be defined as standalone scripts.
These must be located in `mise-tasks`, `.mise-tasks`, `.mise/tasks`, `mise/tasks` or
`.config/mise/tasks`.
The name of the script will be the name of the tasks.

```
$ cat .mise/tasks/build&lt;&lt;EOF
#!/usr/bin/env bash
npm run build
EOF
$ mise run build
```

## Flags

### `-c --continue-on-error`

Continue running tasks even if one fails

### `-C --cd <CD>`

Change to this directory before executing the command

### `-f --force`

Force the tasks to run even if outputs are up to date

### `-j --jobs <JOBS>`

Number of tasks to run in parallel
\[default: 4]
Configure with `jobs` config or `MISE_JOBS` env var

### `-n --dry-run`

Don't actually run the task(s), just print them in order of execution

### `-o --output <OUTPUT>`

Change how tasks information is output when running tasks

* `prefix` - Print stdout/stderr by line, prefixed with the task's label
* `interleave` - Print directly to stdout/stderr instead of by line
* `replacing` - Stdout is replaced each time, stderr is printed as is
* `timed` - Only show stdout lines if they are displayed for more than 1 second
* `keep-order` - Print stdout/stderr by line, prefixed with the task's label, but keep the order of the output
* `quiet` - Don't show extra output
* `silent` - Don't show any output including stdout and stderr from the task except for errors

### `-q --quiet`

Don't show extra output

### `-r --raw`

Read/write directly to stdin/stdout/stderr instead of by line
Redactions are not applied with this option
Configure with `raw` config or `MISE_RAW` env var

### `-s --shell <SHELL>`

Shell to use to run toml tasks

Defaults to `sh -c -o errexit -o pipefail` on unix, and `cmd /c` on Windows
Can also be set with the setting `MISE_UNIX_DEFAULT_INLINE_SHELL_ARGS` or `MISE_WINDOWS_DEFAULT_INLINE_SHELL_ARGS`
Or it can be overridden with the `shell` property on a task.

### `-S --silent`

Don't show any output except for errors

### `-t --tool… <TOOL@VERSION>`

Tool(s) to run in addition to what is in mise.toml files e.g.: node@20 python@3.10

### `--fresh-env`

Bypass the environment cache and recompute the environment

### `--no-cache`

Do not use cache on remote tasks

### `--no-prepare`

Skip automatic dependency preparation

### `--no-timings`

Hides elapsed time after each task completes

Default to always hide with `MISE_TASK_TIMINGS=0`

### `--skip-deps`

Run only the specified tasks skipping all dependencies

### `--timeout <TIMEOUT>`

Timeout for the task to complete
e.g.: 30s, 5m

Examples:

```
# Runs the "lint" tasks. This needs to either be defined in mise.toml
# or as a standalone script. See the project README for more information.
$ mise run lint

# Forces the "build" tasks to run even if its sources are up-to-date.
$ mise run --force build

# Run "test" with stdin/stdout/stderr all connected to the current terminal.
# This forces `--jobs=1` to prevent interleaving of output.
$ mise run --raw test

# Runs the "lint", "test", and "check" tasks in parallel.
$ mise run lint ::: test ::: check

# Execute multiple tasks each with their own arguments.
$ mise run cmd1 arg1 arg2 ::: cmd2 arg1 arg2
```

---

---
url: /cli/search.md
---
# `mise search`

* **Usage**: `mise search [FLAGS] [NAME]`
* **Source code**: [`src/cli/search.rs`](https://github.com/jdx/mise/blob/main/src/cli/search.rs)

Search for tools in the registry

This command searches a tool in the registry.

By default, it will show all tools that fuzzy match the search term. For
non-fuzzy matches, use the `--match-type` flag.

## Arguments

### `[NAME]`

The tool to search for

## Flags

### `-i --interactive`

Show interactive search

### `-m --match-type <MATCH_TYPE>`

Match type: equal, contains, or fuzzy

**Choices:**

* `equal`
* `contains`
* `fuzzy`

**Default:** `fuzzy`

### `--no-header`

Don't display headers

Examples:

```
$ mise search jq
Tool  Description
jq    Command-line JSON processor. https://github.com/jqlang/jq
jqp   A TUI playground to experiment with jq. https://github.com/noahgorstein/jqp
jiq   jid on jq - interactive JSON query tool using jq expressions. https://github.com/fiatjaf/jiq
gojq  Pure Go implementation of jq. https://github.com/itchyny/gojq

$ mise search --interactive
Tool
Search a tool
❯ jq    Command-line JSON processor. https://github.com/jqlang/jq
  jqp   A TUI playground to experiment with jq. https://github.com/noahgorstein/jqp
  jiq   jid on jq - interactive JSON query tool using jq expressions. https://github.com/fiatjaf/jiq
  gojq  Pure Go implementation of jq. https://github.com/itchyny/gojq
/jq 
esc clear filter • enter confirm
```

---

---
url: /cli/self-update.md
---
# `mise self-update`

* **Usage**: `mise self-update [FLAGS] [VERSION]`
* **Source code**: [`src/cli/self_update.rs`](https://github.com/jdx/mise/blob/main/src/cli/self_update.rs)

Updates mise itself.

Uses the GitHub Releases API to find the latest release and binary.
By default, this will also update any installed plugins.
Uses the `GITHUB_API_TOKEN` environment variable if set for higher rate limits.

This command is not available if mise is installed via a package manager.

## Arguments

### `[VERSION]`

Update to a specific version

## Flags

### `-f --force`

Update even if already up to date

### `-y --yes`

Skip confirmation prompt

### `--no-plugins`

Disable auto-updating plugins

---

---
url: /cli/set.md
---
# `mise set`

* **Usage**: `mise set [FLAGS] [ENV_VAR]…`
* **Source code**: [`src/cli/set.rs`](https://github.com/jdx/mise/blob/main/src/cli/set.rs)

Set environment variables in mise.toml

By default, this command modifies `mise.toml` in the current directory.
If multiple config files exist (e.g., both `mise.toml` and `mise.local.toml`),
the lowest precedence file (`mise.toml`) will be used.
See <https://mise.jdx.dev/configuration.html#target-file-for-write-operations>

Use `-E <env>` to create/modify environment-specific config files like `mise.<env>.toml`.

## Arguments

### `[ENV_VAR]…`

Environment variable(s) to set
e.g.: NODE\_ENV=production

## Flags

### `-E --env <ENV>`

Create/modify an environment-specific config file like .mise.\<env>.toml

### `-g --global`

Set the environment variable in the global config file

### `--age-encrypt`

\[experimental] Encrypt the value with age before storing

### `--age-key-file <PATH>`

\[experimental] Age identity file for encryption

Defaults to ~/.config/mise/age.txt if it exists

### `--age-recipient… <RECIPIENT>`

\[experimental] Age recipient (x25519 public key) for encryption

Can be used multiple times. Requires --age-encrypt.

### `--age-ssh-recipient… <PATH_OR_PUBKEY>`

\[experimental] SSH recipient (public key or path) for age encryption

Can be used multiple times. Requires --age-encrypt.

### `--file <FILE>`

The TOML file to update

Can be a file path or directory. If a directory is provided, will create/use mise.toml in that directory.
Defaults to MISE\_DEFAULT\_CONFIG\_FILENAME environment variable, or `mise.toml`.

### `--prompt`

Prompt for environment variable values

### `--stdin`

Read the value from stdin (for multiline input)

When using --stdin, provide a single key without a value. The value will be read from stdin until EOF.

Examples:

```
$ mise set NODE_ENV=production

$ mise set NODE_ENV
production

$ mise set -E staging NODE_ENV=staging
# creates or modifies mise.staging.toml

$ mise set
key       value       source
NODE_ENV  production  ~/.config/mise/config.toml

$ mise set --prompt PASSWORD
Enter value for PASSWORD: [hidden input]

Multiline Values (--stdin):

$ cat private.key | mise set --stdin MY_KEY

$ printf "line1\nline2" | mise set --stdin MY_KEY

[experimental] Age Encryption:

$ mise set --age-encrypt API_KEY=secret

$ mise set --age-encrypt --prompt API_KEY
Enter value for API_KEY: [hidden input]
```

---

---
url: /cli/settings/add.md
---
# `mise settings add`

* **Usage**: `mise settings add [-l --local] <SETTING> [VALUE]`
* **Source code**: [`src/cli/settings/add.rs`](https://github.com/jdx/mise/blob/main/src/cli/settings/add.rs)

Adds a setting to the configuration file

Used with an array setting, this will append the value to the array.
This modifies the contents of ~/.config/mise/config.toml

## Arguments

### `<SETTING>`

The setting to set

### `[VALUE]`

The value to set (optional if provided as KEY=VALUE)

## Flags

### `-l --local`

Use the local config file instead of the global one

Examples:

```
mise settings add disable_hints python_multi
```

---

---
url: /cli/settings/get.md
---
# `mise settings get`

* **Usage**: `mise settings get [-l --local] <SETTING>`
* **Source code**: [`src/cli/settings/get.rs`](https://github.com/jdx/mise/blob/main/src/cli/settings/get.rs)

Show a current setting

This is the contents of a single entry in ~/.config/mise/config.toml

Note that aliases are also stored in this file
but managed separately with `mise tool-alias get`

## Arguments

### `<SETTING>`

The setting to show

## Flags

### `-l --local`

Use the local config file instead of the global one

Examples:

```
$ mise settings get idiomatic_version_file
true
```

---

---
url: /cli/settings/ls.md
---
# `mise settings ls`

* **Usage**: `mise settings ls [FLAGS] [SETTING]`
* **Aliases**: `list`
* **Source code**: [`src/cli/settings/ls.rs`](https://github.com/jdx/mise/blob/main/src/cli/settings/ls.rs)

Show current settings

This is the contents of ~/.config/mise/config.toml

Note that aliases are also stored in this file
but managed separately with `mise tool-alias`

## Arguments

### `[SETTING]`

Name of setting

## Flags

### `-a --all`

List all settings

### `-J --json`

Output in JSON format

### `-l --local`

Use the local config file instead of the global one

### `-T --toml`

Output in TOML format

### `--json-extended`

Output in JSON format with sources

Examples:

```
$ mise settings ls
idiomatic_version_file = false
...

$ mise settings ls python
default_packages_file = "~/.default-python-packages"
...
```

---

---
url: /cli/settings/set.md
---
# `mise settings set`

* **Usage**: `mise settings set [-l --local] <SETTING> [VALUE]`
* **Aliases**: `create`
* **Source code**: [`src/cli/settings/set.rs`](https://github.com/jdx/mise/blob/main/src/cli/settings/set.rs)

Add/update a setting

This modifies the contents of ~/.config/mise/config.toml by default.
With `--local`, modifies the local config file instead.
See <https://mise.jdx.dev/configuration.html#target-file-for-write-operations>

## Arguments

### `<SETTING>`

The setting to set

### `[VALUE]`

The value to set (optional if provided as KEY=VALUE)

## Flags

### `-l --local`

Use the local config file instead of the global one

Examples:

```
mise settings idiomatic_version_file=true
```

---

---
url: /cli/settings/unset.md
---
# `mise settings unset`

* **Usage**: `mise settings unset [-l --local] <KEY>`
* **Aliases**: `rm`, `remove`, `delete`, `del`
* **Source code**: [`src/cli/settings/unset.rs`](https://github.com/jdx/mise/blob/main/src/cli/settings/unset.rs)

Clears a setting

This modifies the contents of ~/.config/mise/config.toml

## Arguments

### `<KEY>`

The setting to remove

## Flags

### `-l --local`

Use the local config file instead of the global one

Examples:

```
mise settings unset idiomatic_version_file
```

---

---
url: /cli/settings.md
---
# `mise settings`

* **Usage**: `mise settings [FLAGS] [SETTING] [VALUE] <SUBCOMMAND>`
* **Source code**: [`src/cli/settings/mod.rs`](https://github.com/jdx/mise/blob/main/src/cli/settings/mod.rs)

Show current settings

This is the contents of ~/.config/mise/config.toml

Note that aliases are also stored in this file
but managed separately with `mise tool-alias`

## Arguments

### `[SETTING]`

Name of setting

### `[VALUE]`

Setting value to set

## Global Flags

### `-l --local`

Use the local config file instead of the global one

## Flags

### `-a --all`

List all settings

### `-J --json`

Output in JSON format

### `-T --toml`

Output in TOML format

### `--json-extended`

Output in JSON format with sources

## Subcommands

* [`mise settings add [-l --local] <SETTING> [VALUE]`](/cli/settings/add.md)
* [`mise settings get [-l --local] <SETTING>`](/cli/settings/get.md)
* [`mise settings ls [FLAGS] [SETTING]`](/cli/settings/ls.md)
* [`mise settings set [-l --local] <SETTING> [VALUE]`](/cli/settings/set.md)
* [`mise settings unset [-l --local] <KEY>`](/cli/settings/unset.md)

Examples:

```
# list all settings
$ mise settings

# get the value of the setting "always_keep_download"
$ mise settings always_keep_download

# set the value of the setting "always_keep_download" to "true"
$ mise settings always_keep_download=true

# set the value of the setting "node.mirror_url" to "https://npm.taobao.org/mirrors/node"
$ mise settings node.mirror_url https://npm.taobao.org/mirrors/node
```

---

---
url: /cli/shell-alias/get.md
---
# `mise shell-alias get`

* **Usage**: `mise shell-alias get <shell_alias>`
* **Source code**: [`src/cli/shell_alias/get.rs`](https://github.com/jdx/mise/blob/main/src/cli/shell_alias/get.rs)

Show the command for a shell alias

## Arguments

### `<shell_alias>`

The alias to show

Examples:

```
$ mise shell-alias get ll
ls -la
```

---

---
url: /cli/shell-alias/ls.md
---
# `mise shell-alias ls`

* **Usage**: `mise shell-alias ls [--no-header]`
* **Aliases**: `list`
* **Source code**: [`src/cli/shell_alias/ls.rs`](https://github.com/jdx/mise/blob/main/src/cli/shell_alias/ls.rs)

List shell aliases

Shows the shell aliases that are set in the current directory.
These are defined in `mise.toml` under the `[shell_alias]` section.

## Flags

### `--no-header`

Don't show table header

Examples:

```
$ mise shell-alias ls
alias    command
ll       ls -la
gs       git status
```

---

---
url: /cli/shell-alias/set.md
---
# `mise shell-alias set`

* **Usage**: `mise shell-alias set <shell_alias> [COMMAND]`
* **Aliases**: `add`, `create`
* **Source code**: [`src/cli/shell_alias/set.rs`](https://github.com/jdx/mise/blob/main/src/cli/shell_alias/set.rs)

Add/update a shell alias

This modifies the contents of ~/.config/mise/config.toml

## Arguments

### `<shell_alias>`

The alias name

### `[COMMAND]`

The command to run (optional if provided as ALIAS=COMMAND)

Examples:

```
mise shell-alias set ll "ls -la"
mise shell-alias set gs "git status"
```

---

---
url: /cli/shell-alias/unset.md
---
# `mise shell-alias unset`

* **Usage**: `mise shell-alias unset <shell_alias>`
* **Aliases**: `rm`, `remove`, `delete`, `del`
* **Source code**: [`src/cli/shell_alias/unset.rs`](https://github.com/jdx/mise/blob/main/src/cli/shell_alias/unset.rs)

Removes a shell alias

This modifies the contents of ~/.config/mise/config.toml

## Arguments

### `<shell_alias>`

The alias to remove

Examples:

```
mise shell-alias unset ll
```

---

---
url: /cli/shell-alias.md
---
# `mise shell-alias`

* **Usage**: `mise shell-alias [--no-header] <SUBCOMMAND>`
* **Source code**: [`src/cli/shell_alias/mod.rs`](https://github.com/jdx/mise/blob/main/src/cli/shell_alias/mod.rs)

Manage shell aliases.

## Flags

### `--no-header`

Don't show table header

## Subcommands

* [`mise shell-alias get <shell_alias>`](/cli/shell-alias/get.md)
* [`mise shell-alias ls [--no-header]`](/cli/shell-alias/ls.md)
* [`mise shell-alias set <shell_alias> [COMMAND]`](/cli/shell-alias/set.md)
* [`mise shell-alias unset <shell_alias>`](/cli/shell-alias/unset.md)

---

---
url: /cli/shell.md
---
# `mise shell`

* **Usage**: `mise shell [FLAGS] <TOOL@VERSION>…`
* **Aliases**: `sh`
* **Source code**: [`src/cli/shell.rs`](https://github.com/jdx/mise/blob/main/src/cli/shell.rs)

Sets a tool version for the current session.

Only works in a session where mise is already activated.

This works by setting environment variables for the current shell session
such as `MISE_NODE_VERSION=20` which is "eval"ed as a shell function created by `mise activate`.

## Arguments

### `<TOOL@VERSION>…`

Tool(s) to use

## Flags

### `-j --jobs <JOBS>`

Number of jobs to run in parallel
\[default: 4]

### `-u --unset`

Removes a previously set version

### `--raw`

Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1

Examples:

```
$ mise shell node@20
$ node -v
v20.0.0
```

---

---
url: /cli/sync/node.md
---
# `mise sync node`

* **Usage**: `mise sync node [FLAGS]`
* **Source code**: [`src/cli/sync/node.rs`](https://github.com/jdx/mise/blob/main/src/cli/sync/node.rs)

Symlinks all tool versions from an external tool into mise

For example, use this to import all Homebrew node installs into mise

This won't overwrite any existing installs but will overwrite any existing symlinks

## Flags

### `--brew`

Get tool versions from Homebrew

### `--nodenv`

Get tool versions from nodenv

### `--nvm`

Get tool versions from nvm

Examples:

```
brew install node@18 node@20
mise sync node --brew
mise use -g node@18 - uses Homebrew-provided node
```

---

---
url: /cli/sync/python.md
---
# `mise sync python`

* **Usage**: `mise sync python [--pyenv] [--uv]`
* **Source code**: [`src/cli/sync/python.rs`](https://github.com/jdx/mise/blob/main/src/cli/sync/python.rs)

Symlinks all tool versions from an external tool into mise

For example, use this to import all pyenv installs into mise

This won't overwrite any existing installs but will overwrite any existing symlinks

## Flags

### `--pyenv`

Get tool versions from pyenv

### `--uv`

Sync tool versions with uv (2-way sync)

Examples:

```
pyenv install 3.11.0
mise sync python --pyenv
mise use -g python@3.11.0 - uses pyenv-provided python

uv python install 3.11.0
mise install python@3.10.0
mise sync python --uv
mise x python@3.11.0 -- python -V - uses uv-provided python
uv run -p 3.10.0 -- python -V - uses mise-provided python
```

---

---
url: /cli/sync/ruby.md
---
# `mise sync ruby`

* **Usage**: `mise sync ruby [--brew]`
* **Source code**: [`src/cli/sync/ruby.rs`](https://github.com/jdx/mise/blob/main/src/cli/sync/ruby.rs)

Symlinks all ruby tool versions from an external tool into mise

## Flags

### `--brew`

Get tool versions from Homebrew

Examples:

```
brew install ruby
mise sync ruby --brew
mise use -g ruby - Use the latest version of Ruby installed by Homebrew
```

---

---
url: /cli/sync.md
---
# `mise sync`

* **Usage**: `mise sync <SUBCOMMAND>`
* **Source code**: [`src/cli/sync/mod.rs`](https://github.com/jdx/mise/blob/main/src/cli/sync/mod.rs)

Synchronize tools from other version managers with mise

## Subcommands

* [`mise sync node [FLAGS]`](/cli/sync/node.md)
* [`mise sync python [--pyenv] [--uv]`](/cli/sync/python.md)
* [`mise sync ruby [--brew]`](/cli/sync/ruby.md)

---

---
url: /cli/tasks/add.md
---
# `mise tasks add`

* **Usage**: `mise tasks add [FLAGS] <TASK> [-- RUN]…`
* **Source code**: [`src/cli/tasks/add.rs`](https://github.com/jdx/mise/blob/main/src/cli/tasks/add.rs)

Create a new task

Adds a task to the local mise.toml file.
See <https://mise.jdx.dev/configuration.html#target-file-for-write-operations>

## Arguments

### `<TASK>`

Tasks name to add

### `[-- RUN]…`

## Flags

### `-a --alias… <ALIAS>`

Other names for the task

### `-d --depends… <DEPENDS>`

Add dependencies to the task

### `-D --dir <DIR>`

Run the task in a specific directory

### `-f --file`

Create a file task instead of a toml task

### `-H --hide`

Hide the task from `mise tasks` and completions

### `-q --quiet`

Do not print the command before running

### `-r --raw`

Directly connect stdin/stdout/stderr

### `-s --sources… <SOURCES>`

Glob patterns of files this task uses as input

### `-w --wait-for… <WAIT_FOR>`

Wait for these tasks to complete if they are to run

### `--depends-post… <DEPENDS_POST>`

Dependencies to run after the task runs

### `--description <DESCRIPTION>`

Description of the task

### `--outputs… <OUTPUTS>`

Glob patterns of files this task creates, to skip if they are not modified

### `--run-windows <RUN_WINDOWS>`

Command to run on windows

### `--shell <SHELL>`

Run the task in a specific shell

### `--silent`

Do not print the command or its output

Examples:

```
mise tasks add pre-commit --depends "test" --depends "render" -- echo pre-commit
```

---

---
url: /cli/tasks/deps.md
---
# `mise tasks deps`

* **Usage**: `mise tasks deps [--dot] [--hidden] [TASKS]…`
* **Source code**: [`src/cli/tasks/deps.rs`](https://github.com/jdx/mise/blob/main/src/cli/tasks/deps.rs)

Display a tree visualization of a dependency graph

## Arguments

### `[TASKS]…`

Tasks to show dependencies for
Can specify multiple tasks by separating with spaces
e.g.: mise tasks deps lint test check

## Flags

### `--dot`

Display dependencies in DOT format

### `--hidden`

Show hidden tasks

Examples:

```
# Show dependencies for all tasks
$ mise tasks deps

# Show dependencies for the "lint", "test" and "check" tasks
$ mise tasks deps lint test check

# Show dependencies in DOT format
$ mise tasks deps --dot
```

---

---
url: /cli/tasks/edit.md
---
# `mise tasks edit`

* **Usage**: `mise tasks edit [-p --path] <TASK>`
* **Source code**: [`src/cli/tasks/edit.rs`](https://github.com/jdx/mise/blob/main/src/cli/tasks/edit.rs)

Edit a task with $EDITOR

The task will be created as a standalone script if it does not already exist.

## Arguments

### `<TASK>`

Task to edit

## Flags

### `-p --path`

Display the path to the task instead of editing it

Examples:

```
mise tasks edit build
mise tasks edit test
```

---

---
url: /cli/tasks/info.md
---
# `mise tasks info`

* **Usage**: `mise tasks info [-J --json] <TASK>`
* **Source code**: [`src/cli/tasks/info.rs`](https://github.com/jdx/mise/blob/main/src/cli/tasks/info.rs)

Get information about a task

## Arguments

### `<TASK>`

Name of the task to get information about

## Flags

### `-J --json`

Output in JSON format

Examples:

```
$ mise tasks info
Name: test
Aliases: t
Description: Test the application
Source: ~/src/myproj/mise.toml

$ mise tasks info test --json
{
  "name": "test",
  "aliases": "t",
  "description": "Test the application",
  "source": "~/src/myproj/mise.toml",
  "depends": [],
  "env": {},
  "dir": null,
  "hide": false,
  "raw": false,
  "sources": [],
  "outputs": [],
  "run": [
    "echo \"testing!\""
  ],
  "file": null,
  "usage_spec": {}
}
```

---

---
url: /cli/tasks/ls.md
---
# `mise tasks ls`

* **Usage**: `mise tasks ls [FLAGS]`
* **Source code**: [`src/cli/tasks/ls.rs`](https://github.com/jdx/mise/blob/main/src/cli/tasks/ls.rs)

List available tasks to execute
These may be included from the config file or from the project's .mise/tasks directory
mise will merge all tasks from all parent directories into this list.

So if you have global tasks in `~/.config/mise/tasks/*` and project-specific tasks in
\~/myproject/.mise/tasks/\*, then they'll both be available but the project-specific
tasks will override the global ones if they have the same name.

## Flags

### `-g --global`

Only show global tasks

### `-J --json`

Output in JSON format

### `-l --local`

Only show non-global tasks

### `-x --extended`

Show all columns

### `--all`

Load all tasks from the entire monorepo, including sibling directories.
By default, only tasks from the current directory hierarchy are loaded.

### `--hidden`

Show hidden tasks

### `--no-header`

Do not print table header

### `--sort <COLUMN>`

Sort by column. Default is name.

**Choices:**

* `name`
* `alias`
* `description`
* `source`

### `--sort-order <SORT_ORDER>`

Sort order. Default is asc.

**Choices:**

* `asc`
* `desc`

Examples:

```
mise tasks ls
```

---

---
url: /cli/tasks/run.md
---
# `mise tasks run`

* **Usage**: `mise tasks run [FLAGS] [TASK] [ARGS]…`
* **Aliases**: `r`
* **Source code**: [`src/cli/tasks/run.rs`](https://github.com/jdx/mise/blob/main/src/cli/tasks/run.rs)

Run task(s)

This command will run a task, or multiple tasks in parallel.
Tasks may have dependencies on other tasks or on source files.
If source is configured on a task, it will only run if the source
files have changed.

Tasks can be defined in mise.toml or as standalone scripts.
In mise.toml, tasks take this form:

```
[tasks.build]
run = "npm run build"
sources = ["src/**/*.ts"]
outputs = ["dist/**/*.js"]
```

Alternatively, tasks can be defined as standalone scripts.
These must be located in `mise-tasks`, `.mise-tasks`, `.mise/tasks`, `mise/tasks` or
`.config/mise/tasks`.
The name of the script will be the name of the tasks.

```
$ cat .mise/tasks/build&lt;&lt;EOF
#!/usr/bin/env bash
npm run build
EOF
$ mise run build
```

## Arguments

### `[TASK]`

Tasks to run
Can specify multiple tasks by separating with `:::`
e.g.: mise run task1 arg1 arg2 ::: task2 arg1 arg2

**Default:** `default`

### `[ARGS]…`

Arguments to pass to the tasks. Use ":::" to separate tasks

## Flags

### `-c --continue-on-error`

Continue running tasks even if one fails

### `-C --cd <CD>`

Change to this directory before executing the command

### `-f --force`

Force the tasks to run even if outputs are up to date

### `-j --jobs <JOBS>`

Number of tasks to run in parallel
\[default: 4]
Configure with `jobs` config or `MISE_JOBS` env var

### `-n --dry-run`

Don't actually run the task(s), just print them in order of execution

### `-o --output <OUTPUT>`

Change how tasks information is output when running tasks

* `prefix` - Print stdout/stderr by line, prefixed with the task's label
* `interleave` - Print directly to stdout/stderr instead of by line
* `replacing` - Stdout is replaced each time, stderr is printed as is
* `timed` - Only show stdout lines if they are displayed for more than 1 second
* `keep-order` - Print stdout/stderr by line, prefixed with the task's label, but keep the order of the output
* `quiet` - Don't show extra output
* `silent` - Don't show any output including stdout and stderr from the task except for errors

### `-q --quiet`

Don't show extra output

### `-r --raw`

Read/write directly to stdin/stdout/stderr instead of by line
Redactions are not applied with this option
Configure with `raw` config or `MISE_RAW` env var

### `-s --shell <SHELL>`

Shell to use to run toml tasks

Defaults to `sh -c -o errexit -o pipefail` on unix, and `cmd /c` on Windows
Can also be set with the setting `MISE_UNIX_DEFAULT_INLINE_SHELL_ARGS` or `MISE_WINDOWS_DEFAULT_INLINE_SHELL_ARGS`
Or it can be overridden with the `shell` property on a task.

### `-S --silent`

Don't show any output except for errors

### `-t --tool… <TOOL@VERSION>`

Tool(s) to run in addition to what is in mise.toml files e.g.: node@20 python@3.10

### `--fresh-env`

Bypass the environment cache and recompute the environment

### `--no-cache`

Do not use cache on remote tasks

### `--no-prepare`

Skip automatic dependency preparation

### `--no-timings`

Hides elapsed time after each task completes

Default to always hide with `MISE_TASK_TIMINGS=0`

### `--skip-deps`

Run only the specified tasks skipping all dependencies

### `--timeout <TIMEOUT>`

Timeout for the task to complete
e.g.: 30s, 5m

Examples:

```
# Runs the "lint" tasks. This needs to either be defined in mise.toml
# or as a standalone script. See the project README for more information.
$ mise run lint

# Forces the "build" tasks to run even if its sources are up-to-date.
$ mise run --force build

# Run "test" with stdin/stdout/stderr all connected to the current terminal.
# This forces `--jobs=1` to prevent interleaving of output.
$ mise run --raw test

# Runs the "lint", "test", and "check" tasks in parallel.
$ mise run lint ::: test ::: check

# Execute multiple tasks each with their own arguments.
$ mise run cmd1 arg1 arg2 ::: cmd2 arg1 arg2
```

---

---
url: /cli/tasks/validate.md
---
# `mise tasks validate`

* **Usage**: `mise tasks validate [--errors-only] [--json] [TASKS]…`
* **Source code**: [`src/cli/tasks/validate.rs`](https://github.com/jdx/mise/blob/main/src/cli/tasks/validate.rs)

Validate tasks for common errors and issues

## Arguments

### `[TASKS]…`

Tasks to validate
If not specified, validates all tasks

## Flags

### `--errors-only`

Only show errors (skip warnings)

### `--json`

Output validation results in JSON format

Examples:

```
# Validate all tasks
$ mise tasks validate

# Validate specific tasks
$ mise tasks validate build test

# Output results as JSON
$ mise tasks validate --json

# Only show errors (skip warnings)
$ mise tasks validate --errors-only
```

Validation Checks:

The validate command performs the following checks:

• Circular Dependencies: Detects dependency cycles
• Missing References: Finds references to non-existent tasks
• Usage Spec Parsing: Validates #USAGE directives and specs
• Timeout Format: Checks timeout values are valid durations
• Alias Conflicts: Detects duplicate aliases across tasks
• File Existence: Verifies file-based tasks exist
• Directory Templates: Validates directory paths and templates
• Shell Commands: Checks shell executables exist
• Glob Patterns: Validates source and output patterns
• Run Entries: Ensures tasks reference valid dependencies

---

---
url: /cli/tasks.md
---
# `mise tasks`

* **Usage**: `mise tasks [FLAGS] [TASK] <SUBCOMMAND>`
* **Aliases**: `t`
* **Source code**: [`src/cli/tasks/mod.rs`](https://github.com/jdx/mise/blob/main/src/cli/tasks/mod.rs)

Manage tasks

## Arguments

### `[TASK]`

Task name to get info of

## Global Flags

### `-g --global`

Only show global tasks

### `-J --json`

Output in JSON format

### `-l --local`

Only show non-global tasks

### `-x --extended`

Show all columns

### `--all`

Load all tasks from the entire monorepo, including sibling directories.
By default, only tasks from the current directory hierarchy are loaded.

### `--hidden`

Show hidden tasks

### `--no-header`

Do not print table header

### `--sort <COLUMN>`

Sort by column. Default is name.

**Choices:**

* `name`
* `alias`
* `description`
* `source`

### `--sort-order <SORT_ORDER>`

Sort order. Default is asc.

**Choices:**

* `asc`
* `desc`

## Subcommands

* [`mise tasks add [FLAGS] <TASK> [-- RUN]…`](/cli/tasks/add.md)
* [`mise tasks deps [--dot] [--hidden] [TASKS]…`](/cli/tasks/deps.md)
* [`mise tasks edit [-p --path] <TASK>`](/cli/tasks/edit.md)
* [`mise tasks info [-J --json] <TASK>`](/cli/tasks/info.md)
* [`mise tasks ls [FLAGS]`](/cli/tasks/ls.md)
* [`mise tasks run [FLAGS] [TASK] [ARGS]…`](/cli/tasks/run.md)
* [`mise tasks validate [--errors-only] [--json] [TASKS]…`](/cli/tasks/validate.md)

Examples:

```
mise tasks ls
```

---

---
url: /cli/test-tool.md
---
# `mise test-tool`

* **Usage**: `mise test-tool [FLAGS] [TOOLS]…`
* **Source code**: [`src/cli/test_tool.rs`](https://github.com/jdx/mise/blob/main/src/cli/test_tool.rs)

Test a tool installs and executes

## Arguments

### `[TOOLS]…`

Tool(s) to test

## Flags

### `-a --all`

Test every tool specified in registry/

### `-j --jobs <JOBS>`

Number of jobs to run in parallel
\[default: 4]

### `--all-config`

Test all tools specified in config files

### `--include-non-defined`

Also test tools not defined in registry/, guessing how to test it

### `--raw`

Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1

Examples:

```
mise test-tool ripgrep
```

---

---
url: /cli/tool-alias/get.md
---
# `mise tool-alias get`

* **Usage**: `mise tool-alias get <PLUGIN> <ALIAS>`
* **Source code**: [`src/cli/tool_alias/get.rs`](https://github.com/jdx/mise/blob/main/src/cli/tool_alias/get.rs)

Show an alias for a plugin

This is the contents of a tool\_alias.\<PLUGIN> entry in ~/.config/mise/config.toml

## Arguments

### `<PLUGIN>`

The plugin to show the alias for

### `<ALIAS>`

The alias to show

Examples:

```
$ mise tool-alias get node lts-hydrogen
20.0.0
```

---

---
url: /cli/tool-alias/ls.md
---
# `mise tool-alias ls`

* **Usage**: `mise tool-alias ls [--no-header] [TOOL]`
* **Aliases**: `list`
* **Source code**: [`src/cli/tool_alias/ls.rs`](https://github.com/jdx/mise/blob/main/src/cli/tool_alias/ls.rs)

List tool version aliases
Shows the aliases that can be specified.
These can come from user config or from plugins in `bin/list-aliases`.

For user config, aliases are defined like the following in `~/.config/mise/config.toml`:

```
[tool_alias.node.versions]
lts = "22.0.0"
```

## Arguments

### `[TOOL]`

Show aliases for \<TOOL>

## Flags

### `--no-header`

Don't show table header

Examples:

```
$ mise tool-alias ls
node  lts-jod      22
```

---

---
url: /cli/tool-alias/set.md
---
# `mise tool-alias set`

* **Usage**: `mise tool-alias set <ARGS>…`
* **Aliases**: `add`, `create`
* **Source code**: [`src/cli/tool_alias/set.rs`](https://github.com/jdx/mise/blob/main/src/cli/tool_alias/set.rs)

Add/update an alias for a backend/plugin

This modifies the contents of ~/.config/mise/config.toml

## Arguments

### `<PLUGIN>`

The backend/plugin to set the alias for

### `<ALIAS>`

The alias to set

### `[VALUE]`

The value to set the alias to

Examples:

```
mise tool-alias set maven asdf:mise-plugins/mise-maven
mise tool-alias set node lts-jod 22.0.0
```

---

---
url: /cli/tool-alias/unset.md
---
# `mise tool-alias unset`

* **Usage**: `mise tool-alias unset <PLUGIN> [ALIAS]`
* **Aliases**: `rm`, `remove`, `delete`, `del`
* **Source code**: [`src/cli/tool_alias/unset.rs`](https://github.com/jdx/mise/blob/main/src/cli/tool_alias/unset.rs)

Clears an alias for a backend/plugin

This modifies the contents of ~/.config/mise/config.toml

## Arguments

### `<PLUGIN>`

The backend/plugin to remove the alias from

### `[ALIAS]`

The alias to remove

Examples:

```
mise tool-alias unset maven
mise tool-alias unset node lts-jod
```

---

---
url: /cli/tool-alias.md
---
# `mise tool-alias`

* **Usage**: `mise tool-alias [-p --plugin <PLUGIN>] [--no-header] <SUBCOMMAND>`
* **Source code**: [`src/cli/tool_alias/mod.rs`](https://github.com/jdx/mise/blob/main/src/cli/tool_alias/mod.rs)

Manage tool version aliases.

## Flags

### `-p --plugin <PLUGIN>`

filter aliases by plugin

### `--no-header`

Don't show table header

## Subcommands

* [`mise tool-alias get <PLUGIN> <ALIAS>`](/cli/tool-alias/get.md)
* [`mise tool-alias ls [--no-header] [TOOL]`](/cli/tool-alias/ls.md)
* [`mise tool-alias set <ARGS>…`](/cli/tool-alias/set.md)
* [`mise tool-alias unset <PLUGIN> [ALIAS]`](/cli/tool-alias/unset.md)

---

---
url: /cli/tool-stub.md
---
# `mise tool-stub`

* **Usage**: `mise tool-stub <FILE> [ARGS]…`
* **Source code**: [`src/cli/tool_stub.rs`](https://github.com/jdx/mise/blob/main/src/cli/tool_stub.rs)

Execute a tool stub

Tool stubs are executable files containing TOML configuration that specify which tool to run and how to run it. They provide a convenient way to create portable, self-contained executables that automatically manage tool installation and execution.

A tool stub consists of: - A shebang line: #!/usr/bin/env -S mise tool-stub - TOML configuration specifying the tool, version, and options - Optional comments describing the tool's purpose

Example stub file: #!/usr/bin/env -S mise tool-stub # Node.js v20 development environment

tool = "node" version = "20.0.0" bin = "node"

The stub will automatically install the specified tool version if missing and execute it with any arguments passed to the stub.

For more information, see: <https://mise.jdx.dev/dev-tools/tool-stubs.html>

## Arguments

### `<FILE>`

Path to the TOML tool stub file to execute

The stub file must contain TOML configuration specifying the tool and version to run. At minimum, it should specify a 'version' field. Other common fields include 'tool', 'bin', and backend-specific options.

### `[ARGS]…`

Arguments to pass to the tool

All arguments after the stub file path will be forwarded to the underlying tool. Use '--' to separate mise arguments from tool arguments if needed.

---

---
url: /cli/tool.md
---
# `mise tool`

* **Usage**: `mise tool [FLAGS] <TOOL>`
* **Source code**: [`src/cli/tool.rs`](https://github.com/jdx/mise/blob/main/src/cli/tool.rs)

Gets information about a tool

## Arguments

### `<TOOL>`

Tool name to get information about

## Flags

### `-J --json`

Output in JSON format

### `--active`

Only show active versions

### `--backend`

Only show backend field

### `--config-source`

Only show config source

### `--description`

Only show description field

### `--installed`

Only show installed versions

### `--requested`

Only show requested versions

### `--tool-options`

Only show tool options

Examples:

```
$ mise tool node
Backend:            core
Installed Versions: 20.0.0 22.0.0
Active Version:     20.0.0
Requested Version:  20
Config Source:      ~/.config/mise/mise.toml
Tool Options:       [none]
```

---

---
url: /cli/trust.md
---
# `mise trust`

* **Usage**: `mise trust [FLAGS] [CONFIG_FILE]`
* **Source code**: [`src/cli/trust.rs`](https://github.com/jdx/mise/blob/main/src/cli/trust.rs)

Marks a config file as trusted

This means mise will parse the file with potentially dangerous
features enabled.

This includes:

* environment variables
* templates
* `path:` plugin versions

## Arguments

### `[CONFIG_FILE]`

The config file to trust

## Flags

### `-a --all`

Trust all config files in the current directory and its parents

### `--ignore`

Do not trust this config and ignore it in the future

### `--show`

Show the trusted status of config files from the current directory and its parents.
Does not trust or untrust any files.

### `--untrust`

No longer trust this config, will prompt in the future

Examples:

```
# trusts ~/some_dir/mise.toml
$ mise trust ~/some_dir/mise.toml

# trusts mise.toml in the current or parent directory
$ mise trust
```

---

---
url: /cli/uninstall.md
---
# `mise uninstall`

* **Usage**: `mise uninstall [FLAGS] [INSTALLED_TOOL@VERSION]…`
* **Source code**: [`src/cli/uninstall.rs`](https://github.com/jdx/mise/blob/main/src/cli/uninstall.rs)

Removes installed tool versions

This only removes the installed version, it does not modify mise.toml.

## Arguments

### `[INSTALLED_TOOL@VERSION]…`

Tool(s) to remove

## Flags

### `-a --all`

Delete all installed versions

### `-n --dry-run`

Do not actually delete anything

### `--dry-run-code`

Like --dry-run but exits with code 1 if there are tools to uninstall

This is useful for scripts to check if tools need to be uninstalled.

Examples:

```
# will uninstall specific version
$ mise uninstall node@18.0.0

# will uninstall the current node version (if only one version is installed)
$ mise uninstall node

# will uninstall all installed versions of node
$ mise uninstall --all node@18.0.0 # will uninstall all node versions
```

---

---
url: /cli/unset.md
---
# `mise unset`

* **Usage**: `mise unset [-f --file <FILE>] [-g --global] [ENV_KEY]…`
* **Source code**: [`src/cli/unset.rs`](https://github.com/jdx/mise/blob/main/src/cli/unset.rs)

Remove environment variable(s) from the config file.

By default, this command modifies `mise.toml` in the current directory.

## Arguments

### `[ENV_KEY]…`

Environment variable(s) to remove
e.g.: NODE\_ENV

## Flags

### `-f --file <FILE>`

Specify a file to use instead of `mise.toml`

### `-g --global`

Use the global config file

Examples:

```
# Remove NODE_ENV from the current directory's config
$ mise unset NODE_ENV

# Remove NODE_ENV from the global config
$ mise unset NODE_ENV -g
```

---

---
url: /cli/unuse.md
---
# `mise unuse`

* **Usage**: `mise unuse [FLAGS] <INSTALLED_TOOL@VERSION>…`
* **Aliases**: `rm`, `remove`
* **Source code**: [`src/cli/unuse.rs`](https://github.com/jdx/mise/blob/main/src/cli/unuse.rs)

Removes installed tool versions from mise.toml

By default, this will use the `mise.toml` file that has the tool defined.
If multiple config files exist (e.g., both `mise.toml` and `mise.local.toml`),
the lowest precedence file (`mise.toml`) will be used.
See <https://mise.jdx.dev/configuration.html#target-file-for-write-operations>

In the following order:

* If `--global` is set, it will use the global config file.
* If `--path` is set, it will use the config file at the given path.
* If `--env` is set, it will use `mise.<env>.toml`.
* If `MISE_DEFAULT_CONFIG_FILENAME` is set, it will use that instead.
* If `MISE_OVERRIDE_CONFIG_FILENAMES` is set, it will the first from that list.
* Otherwise just "mise.toml" or global config if cwd is home directory.

Will also prune the installed version if no other configurations are using it.

## Arguments

### `<INSTALLED_TOOL@VERSION>…`

Tool(s) to remove

## Flags

### `-e --env <ENV>`

Create/modify an environment-specific config file like .mise.\<env>.toml

### `-g --global`

Use the global config file (`~/.config/mise/config.toml`) instead of the local one

### `-p --path <PATH>`

Specify a path to a config file or directory

If a directory is specified, it will look for a config file in that directory following the rules above.

### `--no-prune`

Do not also prune the installed version

Examples:

```
# will uninstall specific version
$ mise unuse node@18.0.0

# will uninstall specific version from global config
$ mise unuse -g node@18.0.0

# will uninstall specific version from .mise.local.toml
$ mise unuse --env local node@20

# will uninstall specific version from .mise.staging.toml
$ mise unuse --env staging node@20
```

---

---
url: /cli/upgrade.md
---
# `mise upgrade`

* **Usage**: `mise upgrade [FLAGS] [INSTALLED_TOOL@VERSION]…`
* **Aliases**: `up`
* **Source code**: [`src/cli/upgrade.rs`](https://github.com/jdx/mise/blob/main/src/cli/upgrade.rs)

Upgrades outdated tools

By default, this keeps the range specified in mise.toml. So if you have node@20 set, it will
upgrade to the latest 20.x.x version available. See the `--bump` flag to use the latest version
and bump the version in mise.toml.

This will update mise.lock if it is enabled, see <https://mise.jdx.dev/configuration/settings.html#lockfile>

## Arguments

### `[INSTALLED_TOOL@VERSION]…`

Tool(s) to upgrade
e.g.: node@20 python@3.10
If not specified, all current tools will be upgraded

## Flags

### `-i --interactive`

Display multiselect menu to choose which tools to upgrade

### `-j --jobs <JOBS>`

Number of jobs to run in parallel
\[default: 4]

### `-l --bump`

Upgrades to the latest version available, bumping the version in mise.toml

For example, if you have `node = "20.0.0"` in your mise.toml but 22.1.0 is the latest available,
this will install 22.1.0 and set `node = "22.1.0"` in your config.

It keeps the same precision as what was there before, so if you instead had `node = "20"`, it
would change your config to `node = "22"`.

### `-n --dry-run`

Just print what would be done, don't actually do it

### `-x --exclude… <INSTALLED_TOOL>`

Tool(s) to exclude from upgrading
e.g.: go python

### `--before <BEFORE>`

Only upgrade to versions released before this date

Supports absolute dates like "2024-06-01" and relative durations like "90d" or "1y".
This can be useful for reproducibility or security purposes.

This only affects fuzzy version matches like "20" or "latest".
Explicitly pinned versions like "22.5.0" are not filtered.

### `--dry-run-code`

Like --dry-run but exits with code 1 if there are outdated tools

This is useful for scripts to check if tools need to be upgraded.

### `--raw`

Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1

Examples:

```
# Upgrades node to the latest version matching the range in mise.toml
$ mise upgrade node

# Upgrades node to the latest version and bumps the version in mise.toml
$ mise upgrade node --bump

# Upgrades all tools to the latest versions
$ mise upgrade

# Upgrades all tools to the latest versions and bumps the version in mise.toml
$ mise upgrade --bump

# Just print what would be done, don't actually do it
$ mise upgrade --dry-run

# Upgrades node and python to the latest versions
$ mise upgrade node python

# Upgrade all tools except go
$ mise upgrade --exclude go

# Show a multiselect menu to choose which tools to upgrade
$ mise upgrade --interactive
```

---

---
url: /cli/use.md
---
# `mise use`

* **Usage**: `mise use [FLAGS] [TOOL@VERSION]…`
* **Aliases**: `u`
* **Source code**: [`src/cli/use.rs`](https://github.com/jdx/mise/blob/main/src/cli/use.rs)

Installs a tool and adds the version to mise.toml.

This will install the tool version if it is not already installed.
By default, this will use a `mise.toml` file in the current directory.
If multiple config files exist (e.g., both `mise.toml` and `mise.local.toml`),
the lowest precedence file (`mise.toml`) will be used.
See <https://mise.jdx.dev/configuration.html#target-file-for-write-operations>

In the following order:

* If `--global` is set, it will use the global config file.
* If `--path` is set, it will use the config file at the given path.
* If `--env` is set, it will use `mise.<env>.toml`.
* If `MISE_DEFAULT_CONFIG_FILENAME` is set, it will use that instead.
* If `MISE_OVERRIDE_CONFIG_FILENAMES` is set, it will the first from that list.
* Otherwise just "mise.toml" or global config if cwd is home directory.

Use the `--global` flag to use the global config file instead.

## Arguments

### `[TOOL@VERSION]…`

Tool(s) to add to config file

e.g.: node@20, cargo:ripgrep@latest npm:prettier@3
If no version is specified, it will default to @latest

Tool options can be set with this syntax:

```
mise use ubi:BurntSushi/ripgrep[exe=rg]
```

## Flags

### `-e --env <ENV>`

Create/modify an environment-specific config file like .mise.\<env>.toml

### `-f --force`

Force reinstall even if already installed

### `-g --global`

Use the global config file (`~/.config/mise/config.toml`) instead of the local one

### `-j --jobs <JOBS>`

Number of jobs to run in parallel
\[default: 4]

### `-n --dry-run`

Perform a dry run, showing what would be installed and modified without making changes

### `-p --path <PATH>`

Specify a path to a config file or directory

If a directory is specified, it will look for a config file in that directory following the rules above.

### `--before <BEFORE>`

Only install versions released before this date

Supports absolute dates like "2024-06-01" and relative durations like "90d" or "1y".

### `--dry-run-code`

Like --dry-run but exits with code 1 if there are changes to make

This is useful for scripts to check if tools need to be added or removed.

### `--fuzzy`

Save fuzzy version to config file

e.g.: `mise use --fuzzy node@20` will save 20 as the version
this is the default behavior unless `MISE_PIN=1`

### `--pin`

Save exact version to config file
e.g.: `mise use --pin node@20` will save 20.0.0 as the version
Set `MISE_PIN=1` to make this the default behavior

Consider using mise.lock as a better alternative to pinning in mise.toml:
<https://mise.jdx.dev/configuration/settings.html#lockfile>

### `--raw`

Directly pipe stdin/stdout/stderr from plugin to user Sets `--jobs=1`

### `--remove… <PLUGIN>`

Remove the plugin(s) from config file

Examples:

```

# run with no arguments to use the interactive selector
$ mise use

# set the current version of node to 20.x in mise.toml of current directory
# will write the fuzzy version (e.g.: 20)
$ mise use node@20

# set the current version of node to 20.x in ~/.config/mise/config.toml
# will write the precise version (e.g.: 20.0.0)
$ mise use -g --pin node@20

# sets .mise.local.toml (which is intended not to be committed to a project)
$ mise use --env local node@20

# sets .mise.staging.toml (which is used if MISE_ENV=staging)
$ mise use --env staging node@20
```

---

---
url: /cli/version.md
---
# `mise version`

* **Usage**: `mise version [-J --json]`
* **Aliases**: `v`
* **Source code**: [`src/cli/version.rs`](https://github.com/jdx/mise/blob/main/src/cli/version.rs)

Display the version of mise

Displays the version, os, architecture, and the date of the build.

If the version is out of date, it will display a warning.

## Flags

### `-J --json`

Print the version information in JSON format

Examples:

```
mise version
mise --version
mise -v
mise -V
```

---

---
url: /cli/watch.md
---
# `mise watch`

* **Usage**: `mise watch [FLAGS] [TASK] [ARGS]…`
* **Aliases**: `w`
* **Source code**: [`src/cli/watch.rs`](https://github.com/jdx/mise/blob/main/src/cli/watch.rs)

Run task(s) and watch for changes to rerun it

This command uses the `watchexec` tool to watch for changes to files and rerun the specified task(s).
It must be installed for this command to work, but you can install it with `mise use -g watchexec@latest`.

For more advanced process management (daemon management, auto-restart, readiness checks,
cron scheduling), see mise's sister project: https://pitchfork.jdx.dev

## Arguments

### `[TASK]`

Tasks to run
Can specify multiple tasks by separating with `:::`
e.g.: `mise run task1 arg1 arg2 ::: task2 arg1 arg2`

### `[ARGS]…`

Task and arguments to run

## Flags

### `--skip-deps`

Run only the specified tasks skipping all dependencies

### `-w --watch… <PATH>`

Watch a specific file or directory

By default, Watchexec watches the current directory.

When watching a single file, it's often better to watch the containing directory instead, and filter on the filename. Some editors may replace the file with a new one when saving, and some platforms may not detect that or further changes.

Upon starting, Watchexec resolves a "project origin" from the watched paths. See the help for '--project-origin' for more information.

This option can be specified multiple times to watch multiple files or directories.

The special value '/dev/null', provided as the only path watched, will cause Watchexec to not watch any paths. Other event sources (like signals or key events) may still be used.

### `-W --watch-non-recursive… <PATH>`

Watch a specific directory, non-recursively

Unlike '-w', folders watched with this option are not recursed into.

This option can be specified multiple times to watch multiple directories non-recursively.

### `-F --watch-file <PATH>`

Watch files and directories from a file

Each line in the file will be interpreted as if given to '-w'.

For more complex uses (like watching non-recursively), use the argfile capability: build a file containing command-line options and pass it to watchexec with `@path/to/argfile`.

The special value '-' will read from STDIN; this in incompatible with '--stdin-quit'.

### `-c --clear <MODE>`

Clear screen before running command

If this doesn't completely clear the screen, try '--clear=reset'.

**Choices:**

* `clear`
* `reset`

### `-o --on-busy-update <MODE>`

What to do when receiving events while the command is running

Default is to 'do-nothing', which ignores events while the command is running, so that changes that occur due to the command are ignored, like compilation outputs. You can also use 'queue' which will run the command once again when the current run has finished if any events occur while it's running, or 'restart', which terminates the running command and starts a new one. Finally, there's 'signal', which only sends a signal; this can be useful with programs that can reload their configuration without a full restart.

The signal can be specified with the '--signal' option.

**Choices:**

* `queue`
* `do-nothing`
* `restart`
* `signal`

**Default:** `do-nothing`

### `-r --restart`

Restart the process if it's still running

This is a shorthand for '--on-busy-update=restart'.

### `-s --signal <SIGNAL>`

Send a signal to the process when it's still running

Specify a signal to send to the process when it's still running. This implies '--on-busy-update=signal'; otherwise the signal used when that mode is 'restart' is controlled by '--stop-signal'.

See the long documentation for '--stop-signal' for syntax.

Signals are not supported on Windows at the moment, and will always be overridden to 'kill'. See '--stop-signal' for more on Windows "signals".

### `--stop-signal <SIGNAL>`

Signal to send to stop the command

This is used by 'restart' and 'signal' modes of '--on-busy-update' (unless '--signal' is provided). The restart behaviour is to send the signal, wait for the command to exit, and if it hasn't exited after some time (see '--timeout-stop'), forcefully terminate it.

The default on unix is "SIGTERM".

Input is parsed as a full signal name (like "SIGTERM"), a short signal name (like "TERM"), or a signal number (like "15"). All input is case-insensitive.

On Windows this option is technically supported but only supports the "KILL" event, as Watchexec cannot yet deliver other events. Windows doesn't have signals as such; instead it has termination (here called "KILL" or "STOP") and "CTRL+C", "CTRL+BREAK", and "CTRL+CLOSE" events. For portability the unix signals "SIGKILL", "SIGINT", "SIGTERM", and "SIGHUP" are respectively mapped to these.

### `--stop-timeout <TIMEOUT>`

Time to wait for the command to exit gracefully

This is used by the 'restart' mode of '--on-busy-update'. After the graceful stop signal is sent, Watchexec will wait for the command to exit. If it hasn't exited after this time, it is forcefully terminated.

Takes a unit-less value in seconds, or a time span value such as "5min 20s". Providing a unit-less value is deprecated and will warn; it will be an error in the future.

The default is 10 seconds. Set to 0 to immediately force-kill the command.

This has no practical effect on Windows as the command is always forcefully terminated; see '--stop-signal' for why.

**Default:** `10s`

### `--map-signal… <SIGNAL:SIGNAL>`

Translate signals from the OS to signals to send to the command

Takes a pair of signal names, separated by a colon, such as "TERM:INT" to map SIGTERM to SIGINT. The first signal is the one received by watchexec, and the second is the one sent to the command. The second can be omitted to discard the first signal, such as "TERM:" to not do anything on SIGTERM.

If SIGINT or SIGTERM are mapped, then they no longer quit Watchexec. Besides making it hard to quit Watchexec itself, this is useful to send pass a Ctrl-C to the command without also terminating Watchexec and the underlying program with it, e.g. with "INT:INT".

This option can be specified multiple times to map multiple signals.

Signal syntax is case-insensitive for short names (like "TERM", "USR2") and long names (like "SIGKILL", "SIGHUP"). Signal numbers are also supported (like "15", "31"). On Windows, the forms "STOP", "CTRL+C", and "CTRL+BREAK" are also supported to receive, but Watchexec cannot yet deliver other "signals" than a STOP.

### `-d --debounce <TIMEOUT>`

Time to wait for new events before taking action

When an event is received, Watchexec will wait for up to this amount of time before handling it (such as running the command). This is essential as what you might perceive as a single change may actually emit many events, and without this behaviour, Watchexec would run much too often. Additionally, it's not infrequent that file writes are not atomic, and each write may emit an event, so this is a good way to avoid running a command while a file is partially written.

An alternative use is to set a high value (like "30min" or longer), to save power or bandwidth on intensive tasks, like an ad-hoc backup script. In those use cases, note that every accumulated event will build up in memory.

Takes a unit-less value in milliseconds, or a time span value such as "5sec 20ms". Providing a unit-less value is deprecated and will warn; it will be an error in the future.

The default is 50 milliseconds. Setting to 0 is highly discouraged.

**Default:** `50ms`

### `--stdin-quit`

Exit when stdin closes

This watches the stdin file descriptor for EOF, and exits Watchexec gracefully when it is closed. This is used by some process managers to avoid leaving zombie processes around.

### `--no-vcs-ignore`

Don't load gitignores

Among other VCS exclude files, like for Mercurial, Subversion, Bazaar, DARCS, Fossil. Note that Watchexec will detect which of these is in use, if any, and only load the relevant files. Both global (like '~/.gitignore') and local (like '.gitignore') files are considered.

This option is useful if you want to watch files that are ignored by Git.

### `--no-project-ignore`

Don't load project-local ignores

This disables loading of project-local ignore files, like '.gitignore' or '.ignore' in the
watched project. This is contrasted with '--no-vcs-ignore', which disables loading of Git
and other VCS ignore files, and with '--no-global-ignore', which disables loading of global
or user ignore files, like '~/.gitignore' or '~/.config/watchexec/ignore'.

Supported project ignore files:

* Git: .gitignore at project root and child directories, .git/info/exclude, and the file pointed to by `core.excludesFile` in .git/config.
* Mercurial: .hgignore at project root and child directories.
* Bazaar: .bzrignore at project root.
* Darcs: \_darcs/prefs/boring
* Fossil: .fossil-settings/ignore-glob
* Ripgrep/Watchexec/generic: .ignore at project root and child directories.

VCS ignore files (Git, Mercurial, Bazaar, Darcs, Fossil) are only used if the corresponding
VCS is discovered to be in use for the project/origin. For example, a .bzrignore in a Git
repository will be discarded.

### `--no-global-ignore`

Don't load global ignores

This disables loading of global or user ignore files, like '~/.gitignore',
'~/.config/watchexec/ignore', or '%APPDATA%\Bazzar\2.0\ignore'. Contrast with
'--no-vcs-ignore' and '--no-project-ignore'.

Supported global ignore files

* Git (if core.excludesFile is set): the file at that path
* Git (otherwise): the first found of $XDG\_CONFIG\_HOME/git/ignore, %APPDATA%/.gitignore, %USERPROFILE%/.gitignore, $HOME/.config/git/ignore, $HOME/.gitignore.
* Bazaar: the first found of %APPDATA%/Bazzar/2.0/ignore, $HOME/.bazaar/ignore.
* Watchexec: the first found of $XDG\_CONFIG\_HOME/watchexec/ignore, %APPDATA%/watchexec/ignore, %USERPROFILE%/.watchexec/ignore, $HOME/.watchexec/ignore.

Like for project files, Git and Bazaar global files will only be used for the corresponding
VCS as used in the project.

### `--no-default-ignore`

Don't use internal default ignores

Watchexec has a set of default ignore patterns, such as editor swap files, `*.pyc`, `*.pyo`, `.DS_Store`, `.bzr`, `_darcs`, `.fossil-settings`, `.git`, `.hg`, `.pijul`, `.svn`, and Watchexec log files.

### `--no-discover-ignore`

Don't discover ignore files at all

This is a shorthand for '--no-global-ignore', '--no-vcs-ignore', '--no-project-ignore', but even more efficient as it will skip all the ignore discovery mechanisms from the get go.

Note that default ignores are still loaded, see '--no-default-ignore'.

### `--ignore-nothing`

Don't ignore anything at all

This is a shorthand for '--no-discover-ignore', '--no-default-ignore'.

Note that ignores explicitly loaded via other command line options, such as '--ignore' or '--ignore-file', will still be used.

### `-p --postpone`

Wait until first change before running command

By default, Watchexec will run the command once immediately. With this option, it will instead wait until an event is detected before running the command as normal.

### `--delay-run <DURATION>`

Sleep before running the command

This option will cause Watchexec to sleep for the specified amount of time before running the command, after an event is detected. This is like using "sleep 5 && command" in a shell, but portable and slightly more efficient.

Takes a unit-less value in seconds, or a time span value such as "2min 5s". Providing a unit-less value is deprecated and will warn; it will be an error in the future.

### `--poll <INTERVAL>`

Poll for filesystem changes

By default, and where available, Watchexec uses the operating system's native file system watching capabilities. This option disables that and instead uses a polling mechanism, which is less efficient but can work around issues with some file systems (like network shares) or edge cases.

Optionally takes a unit-less value in milliseconds, or a time span value such as "2s 500ms", to use as the polling interval. If not specified, the default is 30 seconds. Providing a unit-less value is deprecated and will warn; it will be an error in the future.

Aliased as '--force-poll'.

### `--shell <SHELL>`

Use a different shell

By default, Watchexec will use '$SHELL' if it's defined or a default of 'sh' on Unix-likes, and either 'pwsh', 'powershell', or 'cmd' (CMD.EXE) on Windows, depending on what Watchexec detects is the running shell.

With this option, you can override that and use a different shell, for example one with more features or one which has your custom aliases and functions.

If the value has spaces, it is parsed as a command line, and the first word used as the shell program, with the rest as arguments to the shell.

The command is run with the '-c' flag (except for 'cmd' on Windows, where it's '/C').

The special value 'none' can be used to disable shell use entirely. In that case, the command provided to Watchexec will be parsed, with the first word being the executable and the rest being the arguments, and executed directly. Note that this parsing is rudimentary, and may not work as expected in all cases.

Using 'none' is a little more efficient and can enable a stricter interpretation of the input, but it also means that you can't use shell features like globbing, redirection, control flow, logic, or pipes.

Examples:

Use without shell:

$ watchexec -n -- zsh -x -o shwordsplit scr

Use with powershell core:

$ watchexec --shell=pwsh -- Test-Connection localhost

Use with CMD.exe:

$ watchexec --shell=cmd -- dir

Use with a different unix shell:

$ watchexec --shell=bash -- 'echo $BASH\_VERSION'

Use with a unix shell and options:

$ watchexec --shell='zsh -x -o shwordsplit' -- scr

### `-n`

Shorthand for '--shell=none'

### `--emit-events-to <MODE>`

Configure event emission

Watchexec can emit event information when running a command, which can be used by the child
process to target specific changed files.

One thing to take care with is assuming inherent behaviour where there is only chance.
Notably, it could appear as if the `RENAMED` variable contains both the original and the new
path being renamed. In previous versions, it would even appear on some platforms as if the
original always came before the new. However, none of this was true. It's impossible to
reliably and portably know which changed path is the old or new, "half" renames may appear
(only the original, only the new), "unknown" renames may appear (change was a rename, but
whether it was the old or new isn't known), rename events might split across two debouncing
boundaries, and so on.

This option controls where that information is emitted. It defaults to 'none', which doesn't
emit event information at all. The other options are 'environment' (deprecated), 'stdio',
'file', 'json-stdio', and 'json-file'.

The 'stdio' and 'file' modes are text-based: 'stdio' writes absolute paths to the stdin of
the command, one per line, each prefixed with `create:`, `remove:`, `rename:`, `modify:`,
or `other:`, then closes the handle; 'file' writes the same thing to a temporary file, and
its path is given with the $WATCHEXEC\_EVENTS\_FILE environment variable.

There are also two JSON modes, which are based on JSON objects and can represent the full
set of events Watchexec handles. Here's an example of a folder being created on Linux:

```json
  {
```

"tags": \[
{
"kind": "path",
"absolute": "/home/user/your/new-folder",
"filetype": "dir"
},
{
"kind": "fs",
"simple": "create",
"full": "Create(Folder)"
},
{
"kind": "source",
"source": "filesystem",
}
],
"metadata": {
"notify-backend": "inotify"
}

```
  }
```

The fields are as follows:

* `tags`, structured event data.
* `tags[].kind`, which can be:

```
* 'path', along with:
  + `absolute`, an absolute path.
  + `filetype`, a file type if known ('dir', 'file', 'symlink', 'other').
* 'fs':
  + `simple`, the "simple" event type ('access', 'create', 'modify', 'remove', or 'other').
  + `full`, the "full" event type, which is too complex to fully describe here, but looks like 'General(Precise(Specific))'.
* 'source', along with:
  + `source`, the source of the event ('filesystem', 'keyboard', 'mouse', 'os', 'time', 'internal').
* 'keyboard', along with:
  + `keycode`. Currently only the value 'eof' is supported.
* 'process', for events caused by processes:
  + `pid`, the process ID.
* 'signal', for signals sent to Watchexec:
  + `signal`, the normalised signal name ('hangup', 'interrupt', 'quit', 'terminate', 'user1', 'user2').
* 'completion', for when a command ends:
  + `disposition`, the exit disposition ('success', 'error', 'signal', 'stop', 'exception', 'continued').
  + `code`, the exit, signal, stop, or exception code.
```

* `metadata`, additional information about the event.

The 'json-stdio' mode will emit JSON events to the standard input of the command, one per
line, then close stdin. The 'json-file' mode will create a temporary file, write the
events to it, and provide the path to the file with the $WATCHEXEC\_EVENTS\_FILE
environment variable.

Finally, the 'environment' mode was the default until 2.0. It sets environment variables
with the paths of the affected files, for filesystem events:

$WATCHEXEC\_COMMON\_PATH is set to the longest common path of all of the below variables,
and so should be prepended to each path to obtain the full/real path. Then:

* $WATCHEXEC\_CREATED\_PATH is set when files/folders were created
* $WATCHEXEC\_REMOVED\_PATH is set when files/folders were removed
* $WATCHEXEC\_RENAMED\_PATH is set when files/folders were renamed
* $WATCHEXEC\_WRITTEN\_PATH is set when files/folders were modified
* $WATCHEXEC\_META\_CHANGED\_PATH is set when files/folders' metadata were modified
* $WATCHEXEC\_OTHERWISE\_CHANGED\_PATH is set for every other kind of pathed event

Multiple paths are separated by the system path separator, ';' on Windows and ':' on unix.
Within each variable, paths are deduplicated and sorted in binary order (i.e. neither
Unicode nor locale aware).

This is the legacy mode, is deprecated, and will be removed in the future. The environment
is a very restricted space, while also limited in what it can usefully represent. Large
numbers of files will either cause the environment to be truncated, or may error or crash
the process entirely. The $WATCHEXEC\_COMMON\_PATH is also unintuitive, as demonstrated by the
multiple confused queries that have landed in my inbox over the years.

**Choices:**

* `environment`
* `stdio`
* `file`
* `json-stdio`
* `json-file`
* `none`

**Default:** `none`

### `--only-emit-events`

Only emit events to stdout, run no commands.

This is a convenience option for using Watchexec as a file watcher, without running any commands. It is almost equivalent to using `cat` as the command, except that it will not spawn a new process for each event.

This option requires `--emit-events-to` to be set, and restricts the available modes to `stdio` and `json-stdio`, modifying their behaviour to write to stdout instead of the stdin of the command.

### `-E --env… <KEY=VALUE>`

Add env vars to the command

This is a convenience option for setting environment variables for the command, without setting them for the Watchexec process itself.

Use key=value syntax. Multiple variables can be set by repeating the option.

### `--wrap-process <MODE>`

Configure how the process is wrapped

By default, Watchexec will run the command in a process group in Unix, and in a Job Object in Windows.

Some Unix programs prefer running in a session, while others do not work in a process group.

Use 'group' to use a process group, 'session' to use a process session, and 'none' to run the command directly. On Windows, either of 'group' or 'session' will use a Job Object.

**Choices:**

* `group`
* `session`
* `none`

**Default:** `group`

### `-N --notify`

Alert when commands start and end

With this, Watchexec will emit a desktop notification when a command starts and ends, on supported platforms. On unsupported platforms, it may silently do nothing, or log a warning.

### `--color <MODE>`

When to use terminal colours

Setting the environment variable `NO_COLOR` to any value is equivalent to `--color=never`.

**Choices:**

* `auto`
* `always`
* `never`

**Default:** `auto`

### `--timings`

Print how long the command took to run

This may not be exactly accurate, as it includes some overhead from Watchexec itself. Use the `time` utility, high-precision timers, or benchmarking tools for more accurate results.

### `-q --quiet`

Don't print starting and stopping messages

By default Watchexec will print a message when the command starts and stops. This option disables this behaviour, so only the command's output, warnings, and errors will be printed.

### `--bell`

Ring the terminal bell on command completion

### `--project-origin <DIRECTORY>`

Set the project origin

Watchexec will attempt to discover the project's "origin" (or "root") by searching for a variety of markers, like files or directory patterns. It does its best but sometimes gets it it wrong, and you can override that with this option.

The project origin is used to determine the path of certain ignore files, which VCS is being used, the meaning of a leading '/' in filtering patterns, and maybe more in the future.

When set, Watchexec will also not bother searching, which can be significantly faster.

### `--workdir <DIRECTORY>`

Set the working directory

By default, the working directory of the command is the working directory of Watchexec. You can change that with this option. Note that paths may be less intuitive to use with this.

### `-e --exts… <EXTENSIONS>`

Filename extensions to filter to

This is a quick filter to only emit events for files with the given extensions. Extensions can be given with or without the leading dot (e.g. 'js' or '.js'). Multiple extensions can be given by repeating the option or by separating them with commas.

### `-f --filter… <PATTERN>`

Filename patterns to filter to

Provide a glob-like filter pattern, and only events for files matching the pattern will be emitted. Multiple patterns can be given by repeating the option. Events that are not from files (e.g. signals, keyboard events) will pass through untouched.

### `--filter-file… <PATH>`

Files to load filters from

Provide a path to a file containing filters, one per line. Empty lines and lines starting with '#' are ignored. Uses the same pattern format as the '--filter' option.

This can also be used via the $WATCHEXEC\_FILTER\_FILES environment variable.

### `-J --filter-prog… <EXPRESSION>`

\[experimental] Filter programs.

/!\ This option is EXPERIMENTAL and may change and/or vanish without notice.

Provide your own custom filter programs in jaq (similar to jq) syntax. Programs are given an event in the same format as described in '--emit-events-to' and must return a boolean. Invalid programs will make watchexec fail to start; use '-v' to see program runtime errors.

In addition to the jaq stdlib, watchexec adds some custom filter definitions:

* 'path | file\_meta' returns file metadata or null if the file does not exist.

* 'path | file\_size' returns the size of the file at path, or null if it does not exist.

* 'path | file\_read(bytes)' returns a string with the first n bytes of the file at path. If the file is smaller than n bytes, the whole file is returned. There is no filter to read the whole file at once to encourage limiting the amount of data read and processed.

* 'string | hash', and 'path | file\_hash' return the hash of the string or file at path. No guarantee is made about the algorithm used: treat it as an opaque value.

* 'any | kv\_store(key)', 'kv\_fetch(key)', and 'kv\_clear' provide a simple key-value store. Data is kept in memory only, there is no persistence. Consistency is not guaranteed.

* 'any | printout', 'any | printerr', and 'any | log(level)' will print or log any given value to stdout, stderr, or the log (levels = error, warn, info, debug, trace), and pass the value through (so '\[1] | log("debug") | .\[]' will produce a '1' and log '\[1]').

All filtering done with such programs, and especially those using kv or filesystem access, is much slower than the other filtering methods. If filtering is too slow, events will back up and stall watchexec. Take care when designing your filters.

If the argument to this option starts with an '@', the rest of the argument is taken to be the path to a file containing a jaq program.

Jaq programs are run in order, after all other filters, and short-circuit: if a filter (jaq or not) rejects an event, execution stops there, and no other filters are run. Additionally, they stop after outputting the first value, so you'll want to use 'any' or 'all' when iterating, otherwise only the first item will be processed, which can be quite confusing!

Find user-contributed programs or submit your own useful ones at \<https://github.com/watchexec/watchexec/discussions/592>.

## Examples:

Regexp ignore filter on paths:

'all(.tags\[] | select(.kind == "path"); .absolute | test("\[.]test\[.]js$")) | not'

Pass any event that creates a file:

'any(.tags\[] | select(.kind == "fs"); .simple == "create")'

Pass events that touch executable files:

'any(.tags\[] | select(.kind == "path" && .filetype == "file"); .absolute | metadata | .executable)'

Ignore files that start with shebangs:

'any(.tags\[] | select(.kind == "path" && .filetype == "file"); .absolute | read(2) == "#!") | not'

### `-i --ignore… <PATTERN>`

Filename patterns to filter out

Provide a glob-like filter pattern, and events for files matching the pattern will be excluded. Multiple patterns can be given by repeating the option. Events that are not from files (e.g. signals, keyboard events) will pass through untouched.

### `--ignore-file… <PATH>`

Files to load ignores from

Provide a path to a file containing ignores, one per line. Empty lines and lines starting with '#' are ignored. Uses the same pattern format as the '--ignore' option.

This can also be used via the $WATCHEXEC\_IGNORE\_FILES environment variable.

### `--fs-events… <EVENTS>`

Filesystem events to filter to

This is a quick filter to only emit events for the given types of filesystem changes. Choose from 'access', 'create', 'remove', 'rename', 'modify', 'metadata'. Multiple types can be given by repeating the option or by separating them with commas. By default, this is all types except for 'access'.

This may apply filtering at the kernel level when possible, which can be more efficient, but may be more confusing when reading the logs.

**Choices:**

* `access`
* `create`
* `remove`
* `rename`
* `modify`
* `metadata`

**Default:** `create,remove,rename,modify,metadata`

### `--no-meta`

Don't emit fs events for metadata changes

This is a shorthand for '--fs-events create,remove,rename,modify'. Using it alongside the '--fs-events' option is non-sensical and not allowed.

### `--print-events`

Print events that trigger actions

This prints the events that triggered the action when handling it (after debouncing), in a human readable form. This is useful for debugging filters.

Use '-vvv' instead when you need more diagnostic information.

### `--manual`

Show the manual page

This shows the manual page for Watchexec, if the output is a terminal and the 'man' program is available. If not, the manual page is printed to stdout in ROFF format (suitable for writing to a watchexec.1 file).

Examples:

```
$ mise watch build
Runs the "build" tasks. Will re-run the tasks when any of its sources change.
Uses "sources" from the tasks definition to determine which files to watch.

$ mise watch build --glob src/**/*.rs
Runs the "build" tasks but specify the files to watch with a glob pattern.
This overrides the "sources" from the tasks definition.

$ mise watch build --clear
Extra arguments are passed to watchexec. See `watchexec --help` for details.

$ mise watch serve --watch src --exts rs --restart
Starts an api server, watching for changes to "*.rs" files in "./src" and kills/restarts the server when they change.
```

---

---
url: /cli/where.md
---
# `mise where`

* **Usage**: `mise where <TOOL@VERSION>`
* **Source code**: [`src/cli/where.rs`](https://github.com/jdx/mise/blob/main/src/cli/where.rs)

Display the installation path for a tool

The tool must be installed for this to work.

## Arguments

### `<TOOL@VERSION>`

Tool(s) to look up
e.g.: ruby@3
if "@\<PREFIX>" is specified, it will show the latest installed version
that matches the prefix
otherwise, it will show the current, active installed version

Examples:

```
# Show the latest installed version of node
# If it is is not installed, errors
$ mise where node@20
/home/jdx/.local/share/mise/installs/node/20.0.0

# Show the current, active install directory of node
# Errors if node is not referenced in any .tool-version file
$ mise where node
/home/jdx/.local/share/mise/installs/node/20.0.0
```

---

---
url: /cli/which.md
---
# `mise which`

* **Usage**: `mise which [FLAGS] [BIN_NAME]`
* **Source code**: [`src/cli/which.rs`](https://github.com/jdx/mise/blob/main/src/cli/which.rs)

Shows the path that a tool's bin points to.

Use this to figure out what version of a tool is currently active.

## Arguments

### `[BIN_NAME]`

The bin to look up

## Flags

### `-t --tool <TOOL@VERSION>`

Use a specific tool@version
e.g.: `mise which npm --tool=node@20`

### `--plugin`

Show the plugin name instead of the path

### `--version`

Show the version instead of the path

Examples:

```
$ mise which node
/home/username/.local/share/mise/installs/node/20.0.0/bin/node

$ mise which node --plugin
node

$ mise which node --version
20.0.0
```

---

---
url: /cli.md
---
# `mise`

**Usage**: `mise [FLAGS] [TASK] <SUBCOMMAND>`

* **Usage**: `mise [FLAGS] [TASK] <SUBCOMMAND>`

## Arguments

### `[TASK]`

Task to run.

Shorthand for `mise tasks run <TASK>`.

## Global Flags

### `-C --cd <DIR>`

Change directory before running command

### `-E --env… <ENV>`

Set the environment for loading `mise.<ENV>.toml`

### `-j --jobs <JOBS>`

How many jobs to run in parallel \[default: 8]

### `-q --quiet`

Suppress non-error messages

### `-v --verbose…`

Show extra output (use -vv for even more)

### `-y --yes`

Answer yes to all confirmation prompts

### `--raw`

Read/write directly to stdin/stdout/stderr instead of by line

### `--locked`

Require lockfile URLs to be present during installation

Fails if tools don't have pre-resolved URLs in the lockfile for the current platform.
This prevents API calls to GitHub, aqua registry, etc.
Can also be enabled via MISE\_LOCKED=1 or settings.locked=true

### `--silent`

Suppress all task output and mise non-error messages

## Flags

### `--no-config`

Do not load any config files

Can also use `MISE_NO_CONFIG=1`

### `--no-env`

Do not load environment variables from config files

Can also use `MISE_NO_ENV=1`

### `--no-hooks`

Do not execute hooks from config files

Can also use `MISE_NO_HOOKS=1`

### `--output <OUTPUT>`

## Subcommands

* [`mise activate [FLAGS] [SHELL_TYPE]`](/cli/activate.md)
* [`mise tool-alias [-p --plugin <PLUGIN>] [--no-header] <SUBCOMMAND>`](/cli/tool-alias.md)
* [`mise tool-alias get <PLUGIN> <ALIAS>`](/cli/tool-alias/get.md)
* [`mise tool-alias ls [--no-header] [TOOL]`](/cli/tool-alias/ls.md)
* [`mise tool-alias set <ARGS>…`](/cli/tool-alias/set.md)
* [`mise tool-alias unset <PLUGIN> [ALIAS]`](/cli/tool-alias/unset.md)
* [`mise backends <SUBCOMMAND>`](/cli/backends.md)
* [`mise backends ls`](/cli/backends/ls.md)
* [`mise bin-paths [TOOL@VERSION]…`](/cli/bin-paths.md)
* [`mise cache <SUBCOMMAND>`](/cli/cache.md)
* [`mise cache clear [PLUGIN]…`](/cli/cache/clear.md)
* [`mise cache path`](/cli/cache/path.md)
* [`mise cache prune [-v --verbose…] [--dry-run] [PLUGIN]…`](/cli/cache/prune.md)
* [`mise completion [--include-bash-completion-lib] [SHELL]`](/cli/completion.md)
* [`mise config [FLAGS] <SUBCOMMAND>`](/cli/config.md)
* [`mise config get [-f --file <FILE>] [KEY]`](/cli/config/get.md)
* [`mise config ls [FLAGS]`](/cli/config/ls.md)
* [`mise config set [-f --file <FILE>] [-t --type <TYPE>] <KEY> [VALUE]`](/cli/config/set.md)
* [`mise deactivate`](/cli/deactivate.md)
* [`mise doctor [-J --json] <SUBCOMMAND>`](/cli/doctor.md)
* [`mise doctor path [-f --full]`](/cli/doctor/path.md)
* [`mise en [-s --shell <SHELL>] [DIR]`](/cli/en.md)
* [`mise env [FLAGS] [TOOL@VERSION]…`](/cli/env.md)
* [`mise exec [FLAGS] [TOOL@VERSION]… [-- COMMAND]…`](/cli/exec.md)
* [`mise fmt [FLAGS]`](/cli/fmt.md)
* [`mise generate <SUBCOMMAND>`](/cli/generate.md)
* [`mise generate bootstrap [FLAGS]`](/cli/generate/bootstrap.md)
* [`mise generate config [-n --dry-run] [-t --tool-versions <TOOL_VERSIONS>] [PATH]`](/cli/generate/config.md)
* [`mise generate devcontainer [FLAGS]`](/cli/generate/devcontainer.md)
* [`mise generate git-pre-commit [FLAGS]`](/cli/generate/git-pre-commit.md)
* [`mise generate github-action [FLAGS]`](/cli/generate/github-action.md)
* [`mise generate task-docs [FLAGS]`](/cli/generate/task-docs.md)
* [`mise generate task-stubs [-d --dir <DIR>] [-m --mise-bin <MISE_BIN>]`](/cli/generate/task-stubs.md)
* [`mise generate tool-stub [FLAGS] <OUTPUT>`](/cli/generate/tool-stub.md)
* [`mise implode [-n --dry-run] [--config]`](/cli/implode.md)
* [`mise edit [-n --dry-run] [-t --tool-versions <TOOL_VERSIONS>] [PATH]`](/cli/edit.md)
* [`mise install [FLAGS] [TOOL@VERSION]…`](/cli/install.md)
* [`mise install-into <TOOL@VERSION> <PATH>`](/cli/install-into.md)
* [`mise latest [-i --installed] <TOOL@VERSION>`](/cli/latest.md)
* [`mise link [-f --force] <TOOL@VERSION> <PATH>`](/cli/link.md)
* [`mise lock [FLAGS] [TOOL]…`](/cli/lock.md)
* [`mise ls [FLAGS] [INSTALLED_TOOL]…`](/cli/ls.md)
* [`mise ls-remote [--all] [-J --json] [TOOL@VERSION] [PREFIX]`](/cli/ls-remote.md)
* [`mise mcp`](/cli/mcp.md)
* [`mise outdated [FLAGS] [TOOL@VERSION]…`](/cli/outdated.md)
* [`mise plugins [FLAGS] <SUBCOMMAND>`](/cli/plugins.md)
* [`mise plugins install [FLAGS] [NEW_PLUGIN] [GIT_URL]`](/cli/plugins/install.md)
* [`mise plugins link [-f --force] <NAME> [DIR]`](/cli/plugins/link.md)
* [`mise plugins ls [-o --outdated] [-u --urls]`](/cli/plugins/ls.md)
* [`mise plugins ls-remote [-u --urls] [--only-names]`](/cli/plugins/ls-remote.md)
* [`mise plugins uninstall [-a --all] [-p --purge] [PLUGIN]…`](/cli/plugins/uninstall.md)
* [`mise plugins update [-j --jobs <JOBS>] [PLUGIN]…`](/cli/plugins/update.md)
* [`mise prepare [FLAGS] [PROVIDER]`](/cli/prepare.md)
* [`mise prune [FLAGS] [INSTALLED_TOOL]…`](/cli/prune.md)
* [`mise registry [FLAGS] [NAME]`](/cli/registry.md)
* [`mise reshim [-f --force]`](/cli/reshim.md)
* [`mise run [FLAGS]`](/cli/run.md)
* [`mise search [FLAGS] [NAME]`](/cli/search.md)
* [`mise self-update [FLAGS] [VERSION]`](/cli/self-update.md)
* [`mise set [FLAGS] [ENV_VAR]…`](/cli/set.md)
* [`mise settings [FLAGS] [SETTING] [VALUE] <SUBCOMMAND>`](/cli/settings.md)
* [`mise settings add [-l --local] <SETTING> [VALUE]`](/cli/settings/add.md)
* [`mise settings get [-l --local] <SETTING>`](/cli/settings/get.md)
* [`mise settings ls [FLAGS] [SETTING]`](/cli/settings/ls.md)
* [`mise settings set [-l --local] <SETTING> [VALUE]`](/cli/settings/set.md)
* [`mise settings unset [-l --local] <KEY>`](/cli/settings/unset.md)
* [`mise shell [FLAGS] <TOOL@VERSION>…`](/cli/shell.md)
* [`mise shell-alias [--no-header] <SUBCOMMAND>`](/cli/shell-alias.md)
* [`mise shell-alias get <shell_alias>`](/cli/shell-alias/get.md)
* [`mise shell-alias ls [--no-header]`](/cli/shell-alias/ls.md)
* [`mise shell-alias set <shell_alias> [COMMAND]`](/cli/shell-alias/set.md)
* [`mise shell-alias unset <shell_alias>`](/cli/shell-alias/unset.md)
* [`mise sync <SUBCOMMAND>`](/cli/sync.md)
* [`mise sync node [FLAGS]`](/cli/sync/node.md)
* [`mise sync python [--pyenv] [--uv]`](/cli/sync/python.md)
* [`mise sync ruby [--brew]`](/cli/sync/ruby.md)
* [`mise tasks [FLAGS] [TASK] <SUBCOMMAND>`](/cli/tasks.md)
* [`mise tasks add [FLAGS] <TASK> [-- RUN]…`](/cli/tasks/add.md)
* [`mise tasks deps [--dot] [--hidden] [TASKS]…`](/cli/tasks/deps.md)
* [`mise tasks edit [-p --path] <TASK>`](/cli/tasks/edit.md)
* [`mise tasks info [-J --json] <TASK>`](/cli/tasks/info.md)
* [`mise tasks ls [FLAGS]`](/cli/tasks/ls.md)
* [`mise tasks run [FLAGS] [TASK] [ARGS]…`](/cli/tasks/run.md)
* [`mise tasks validate [--errors-only] [--json] [TASKS]…`](/cli/tasks/validate.md)
* [`mise test-tool [FLAGS] [TOOLS]…`](/cli/test-tool.md)
* [`mise tool [FLAGS] <TOOL>`](/cli/tool.md)
* [`mise tool-stub <FILE> [ARGS]…`](/cli/tool-stub.md)
* [`mise trust [FLAGS] [CONFIG_FILE]`](/cli/trust.md)
* [`mise uninstall [FLAGS] [INSTALLED_TOOL@VERSION]…`](/cli/uninstall.md)
* [`mise unset [-f --file <FILE>] [-g --global] [ENV_KEY]…`](/cli/unset.md)
* [`mise unuse [FLAGS] <INSTALLED_TOOL@VERSION>…`](/cli/unuse.md)
* [`mise upgrade [FLAGS] [INSTALLED_TOOL@VERSION]…`](/cli/upgrade.md)
* [`mise use [FLAGS] [TOOL@VERSION]…`](/cli/use.md)
* [`mise version [-J --json]`](/cli/version.md)
* [`mise watch [FLAGS] [TASK] [ARGS]…`](/cli/watch.md)
* [`mise where <TOOL@VERSION>`](/cli/where.md)
* [`mise which [FLAGS] [BIN_NAME]`](/cli/which.md)

---

---
url: /about.md
---
# About

`mise` (pronounced "meez") or "mise-en-place" is a development environment setup tool.
The name refers to a French culinary phrase that roughly translates to "setup" or "put in place".
The idea is that before one begins cooking, they should have all their utensils and ingredients
ready to go in their place.

`mise` does the same for your projects. Using its `mise.toml` config file,
you'll have a consistent way to setup and interact with your projects no matter what
language they're written in.

Its functionality is grouped into 3 categories described below.

`mise` installs and manages dev tools/runtimes like node, python, or terraform both
simplifying installing these tools and allowing you to specify which version of these
tools to use in different projects. `mise` supports [hundreds](/plugins.md) of dev tools.

`mise` manages environment variables letting you specify configuration like
`AWS_ACCESS_KEY_ID` that may differ between projects. It can also be used to
automatically activate a [Python virtualenv](/lang/python) when entering projects too.

`mise` is a task runner that can be used to share common tasks within
a project among developers and make things like running tasks on file changes
easy.

## Contact

`mise` was initially created by [Jeff Dickey](https://jdx.dev). The goal is
to make local development of software easy and consistent across languages. Jeff
has spent many years building dev tools and thinking about the problems that `mise`
addresses.

This project is simply a labor of love. Jeff created it because he wanted to make
your life as a developer easier. We hope you find it useful. Feedback is a massive
driver for us. If you have anything positive or negative to say-even if it's just
to say hi-please reach out to me either on [Twitter](https://twitter.com/jdxcode),
[Mastodon](https://fosstodon.org/@jdx), [Discord](https://discord.gg/UBa7pJUN7Z),
or `jdx at this domain`.

---

---
url: /dev-tools/backends/aqua.md
---
# Aqua Backend

[Aqua](https://aquaproj.github.io/) tools may be used natively in mise. aqua is the ideal backend
to use for new tools since they don't require plugins, they work on windows, they offer security
features in addition to checksums. aqua installs also show more progress bars, which is nice.

You do not need to separately install aqua. The aqua CLI is not used in mise at all. What is used is
the [aqua registry](https://github.com/aquaproj/aqua-registry) which is a bunch of yaml files that get compiled into the mise binary on release.
Here's an example of one of these files: [`aqua:hashicorp/terraform`](https://github.com/aquaproj/aqua-registry/blob/main/pkgs/hashicorp/terraform/registry.yaml).
mise has a reimplementation of aqua that knows how to work with these files to install tools.

As of this writing, aqua is relatively new to mise and because a lot of tools are being converted from
asdf to aqua, there may be some configuration in aqua tools that need to be tightened up. I put some
common issues below and would strongly recommend contributing changes back to the aqua registry if you
notice problems. The maintainer is super responsive and great to work with.

If all else fails, you can disable aqua entirely with [`MISE_DISABLE_BACKENDS=aqua`](/configuration/settings.html#disable_backends).

Currently aqua tools don't support setting environment variables or doing more than simply downloading
binaries though (and I'm not sure this functionality would ever get added), so some tools will likely
always require plugins like asdf/vfox.

The code for this is inside the mise repository at [`./src/backend/aqua.rs`](https://github.com/jdx/mise/blob/main/src/backend/aqua.rs).

## Usage

The following installs the latest version of ripgrep and sets it as the active version on PATH:

```sh
$ mise use -g aqua:BurntSushi/ripgrep
$ rg --version
ripgrep 14.1.1
```

The version will be set in `~/.config/mise/config.toml` with the following format:

```toml
[tools]
"aqua:BurntSushi/ripgrep" = "latest"
```

Some tools will default to use aqua if they're specified in [registry/](https://github.com/jdx/mise/blob/main/registry/)
to use the aqua backend. To see these tools, run `mise registry | grep aqua:`.

## Tool Options

### `symlink_bins`

Some tools bundle dependencies that you may not want exposed on PATH. For example, `aws-cli` bundles
Python, which can conflict with your intended Python version.

Setting `symlink_bins = true` creates a filtered bin directory containing symlinks only to the binaries
explicitly defined in the aqua registry, preventing bundled dependencies from being exposed.

```toml
[tools]
aws-cli = { version = "latest", symlink_bins = true }
```

When enabled:

* Only binaries defined in the aqua registry's `files` field are exposed (e.g., `aws` and `aws_completer` for aws-cli)
* A `.mise-bins` subdirectory is created with symlinks to these specific binaries
* Bundled dependencies like Python are not added to PATH

## Settings

## Security Verification

Aqua backend supports multiple security verification methods to ensure the integrity and authenticity of downloaded tools. mise provides **native Rust implementation** for all verification methods, eliminating the need for external CLI tools like `cosign`, `slsa-verifier`, or `gh`.

### GitHub Artifact Attestations

GitHub Artifact Attestations provide cryptographic proof that artifacts were built by specific GitHub Actions workflows. mise verifies these attestations natively to ensure the authenticity and integrity of downloaded tools.

**Requirements:**

* The tool must have `github_artifact_attestations` configuration in the aqua registry for attestations to be verified
* No external tools required - verification is handled natively by mise

**Configuration:**

```bash
# Enable/disable GitHub artifact attestations verification (default: true)
export MISE_AQUA_GITHUB_ATTESTATIONS=true
```

**Registry Configuration Example:**

```yaml
packages:
  - type: github_release
    repo_owner: cli
    repo_name: cli
    github_artifact_attestations:
      signer_workflow: cli/cli/.github/workflows/deployment.yml
```

### Cosign Verification

mise natively verifies Cosign signatures without requiring the `cosign` CLI tool to be installed.

**Configuration:**

```bash
# Enable/disable Cosign verification (default: true)
export MISE_AQUA_COSIGN=true

# Pass extra arguments to the verification process
export MISE_AQUA_COSIGN_EXTRA_ARGS="--key /path/to/key.pub"
```

### SLSA Provenance Verification

mise natively verifies SLSA (Supply-chain Levels for Software Artifacts) provenance without requiring the `slsa-verifier` CLI tool.

**Configuration:**

```bash
# Enable/disable SLSA verification (default: true)
export MISE_AQUA_SLSA=true
```

### Other Security Methods

Aqua also supports:

* **Minisign verification**: Uses minisign for signature verification
* **Checksum verification**: Verifies SHA256/SHA512/SHA1/MD5 checksums (always enabled)

### Verification Process

During tool installation, mise will:

1. Download the tool and any signature/attestation files
2. Perform native verification using the configured methods
3. Display verification status with progress indicators
4. Abort installation if any verification fails

**Example output during installation:**

```
✓ Downloaded cli/cli v2.50.0
✓ GitHub artifact attestations verified
✓ Tool installed successfully
```

### Troubleshooting

If verification fails:

1. **Check network connectivity**: Verification requires downloading attestation data
2. **Verify tool configuration**: Ensure the aqua registry has correct verification settings
3. **Disable specific verification**: Temporarily disable problematic verification methods
4. **Enable debug logging**: Use `MISE_DEBUG=1` to see detailed verification logs

**Common issues:**

* **No attestations found**: The tool may not have attestations configured in the registry
* **Verification timeout**: Network issues or slow attestation services
* **Certificate validation**: Clock skew or certificate chain issues

To disable all verification temporarily:

```bash
export MISE_AQUA_GITHUB_ATTESTATIONS=false
export MISE_AQUA_COSIGN=false
export MISE_AQUA_SLSA=false
export MISE_AQUA_MINISIGN=false
```

## Common aqua issues

Here's some common issues I've seen when working with aqua tools.

### Supported env missing

The aqua registry defines supported envs for each tool of the os/arch. I've noticed some of these
are simply missing os/arch combos that are in fact supported—possibly because it was added after
the registry was created for that tool.

The fix is simple, just edit the `supported_envs` section of `registry.yaml` for the tool in question.

### Using `version_filter` instead of `version_prefix`

This is a weird one that causes weird issues in mise. In general in mise we like versions like
`1.2.3` with no decoration like `v1.2.3` or `cli-v1.2.3`. This consistency not only makes `mise.toml`
cleaner but, it also helps make things like `mise up` function right because it's able to parse it as
semver without dealing with a bunch of edge-cases.

Really if you notice aqua tools are giving you versions that aren't simple triplets, it's worth fixing.

One common thing I've seen is registries using a `version_filter` expression like `Version startsWith "Version startsWith "atlascli/""`.

This ultimately causes the version to be `atlascli/1.2.3` which is not what we want. The fix is to use
`version_prefix` instead of `version_filter` and just put the prefix in the `version_prefix` field.
In this example, it would be `atlascli/`. mise will automatically strip this out and add it back in,
which it can't do with `version_filter`.

---

---
url: /asdf-legacy-plugins.md
---
# asdf (Legacy) Plugins

::: warning
asdf plugins are considered legacy. For new tools, prefer [vfox plugins](/dev-tools/backends/vfox.html) which are written in Lua, work cross-platform (including Windows), and have access to built-in modules. See the [feature comparison](/dev-tools/backends/asdf.html#feature-comparison-asdf-vs-vfox) and [hook migration table](/dev-tools/backends/asdf.html#hook-migration-asdf-to-vfox) for details.
:::

mise maintains compatibility with the asdf plugin ecosystem through its asdf backend. These plugins are considered legacy because they have limitations compared to mise's modern plugin system.

## What are asdf (Legacy) Plugins?

asdf plugins are shell script-based plugins that follow the asdf plugin specification. They were the original way to extend tool management in the asdf ecosystem and are now supported by mise for backward compatibility.

## Limitations

asdf plugins have several limitations compared to mise's modern plugin system:

* **Platform Support**: Only work on Linux and macOS (no Windows support)
* **Performance**: Shell script execution is slower than mise's native backends
* **Features**: Limited compared to modern backends like aqua, github, or tool/backend plugins
* **Maintenance**: Harder to maintain and debug
* **Security**: Less secure than sandboxed modern backends

## When to Use asdf (Legacy) Plugins

Only use asdf plugins when:

* The tool is not available through modern backends (aqua, github, etc.)
* You need compatibility with existing asdf workflows
* The tool requires complex shell-based installation logic that can't be handled by modern backends

**For new tools, consider these alternatives first:**

1. [aqua backend](dev-tools/backends/aqua.md) - Preferred for GitHub releases
2. [github backend](dev-tools/backends/github.md) - Simple GitHub releases
3. [Language package managers](dev-tools/backends/) - npm, pipx, cargo, gem, etc.
4. [backend plugins](backend-plugin-development.md) - Enhanced plugins with backend methods
5. [tool plugins](tool-plugin-development.md) - Hook-based cross-platform plugins

## Installing asdf (Legacy) Plugins

### From the Registry

Most popular asdf plugins are available through mise's registry:

```bash
# Install from registry shorthand
mise use postgres@15

# This is equivalent to
mise use asdf:mise-plugins/mise-postgres@15
```

### From Git Repository

```bash
# Install plugin directly from repository
mise plugin install <plugin-name> <git-url>

# Example: PostgreSQL plugin
mise plugin install postgres https://github.com/mise-plugins/mise-postgres
```

### Manual Installation

```bash
# Add plugin manually
mise plugin add postgres https://github.com/mise-plugins/mise-postgres

# Install tool version
mise install postgres@15.0.0

# Use the tool
mise use postgres@15.0.0
```

## Plugin Structure

asdf plugins follow this directory structure:

```
plugin-name/
├── bin/
│   ├── list-all          # List all available versions
│   ├── download          # Download source code/binary
│   ├── install           # Install the tool
│   ├── latest-stable     # Get latest stable version [optional]
│   ├── help.overview     # Plugin description [optional]
│   ├── help.deps         # Plugin dependencies [optional]
│   ├── help.config       # Plugin configuration [optional]
│   ├── help.links        # Plugin links [optional]
│   ├── list-legacy-filenames  # Legacy version files [optional]
│   ├── parse-legacy-file # Parse legacy version files [optional]
│   ├── post-plugin-add   # Post plugin addition hook [optional]
│   ├── post-plugin-update # Post plugin update hook [optional]
│   ├── pre-plugin-remove # Pre plugin removal hook [optional]
│   └── exec-env          # Set execution environment [optional]
├── lib/                  # Shared library code [optional]
└── README.md
```

## Required Scripts

### bin/list-all

Lists all available versions of the tool:

```bash
#!/usr/bin/env bash
# List all available versions
curl -s https://api.github.com/repos/owner/repo/releases |
  grep '"tag_name":' |
  sed -E 's/.*"([^"]+)".*/\1/' |
  sort -V
```

### bin/download

Downloads the tool source/binary:

```bash
#!/usr/bin/env bash
set -e

# Input variables from mise
# ASDF_INSTALL_TYPE (version or ref)
# ASDF_INSTALL_VERSION (version number or git ref)
# ASDF_INSTALL_PATH (where to install)
# ASDF_DOWNLOAD_PATH (where to download)

version="$ASDF_INSTALL_VERSION"
download_path="$ASDF_DOWNLOAD_PATH"

# Download logic here
curl -Lo "$download_path/archive.tar.gz" \
  "https://github.com/owner/repo/archive/v${version}.tar.gz"
```

### bin/install

Installs the tool:

```bash
#!/usr/bin/env bash
set -e

# Input variables from mise
# ASDF_INSTALL_TYPE (version or ref)
# ASDF_INSTALL_VERSION (version number or git ref)
# ASDF_INSTALL_PATH (where to install)
# ASDF_DOWNLOAD_PATH (where source is downloaded)

install_path="$ASDF_INSTALL_PATH"
download_path="$ASDF_DOWNLOAD_PATH"

# Extract and install
cd "$download_path"
tar -xzf archive.tar.gz --strip-components=1
make install PREFIX="$install_path"
```

## Optional Scripts

### bin/exec-env

Set environment variables when executing tools:

```bash
#!/usr/bin/env bash

# Set environment variables
export TOOL_HOME="$ASDF_INSTALL_PATH"
export PATH="$ASDF_INSTALL_PATH/bin:$PATH"
```

### bin/latest-stable

Get the latest stable version:

```bash
#!/usr/bin/env bash
curl -s https://api.github.com/repos/owner/repo/releases/latest |
  grep '"tag_name":' |
  sed -E 's/.*"([^"]+)".*/\1/'
```

### bin/list-legacy-filenames

List legacy version file names:

```bash
#!/usr/bin/env bash
echo ".tool-version"
echo ".tool-versions"
```

### bin/parse-legacy-file

Parse legacy version files:

```bash
#!/usr/bin/env bash
cat "$1" | head -n 1
```

## Environment Variables

asdf plugins have access to these environment variables:

* `ASDF_INSTALL_TYPE` - `version` or `ref`
* `ASDF_INSTALL_VERSION` - Version number or git ref
* `ASDF_INSTALL_PATH` - Installation directory
* `ASDF_DOWNLOAD_PATH` - Download directory
* `ASDF_PLUGIN_PATH` - Plugin directory
* `ASDF_PLUGIN_PREV_REF` - Previous git ref (for updates)
* `ASDF_PLUGIN_POST_REF` - New git ref (for updates)
* `ASDF_CMD_FILE` - Path to executable being run

## Best Practices

### Error Handling

```bash
#!/usr/bin/env bash
set -euo pipefail  # Exit on error, undefined vars, pipe failures

# Check dependencies
command -v curl >/dev/null 2>&1 || {
  echo "Error: curl is required" >&2
  exit 1
}
```

### Cross-Platform Compatibility

```bash
#!/usr/bin/env bash

# Detect platform
case "$(uname -s)" in
  Darwin*) platform="darwin" ;;
  Linux*)  platform="linux" ;;
  *)       echo "Unsupported platform" >&2; exit 1 ;;
esac

case "$(uname -m)" in
  x86_64) arch="amd64" ;;
  arm64)  arch="arm64" ;;
  *)      echo "Unsupported architecture" >&2; exit 1 ;;
esac
```

### Version Parsing

```bash
#!/usr/bin/env bash

# Parse semantic version
parse_version() {
  local version="$1"
  # Remove 'v' prefix if present
  version="${version#v}"
  echo "$version"
}
```

## Testing Plugins

### Local Development

```bash
# Link plugin for development
mise plugin add my-plugin /path/to/local/plugin

# Test basic functionality
mise list-all my-plugin
mise install my-plugin@1.0.0
mise which my-plugin
```

### Debugging

```bash
# Enable debug mode
export MISE_DEBUG=1

# Or use --verbose flag
mise install --verbose my-plugin@1.0.0
```

## Example Plugin

Here's a minimal example for a fictional tool:

```bash
#!/usr/bin/env bash
# bin/list-all
curl -s "https://api.github.com/repos/example/tool/releases" |
  grep '"tag_name":' |
  sed -E 's/.*"v([^"]+)".*/\1/' |
  sort -V
```

```bash
#!/usr/bin/env bash
# bin/download
set -e
version="$ASDF_INSTALL_VERSION"
platform=$(uname -s | tr '[:upper:]' '[:lower:]')
arch=$(uname -m)

url="https://github.com/example/tool/releases/download/v${version}/tool-${platform}-${arch}.tar.gz"
curl -fSL "$url" -o "$ASDF_DOWNLOAD_PATH/tool.tar.gz"
```

```bash
#!/usr/bin/env bash
# bin/install
set -e
cd "$ASDF_DOWNLOAD_PATH"
tar -xzf tool.tar.gz
cp tool "$ASDF_INSTALL_PATH/bin/"
chmod +x "$ASDF_INSTALL_PATH/bin/tool"
```

## Migration Path

Consider migrating from asdf plugins to modern alternatives:

1. **Check if tool is available in [aqua registry](https://aquaproj.github.io/aqua-registry/)**
2. **Use [github backend](dev-tools/backends/github.md) for simple GitHub releases**
3. **Create a [mise plugin](tool-plugin-development.md) for complex tools** - use the [mise-tool-plugin-template](https://github.com/jdx/mise-tool-plugin-template) for a quick start
4. **Use language-specific package managers** (npm, pipx, cargo, gem)

## Community Resources

* **[asdf Plugin List](https://github.com/asdf-vm/asdf-plugins)** - Official asdf plugin registry
* **[mise-plugins Organization](https://github.com/mise-plugins)** - Community-maintained plugins
* **[Plugin Template (asdf)](https://github.com/asdf-vm/asdf-plugin-template)** - Template for creating asdf plugins
* **[Plugin Template (mise)](https://github.com/jdx/mise-tool-plugin-template)** - Modern template for creating mise plugins with Lua

## Security Considerations

asdf plugins execute arbitrary shell scripts, which poses security risks:

* **Only install plugins from trusted sources**
* **Review plugin code before installation**
* **Avoid plugins with complex installation scripts when possible**
* **Consider using modern backends for better security**

## Next Steps

* [Explore modern backends](dev-tools/backends/) for better alternatives
* [Learn about backend plugins](backend-plugin-development.md) for enhanced functionality
* [Learn about tool plugins](tool-plugin-development.md) for cross-platform support
* [Check the registry](registry.md) for available tools

---

---
url: /dev-tools/backends/asdf.md
---
# asdf Backend

::: warning
asdf plugins are considered legacy. For new tools, prefer [vfox plugins](/dev-tools/backends/vfox.html) which are written in Lua, work cross-platform (including Windows), and have access to built-in modules for HTTP, JSON, HTML parsing, and more.
:::

`asdf` is the original backend for mise.

It relies on asdf plugins for each tool. asdf plugins are more risky to use because they're typically written by a single developer unrelated to the tool vendor. They also generally do not function on Windows because they're written
in bash which is often not available on Windows and the scripts generally are not written to be cross-platform.

asdf plugins are not used for tools inside the [registry](https://github.com/jdx/mise/blob/main/registry/) whenever possible. Sometimes it is not possible to use more secure backends like aqua/github because tools have complex install setups or need to export env vars.

All of these are hosted in the mise-plugins org to secure the supply chain so you do not need to rely on plugins maintained by anyone except me.

Because of the extra complexity of asdf tools and security concerns we are actively moving tools in
the registry away from asdf where possible to backends like aqua and github which don't require plugins.
That said, not all tools can function with github/aqua if they have a unique installation process or
need to set env vars other than `PATH`.

## Feature Comparison: asdf vs vfox

| Feature                         | asdf Plugins       | vfox Plugins         |
| ------------------------------- | ------------------ | -------------------- |
| **Language**                    | Bash scripts       | Lua                  |
| **Windows Support**             | ❌                 | ✅                   |
| **Built-in HTTP module**        | ❌ (requires curl) | ✅                   |
| **Built-in JSON module**        | ❌ (requires jq)   | ✅                   |
| **Built-in HTML parsing**       | ❌                 | ✅                   |
| **Built-in archive extraction** | ❌                 | ✅                   |
| **Built-in semver module**      | ❌                 | ✅                   |
| **Built-in logging**            | ❌                 | ✅                   |
| **Post-install hooks**          | ❌                 | ✅                   |
| **Security attestations**       | ❌                 | ✅ (cosign, SLSA)    |
| **Multi-tool plugins**          | ❌                 | ✅ (backend plugins) |
| **Lock file support**           | ❌                 | ✅                   |
| **Rolling version checksums**   | ❌                 | ✅                   |

## Hook Migration: asdf to vfox

| asdf Script                 | vfox Hook                | Notes                                                            |
| --------------------------- | ------------------------ | ---------------------------------------------------------------- |
| `bin/list-all`              | `Available`              | Return structured version objects instead of plain text          |
| `bin/download`              | `PreInstall`             | Return URL and checksum; mise handles the download               |
| `bin/install`               | `PostInstall`            | Runs after mise downloads and extracts the tool                  |
| `bin/exec-env`              | `EnvKeys`                | Return structured key/value pairs instead of `export` statements |
| `bin/list-legacy-filenames` | `PLUGIN.legacyFilenames` | Set in `metadata.lua` instead of a script                        |
| `bin/parse-legacy-file`     | `ParseLegacyFile`        | Return structured result instead of plain text                   |

## Writing asdf (legacy) plugins for mise

See the asdf documentation for more information on [writing plugins](https://asdf-vm.com/plugins/create.html).

---

---
url: /dev-tools/backend_architecture.md
---
# Backend Architecture

Understanding how mise's backend system works can help you choose the right backend for your tools and troubleshoot issues when they arise. Most users don't need to explicitly choose backends since the [mise registry](../registry.md) defines smart defaults, but understanding the system helps when you need specific tools or want to optimize performance.

## What are Backends?

Backends are mise's way of supporting different tool installation methods. Each backend knows how to:

* List available versions of tools
* Download and install specific versions
* Set up the environment for installed tools
* Manage tool lifecycles (updates, uninstalls)

Think of backends as "adapters" that let mise work with different package managers and installation systems.

## The Backend Trait System

All backends implement a common interface (called a "trait" in Rust), which means they all provide the same basic functionality:

```rust
pub trait Backend {
    async fn list_remote_versions(&self) -> Result<Vec<String>>;
    async fn install_version(&self, ctx: &InstallContext, tv: &ToolVersion) -> Result<()>;
    async fn uninstall_version(&self, tv: &ToolVersion) -> Result<()>;
    // ... other methods
}
```

This design allows mise to treat all backends uniformly while each backend handles the specifics of its installation method.

## Backend Types

### Core Tools

Built directly into mise, written in Rust for performance and reliability:

* **Node.js, Python, Ruby, Go, Java, etc.** - Native implementations
* **Benefits**: Fastest performance, no external dependencies, best integration
* **Drawbacks**: Require much more maintenance; new core tool contributions are likely to be rejected unless they're for very popular tools like Node.js, Python, or Go

::: info
Core tools like Node.js and Java are implemented as backends even though they represent single tools. This consistent backend architecture allows mise to handle all tools uniformly, whether they're complex ecosystems or individual tools.
:::

### Language Package Managers

Leverage existing language ecosystems:

* **npm** - npm packages (`npm:prettier`, `npm:typescript`)
* **pipx** - Python packages (`pipx:black`, `pipx:poetry`)
* **cargo** - Rust crates (`cargo:ripgrep`, `cargo:fd-find`)
* **gem** - Ruby gems (`gem:bundler`, `gem:rails`)
* **go** - Go modules (`go:github.com/golangci/golangci-lint/cmd/golangci-lint`)

### Universal Installers

#### aqua - Comprehensive Package Manager

Registry-based package manager with strong security features:

* **Usage**: `aqua:golangci/golangci-lint`
* **Requirements**: Tools must be available in the [aqua registry](https://github.com/aquaproj/aqua-registry)
* **Sources**: Primarily GitHub but supports other sources through registry configuration
* **Security**: Comprehensive checksums, signatures, and verification

#### ubi - Universal Binary Installer (Deprecated)

::: warning
The ubi backend is deprecated. Use the [github backend](/dev-tools/backends/github) instead.
:::

Zero-configuration installer that works with any GitHub/GitLab repository following standard conventions:

* **Usage**: `ubi:BurntSushi/ripgrep` → migrate to `github:BurntSushi/ripgrep`
* **Requirements**: Repository must follow standard release tarball conventions
* **Sources**: Primarily GitHub releases, with GitLab support (rarely used in mise)
* **Configuration**: None required - automatically detects and downloads appropriate binaries

### Plugin Systems

Support for external plugin ecosystems:

* **Tool Plugins** - Hook-based plugins for single tools (`my-tool`) - a superset of vfox plugins functionality
* **asdf Plugins** - Legacy plugin ecosystem (`asdf:postgres`, `asdf:redis`) - generally Linux/macOS only
* **Backend Plugins** - Enhanced plugins using the `plugin:tool` format (`my-plugin:some-tool`) - enables private/custom tools with backend methods

## How Backend Selection Works

When you specify a tool, mise determines the backend using this priority:

1. **Explicit backend**: `mise use aqua:golangci/golangci-lint`
2. **Environment variable override**: `MISE_BACKENDS_<TOOL>` (see below)
3. **Registry lookup**: `mise use golangci-lint` → checks registry for default backend
4. **Core tools**: `mise use node` → uses built-in core backend
5. **Fallback**: If not found, suggests available backends

The [mise registry](../registry.md) defines a priority order for which backend to use for each tool, so typically end-users don't need to know which backend to choose unless they want tools not available in the registry or want to override the default selection.

### Environment Variable Overrides

You can override the backend for any tool using the `MISE_BACKENDS_<TOOL>` environment variable pattern. The tool name is converted to SHOUTY\_SNAKE\_CASE (uppercase with underscores replacing hyphens).

```bash
# Use vfox backend for php
export MISE_BACKENDS_PHP='vfox:mise-plugins/vfox-php'
mise install php@latest
```

### Registry System

The [registry](../registry.md) (`mise registry`) maps short names to full backend specifications with a preferred priority order:

```toml
# ~/.config/mise/config.toml
[tool_alias]
go = "core:go"                    # Use core backend
terraform = "aqua:hashicorp/terraform"  # Use aqua backend
```

## Backend Capabilities Comparison

| Feature                   | Core | npm/pipx/cargo | aqua | ubi | Backend Plugins | Tool Plugins (vfox) | asdf Plugins (legacy) |
| ------------------------- | ---- | -------------- | ---- | --- | --------------- | ------------------- | --------------------- |
| **Speed**                 | ✅   | ⚠️             | ✅   | ✅  | ⚠️              | ⚠️                  | ⚠️                    |
| **Security**              | ✅   | ⚠️             | ✅   | ⚠️  | ⚠️              | ⚠️                  | ⚠️                    |
| **Windows Support**       | ✅   | ✅             | ✅   | ✅  | ✅              | ✅                  | ❌                    |
| **Env Var Support**       | ✅   | ❌             | ❌   | ❌  | ✅              | ✅                  | ✅                    |
| **Custom Scripts**        | ✅   | ❌             | ❌   | ❌  | ✅              | ✅                  | ✅                    |
| **Built-in Modules**      | ✅   | ❌             | ❌   | ❌  | ✅              | ✅                  | ❌                    |
| **Security Attestations** | ❌   | ❌             | ✅   | ❌  | ✅              | ✅                  | ❌                    |
| **Multi-tool Plugins**    | ❌   | ❌             | ❌   | ❌  | ✅              | ❌                  | ❌                    |
| **Progress/Logging**      | ✅   | ✅             | ✅   | ✅  | ✅              | ✅                  | ❌                    |

## When to Use Each Backend

### Use **Core Tools** when

* Available for your tool (check the [registry](../registry.md))
* You want the fastest performance
* You're using major programming languages

Core tools should generally always be used when available, as they provide the best performance and integration with mise.

### Use **Language Package Managers** when

* Installing tools specific to that language ecosystem
* The tool is primarily distributed through that package manager
* You want automatic dependency management

### Use **aqua** when

* Installing pre-compiled binaries or static packages (no compilation needed)
* You want comprehensive security features (checksums, signatures)
* You need Windows support
* The tool is already available in the [aqua registry](https://github.com/aquaproj/aqua-registry)
* You're willing to contribute tools to the aqua registry for tools not yet available

### Use **github** when

* Installing pre-compiled binaries from GitHub releases
* The repository follows standard conventions for release tarballs
* You want zero configuration - no registry setup required
* You need simple, fast binary installation
* The tool doesn't require complex build processes or environment setup

::: info
The `ubi` backend still works but is deprecated in favor of `github`. Replace `ubi:owner/repo` with `github:owner/repo`.
:::

### Use **Backend Plugins** when

* You need to manage multiple tools with one plugin
* Want enhanced backend methods for better performance
* Need the `plugin:tool` format for flexibility
* Working with custom or private tools
* Want modern plugin architecture with backend methods

### Use **Tool Plugins** when

* Creating traditional single-tool plugins
* Need fine-grained control over installation hooks
* Want to use the vfox hook system
* Tool requires complex installation logic or build processes
* Tool requires environment variable setup (like `JAVA_HOME`, `GOROOT`, etc.)
* You need cross-platform support including Windows

### Use **asdf Plugins** when

* Tool requires compilation from source
* Need complex installation logic or build processes
* Tool requires environment variable setup (like `JAVA_HOME`, `GOROOT`, etc.)
* No other backend supports the tool
* Migrating from existing asdf setup
* Working on Linux/macOS (no Windows support)

## Backend Dependencies

Some backends have dependencies on others:

```mermaid
graph TD
    A[npm backend] --> B[Node.js]
    C[pipx backend] --> D[pipx]
    E[cargo backend] --> F[Rust]
    G[gem backend] --> H[Ruby]
```

mise automatically handles these dependencies, installing Node.js before npm tools, pipx before pipx tools, etc.

## Configuration and Overrides

### Disable Backends

```toml
# ~/.config/mise/config.toml
[settings]
disable_backends = ["asdf", "vfox"] # Don't use these backends
```

### Force Backend for Tool

```toml
# mise.toml
[tools]
"core:node" = "20"     # Explicitly use core backend
"aqua:yarn" = "latest" # Use aqua backend instead of default (vfox)
```

### Backend-Specific Settings

Some backends support additional configuration:

```toml
# mise.toml
[tools]
python = { version = "3.12", virtualenv = ".venv" }  # Core backend options
black = { version = "latest", python = "3.12" }      # pipx backend options
```

## Troubleshooting Backend Issues

### Debug Backend Selection

```bash
mise doctor                   # Check backend configuration
mise tool python              # See which backend is used for a tool
mise config get tools         # Verify tool configurations
```

---

---
url: /backend-plugin-development.md
---
# Backend Plugin Development

::: tip
The [mise-backend-plugin-template](https://github.com/jdx/mise-backend-plugin-template) provides a ready-to-use starting point with LuaCATS type definitions, stylua formatting, and hk linting pre-configured.
:::

Backend plugins in mise use enhanced backend methods to manage multiple tools using the `plugin:tool` format. These plugins are perfect for package managers, tool families, and custom installations that need to manage multiple related tools.

## What are Backend Plugins?

Backend plugins extend the standard vfox plugin system with enhanced backend methods. They support:

* **Multiple Tools**: One plugin can manage multiple tools. For example, `vfox-npm` is the plugin which could install different types of tools like `prettier`, `eslint`, and other npm packages
* **Cross-Platform Support**: Works on Windows, macOS, and Linux
* **Flexible Architecture**: Modern plugin system with dedicated backend methods for enhanced functionality

## Plugin Architecture

Backend plugins are generally a git repository but can also be a directory (via `mise link`).

Backend plugins are implemented in Lua (version 5.1 at the moment). They use three main backend methods implemented as individual files:

* `hooks/backend_list_versions.lua` - Lists available versions for a tool
* `hooks/backend_install.lua` - Installs a specific version of a tool
* `hooks/backend_exec_env.lua` - Sets up environment variables for a tool

## Backend Methods

### BackendListVersions

Lists available versions for a tool:

```lua
function PLUGIN:BackendListVersions(ctx)
    local tool = ctx.tool
    local versions = {}

    -- Your logic to fetch versions for the tool
    -- Example: query an API, parse a registry, etc.

    return {versions = versions}
end
```

> \[!WARNING]
> **Version sorting**: The versions returned by `BackendListVersions` should be in ascending order (oldest to newest), sorted semantically (version `3.10.0` should not come before `3.2.0`). Mise does not apply any additional sorting to the versions returned by this method.

### BackendInstall

Installs a specific version of a tool:

```lua
function PLUGIN:BackendInstall(ctx)
    local tool = ctx.tool
    local version = ctx.version
    local install_path = ctx.install_path
    local download_path = ctx.download_path
    local options = ctx.options

    -- Your logic to install the tool
    -- Example: download files, extract archives, etc.
    -- Access custom options via options["key"] or options.key

    return {}
end
```

### BackendExecEnv

Sets up environment variables for a tool:

```lua
function PLUGIN:BackendExecEnv(ctx)
    local install_path = ctx.install_path
    local options = ctx.options

    -- Your logic to set up environment variables
    -- Example: add bin directories to PATH
    -- Access custom options via options["key"] or options.key

    return {
        env_vars = {
            {key = "PATH", value = install_path .. "/bin"}
        }
    }
end
```

## Creating a Backend Plugin

### Using the Template Repository

Use the dedicated [mise-backend-plugin-template](https://github.com/jdx/mise-backend-plugin-template) for creating backend plugins:

```bash
# Option 1: Use GitHub's template feature (recommended)
# Visit https://github.com/jdx/mise-backend-plugin-template
# Click "Use this template" to create your repository

# Option 2: Clone and modify
git clone https://github.com/jdx/mise-backend-plugin-template my-backend-plugin
cd my-backend-plugin
rm -rf .git
git init
```

The template includes:

* Complete backend plugin structure with all required hooks
* Modern development tooling (hk, stylua, luacheck, actionlint)
* Comprehensive documentation and examples
* CI/CD setup with GitHub Actions
* Multiple implementation patterns for different backend types

### 1. Plugin Structure

Create a directory with this structure:

```
my-backend-plugin/
├── metadata.lua                    # Plugin metadata
├── hooks/
│   ├── backend_list_versions.lua   # BackendListVersions hook
│   ├── backend_install.lua         # BackendInstall hook
│   └── backend_exec_env.lua        # BackendExecEnv hook
└── Injection.lua                   # Runtime injection (auto-generated)
```

### 2. Basic metadata.lua

```lua
PLUGIN = {
    name = "vfox-npm",
    version = "1.0.0",
    description = "Backend plugin for npm packages",
    author = "Your Name"
}
```

## Real-World Example: vfox-npm

Here's the complete implementation of the vfox-npm plugin that manages npm packages:

### metadata.lua

```lua
PLUGIN = {
    name = "vfox-npm",
    version = "1.0.0",
    description = "Backend plugin for npm packages",
    author = "jdx"
}
```

### hooks/backend\_list\_versions.lua

```lua
function PLUGIN:BackendListVersions(ctx)
    local cmd = require("cmd")
    local json = require("json")

    local result = cmd.exec("npm view " .. ctx.tool .. " versions --json")
    local versions = json.decode(result)

    return {versions = versions}
end
```

### hooks/backend\_install.lua

```lua
function PLUGIN:BackendInstall(ctx)
    local tool = ctx.tool
    local version = ctx.version
    local install_path = ctx.install_path

    -- Install the package directly using npm install
    local cmd = require("cmd")
    local npm_cmd = "npm install " .. tool .. "@" .. version .. " --no-package-lock --no-save --silent"
    local result = cmd.exec(npm_cmd, {cwd = install_path})

    -- If we get here, the command succeeded
    return {}
end
```

### hooks/backend\_exec\_env.lua

```lua
function PLUGIN:BackendExecEnv(ctx)
    local file = require("file")
    return {
        env_vars = {
            {key = "PATH", value = file.join_path(ctx.install_path, "node_modules", ".bin")}
        }
    }
end
```

## Usage Example

The plugin name doesn't have to match the repository name. The backend prefix will match whatever name the backend plugin was installed as.

```bash
# Install the plugin
mise plugin install vfox-npm https://github.com/jdx/vfox-npm

# List available versions
mise ls-remote vfox-npm:prettier

# Install a specific version
mise install vfox-npm:prettier@3.0.0

# Use in a project
mise use vfox-npm:prettier@latest

# Execute the tool
mise exec -- prettier --help
```

> **Tip**: This naming flexibility could potentially be used to have a very complex plugin backend that would behave differently based on what it was named. For example, you could install the same plugin with different names to configure different behaviors or access different tool registries.

## Context Variables

Backend plugins receive context through the `ctx` parameter passed to each hook function:

### BackendListVersions Context

| Variable   | Description   | Example      |
| ---------- | ------------- | ------------ |
| `ctx.tool` | The tool name | `"prettier"` |

### BackendInstall Context

| Variable            | Description            | Example                                                            |
| ------------------- | ---------------------- | ------------------------------------------------------------------ |
| `ctx.tool`          | The tool name          | `"prettier"`                                                       |
| `ctx.version`       | The requested version  | `"3.0.0"`                                                          |
| `ctx.install_path`  | Installation directory | `"/home/user/.local/share/mise/installs/vfox-npm-prettier/3.0.0"`  |
| `ctx.download_path` | Download directory     | `"/home/user/.local/share/mise/downloads/vfox-npm-prettier/3.0.0"` |

### BackendExecEnv Context

| Variable           | Description            | Example                                                           |
| ------------------ | ---------------------- | ----------------------------------------------------------------- |
| `ctx.tool`         | The tool name          | `"prettier"`                                                      |
| `ctx.version`      | The requested version  | `"3.0.0"`                                                         |
| `ctx.install_path` | Installation directory | `"/home/user/.local/share/mise/installs/vfox-npm-prettier/3.0.0"` |

## Testing Your Plugin

### Local Development

```bash
# Link your plugin for development
mise plugin link my-plugin /path/to/my-plugin

# Test listing versions
mise ls-remote my-plugin:some-tool

# Test installation
mise use my-plugin:some-tool@1.0.0

# Test execution
mise exec -- some-tool --version
```

### Debug Mode

Use debug mode to see detailed plugin execution:

```bash
mise --debug install my-plugin:some-tool@1.0.0
```

## Best Practices

### Error Handling

Provide more meaningful error messages:

```lua
function PLUGIN:BackendListVersions(ctx)
    local tool = ctx.tool

    -- Validate tool name
    if not tool or tool == "" then
        error("Tool name cannot be empty")
    end

    -- Execute command with error checking
    local cmd = require("cmd")
    local result = cmd.exec("npm view " .. tool .. " versions --json 2>/dev/null")
    if not result or result:match("npm ERR!") then
        error("Failed to fetch versions for " .. tool .. ": " .. (result or "no output"))
    end

    -- Parse JSON response
    local json = require("json")
    local success, npm_versions = pcall(json.decode, result)
    if not success or not npm_versions then
        error("Failed to parse versions for " .. tool)
    end

    -- Return versions or error if none found
    local versions = {}
    if type(npm_versions) == "table" then
        for i = #npm_versions, 1, -1 do
            table.insert(versions, npm_versions[i])
        end
    end

    if #versions == 0 then
        error("No versions found for " .. tool)
    end

    return {versions = versions}
end
```

### Regex Parsing

Parse versions with regex:

```lua
local function parse_version(version_string)
    -- Remove prefixes like 'v' or 'release-'
    return version_string:gsub("^v", ""):gsub("^release%-", "")
end
```

### Path Handling

Use cross-platform path handling:

```lua
local function join_path(...)
    local sep = package.config:sub(1,1) -- Get OS path separator
    return table.concat({...}, sep)
end

local bin_path = join_path(install_path, "bin")
```

### Cross-Platform Commands

Handle different operating systems:

```lua
local function create_dir(path)
    local cmd = RUNTIME.osType == "Windows" and "mkdir" or "mkdir -p"
    os.execute(cmd .. " " .. path)
end
```

## Advanced Features

### Conditional Installation

Different installation logic based on tool or version:

```lua
function PLUGIN:BackendInstall(ctx)
    local tool = ctx.tool
    local version = ctx.version
    local install_path = ctx.install_path

    -- Create install directory
    os.execute("mkdir -p " .. install_path)

    if tool == "special-tool" then
        -- Special installation logic
        local cmd = require("cmd")
        local npm_cmd = "cd " .. install_path .. " && npm install " .. tool .. "@" .. version .. " --no-package-lock --no-save --silent 2>/dev/null"
        local result = cmd.exec(npm_cmd)
        if result:match("npm ERR!") then
            error("Failed to install " .. tool .. "@" .. version)
        end
    else
        -- Default installation logic
        local cmd = require("cmd")
        local npm_cmd = "cd " .. install_path .. " && npm install " .. tool .. "@" .. version .. " --no-package-lock --no-save --silent 2>/dev/null"
        local result = cmd.exec(npm_cmd)
        if result:match("npm ERR!") then
            error("Failed to install " .. tool .. "@" .. version)
        end
    end

    return {}
end
```

### Environment Detection

vfox automatically injects runtime information into your plugin:

```lua
function PLUGIN:BackendInstall(ctx)
    -- Platform-specific installation using injected RUNTIME object
    if RUNTIME.osType == "darwin" then
        -- macOS installation logic
    elseif RUNTIME.osType == "linux" then
        -- Linux installation logic
    elseif RUNTIME.osType == "windows" then
        -- Windows installation logic
    end

    return {}
end
```

The `RUNTIME` object provides:

* `RUNTIME.osType`: Operating system type (Windows, Linux, Darwin)
* `RUNTIME.archType`: Architecture (amd64, arm64, etc.)
* `RUNTIME.version`: vfox runtime version
* `RUNTIME.pluginDirPath`: Plugin directory path

### Multiple Environment Variables

Set multiple environment variables:

```lua
function PLUGIN:BackendExecEnv(ctx)
    -- Add node_modules/.bin to PATH for npm-installed binaries
    local bin_path = ctx.install_path .. "/node_modules/.bin"
    return {
        env_vars = {
            {key = "PATH", value = bin_path},
            {key = ctx.tool:upper() .. "_HOME", value = ctx.install_path},
            {key = ctx.tool:upper() .. "_VERSION", value = ctx.version}
        }
    }
end
```

## Performance Optimization

### Caching

TODO: We need caching support for [Shared Lua modules](plugin-lua-modules.md).

## Next Steps

* [Start with the backend plugin template](https://github.com/jdx/mise-backend-plugin-template)
* [Learn about Tool Plugin Development](tool-plugin-development.md)
* [Explore available Lua modules](plugin-lua-modules.md)
* [Publishing your plugin](plugin-publishing.md)
* [View the vfox-npm plugin source](https://github.com/jdx/vfox-npm)

---

---
url: /dev-tools/backends.md
---
# Backends

Backends are package managers or ecosystems that mise uses to install [tools](/dev-tools/index.html) and [plugins](/plugins.html). Each backend can install and manage multiple tools from its ecosystem. For example, the `npm` backend can install many different tools like `npm:prettier`, or the `pipx` backend can install tools like `pipx:black`. This allows mise to support a wide variety of tools and languages by leveraging different package managers and their ecosystems.

When you run the [`mise use`](/cli/use.html) command, mise will determine the appropriate backend to use based on the tool you are trying to manage. The backend will then handle the installation, configuration, and any other necessary steps to ensure the tool is ready to use.

For more details on how backends fit into mise's overall design, see the [backend architecture documentation](/dev-tools/backend_architecture.html).

Below is a list of the available backends in mise:

* [asdf](/dev-tools/backends/asdf) (provide tools through [plugins](/plugins.html))
* [aqua](/dev-tools/backends/aqua)
* [cargo](/dev-tools/backends/cargo)
* [conda](/dev-tools/backends/conda)&#x20;
* [dotnet](/dev-tools/backends/dotnet)&#x20;
* [forgejo](/dev-tools/backends/forgejo)
* [gem](/dev-tools/backends/gem)
* [github](/dev-tools/backends/github)
* [gitlab](/dev-tools/backends/gitlab)
* [go](/dev-tools/backends/go)
* [http](/dev-tools/backends/http)
* [npm](/dev-tools/backends/npm)
* [pipx](/dev-tools/backends/pipx)
* [s3](/dev-tools/backends/s3)&#x20;
* [spm](/dev-tools/backends/spm)&#x20;
* [ubi](/dev-tools/backends/ubi)
* [vfox](/dev-tools/backends/vfox) (provide tools through [plugins](/plugins.html))
* [custom backends](/backend-plugin-development) (build your own backend with a plugin which itself provides many tools)

---

---
url: /lang/bun.md
---
# Bun

`mise` can be used to install and manage multiple versions of [bun](https://bun.sh/) on the same system.

> The following are instructions for using the bun mise core plugin. This is used when there isn't a
> git plugin installed named "bun".

The code for this is inside the mise repository at
[`./src/plugins/core/bun.rs`](https://github.com/jdx/mise/blob/main/src/plugins/core/bun.rs).

## Usage

The following installs bun and makes it the global default:

```sh
mise use -g bun@0.7     # install bun 0.7.x
mise use -g bun@latest  # install latest bun
```

See available versions with `mise ls-remote bun`.

> \[!NOTE]
> Avoid using `bun upgrade` to upgrade bun as `mise` will not be aware of the change.

---

---
url: /cache-behavior.md
---
# Cache Behavior

mise makes use of caching in many places in order to be efficient. The details about how long to keep
cache for should eventually all be configurable. There may be gaps in the current behavior where
things are hardcoded, but I'm happy to add more settings to cover whatever config is needed.

Below I explain the behavior it uses around caching. If you're seeing behavior where things don't appear
to be updating, this is a good place to start.

## Plugin/Runtime Cache

Each plugin has a cache that's stored in `~/$MISE_CACHE_DIR/<PLUGIN>`. It stores
the list of versions available for that plugin (`mise ls-remote <PLUGIN>`), the idiomatic filenames (see below),
the list of aliases, the bin directories within each runtime installation, and the result of
running `exec-env` after the runtime was installed.

Remote versions are updated daily by default. The file is zlib messagepack, if you want to view it you can
run the following (requires [msgpack-cli](https://github.com/msgpack/msgpack-cli)).

```sh
cat ~/$MISE_CACHE_DIR/node/remote_versions.msgpack.z | perl -e 'use Compress::Raw::Zlib;my $d=new Compress::Raw::Zlib::Inflate();my $o;undef $/;$d->inflate(<>,$o);print $o;' | msgpack-cli decode
```

Note that the caching of `exec-env` may be problematic if the script isn't simply exporting
static values. The vast majority of `exec-env` scripts only export static values.

Caching `exec-env` massively improved the performance of mise since it requires calling bash
every time mise is initialized.

## Environment Caching

For more advanced caching needs (including dynamic environment providers like secret managers),
mise provides the [`env_cache`](/configuration/settings.html#env_cache) setting. When enabled,
mise caches the computed environment to disk with encryption.

```toml
# ~/.config/mise/config.toml
[settings]
env_cache = true
env_cache_ttl = "1h"  # optional, default is 1h
```

Cache invalidation happens automatically when:

* Any config file changes (mise.toml, .tool-versions, etc.)
* Tool versions change
* Settings change
* mise version changes
* TTL expires (configurable via `env_cache_ttl`)
* Any watched files change (from modules or `_.source` directives)

Env plugins (vfox modules) can declare themselves cacheable by returning `{cacheable = true, watch_files = [...]}`
from their `MiseEnv` hook. See [Env Plugin Development](/env-plugin-development.html) for details.

Directives can opt out of caching by setting `cacheable = false`:

```toml
[env]
TIMESTAMP = { value = "{{ now() }}", cacheable = false }
_.source = { file = "dynamic.sh", cacheable = false }
```

## Cache auto-pruning

mise will automatically delete old files in its cache directory (configured with [`cache_prune_age`](https://mise.jdx.dev/configuration/settings.html#cache_prune_age)). Much of
the contents are also ignored by mise if they are >24 hours old or a few days. For this reason, it's likely wasteful to store this directory in CI jobs.

---

---
url: /dev-tools/backends/cargo.md
---
# Cargo Backend

You may install packages directly from [Cargo Crates](https://crates.io/) even if there
isn't an asdf plugin for it.

The code for this is inside the mise repository at [`./src/backend/cargo.rs`](https://github.com/jdx/mise/blob/main/src/backend/cargo.rs).

## Dependencies

This relies on having `cargo` installed. You can either install it on your
system via [rustup](https://rustup.rs/):

```sh
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

Or you can install it via mise:

```sh
mise use -g rust
```

## Usage

The following installs the latest version of [eza](https://crates.io/crates/eza) and
sets it as the active version on PATH:

```sh
$ mise use -g cargo:eza
$ eza --version
eza - A modern, maintained replacement for ls
v0.17.1 [+git]
https://github.com/eza-community/eza
```

The version will be set in `~/.config/mise/config.toml` with the following format:

```toml
[tools]
"cargo:eza" = "latest"
```

### Using Git

You can install any package from a Git repository using the `mise` command. This allows you to
install a particular tag, branch, or commit revision:

```sh
# Install a specific tag
mise use cargo:https://github.com/username/demo@tag:<release_tag>

# Install the latest from a branch
mise use cargo:https://github.com/username/demo@branch:<branch_name>

# Install a specific commit revision
mise use cargo:https://github.com/username/demo@rev:<commit_hash>
```

This will execute a `cargo install` command with the corresponding Git options.

## Settings

Set these with `mise settings set [VARIABLE] [VALUE]` or by setting the environment variable listed.

## Tool Options

The following [tool-options](/dev-tools/#tool-options) are available for the `cargo` backend—these
go in `[tools]` in `mise.toml`.

### `features`

Install additional components (passed as `cargo install --features`):

```toml
[tools]
"cargo:cargo-edit" = { version = "latest", features = "add" }
```

### `default-features`

Disable default features (passed as `cargo install --no-default-features`):

```toml
[tools]
"cargo:cargo-edit" = { version = "latest", default-features = false }
```

### `bin`

Select the CLI bin name to install when multiple are available (passed as `cargo install --bin`):

```toml
[tools]
"cargo:https://github.com/username/demo" = { version = "tag:v1.0.0", bin = "demo" }
```

### `crate`

Select the crate name to install when multiple are available (passed as
`cargo install --git=<repo> <crate>`):

```toml
[tools]
"cargo:https://github.com/username/demo" = { version = "tag:v1.0.0", crate = "demo" }
```

### `locked`

Use Cargo.lock (passes `cargo install --locked`) when building CLI. This is the default behavior,
pass `false` to disable:

```toml
[tools]
"cargo:https://github.com/username/demo" = { version = "latest", locked = false }
```

---

---
url: /rtx.md
---
# Coming from rtx

`mise` was formerly called `rtx`. The name was changed to avoid confusion with Nvidia's
line of graphics cards. This wasn't a legal issue, but just general confusion. When
people first hear about the project or see it posted they wouldn't realize it was talking
about a CLI tool. It was a bit difficult to search for on Google but also places like
Twitter and in Slack searches and things. This was the top complaint about `rtx` and
many people were fairly outspoken about disliking the name for this reason. `rtx` was
supposed to be a working title that I intended to change but never got around to doing.
This change should've happened earlier when there were fewer users and I apologize for
not having done that sooner knowing that this was likely going to be necessary at some point.

To upgrade from `rtx` to `mise`, simply install `mise` and it should automatically
migrate its internal directories, moving `~/.local/share/rtx/installs/*` to `~/.local/share/mise/installs/*`
(skipping python & ruby which cannot be moved), `~/.local/share/rtx/plugins` to `~/.local/share/mise/plugins`,
and `~/.config/rtx` to `~/.config/mise` (if the destination does not exist). Python and Ruby
installs will need to be reinstalled with `mise install`.

`mise` will continue reading `.rtx.toml` files for some time but that eventually will
be deprecated so please rename them to `mise.toml`. `mise` will not read from `RTX_*`
env vars so those will need to be changed to `MISE_*`. Anything using a local `.rtx` or
`.config/rtx` directory will need to be moved to `.mise`/`.config/mise`.

I apologize if this migration is not seamless however I think moving to a name that
is easier to search for and avoids confusion is better for everyone. I also apologize
for it being abrupt—I simply couldn't think of a way to "slow roll" this change out
while also keeping the GitHub repo.

Users of the `rtx-action` GitHub action will need to switch to `mise-action` (and also
bump the major version to v2).

If you build infrastructure where users may still be calling `rtx activate` in their
shell rc scripts, you can create a symlink `ln -s /path/to/mise /path/to/rtx` so
`rtx activate` still functions.

For <https://mise.run>, we're using `~/.local/bin/mise`
as the executable PATH instead of the old directory `~/.local/share/rtx/bin/mise`
to keep things a bit cleaner. You can still use the old style if you like by setting
`MISE_INSTALL_PATH`.

If you use shims, a `mise reshim` will be necessary to update the shims.

Thanks for trying out my little CLI tool by the way. I find this project incredibly
fulfilling to work on and seeing people have success using. I have
tremendous passion for building dev tools and the ideas in `mise` are the product of
me thinking about building a tool like this for over a decade.

If you aren't happy with `mise` or the way I'm running this project, even in a tiny way,
please let me know. You can [contact me privately](/about#contact) if you like. I certainly
won't take offense and I would prefer you say something rather than nothing. Otherwise
I'll never know.

---

---
url: /dev-tools/comparison-to-asdf.md
---
# Comparison to asdf

mise can be used as a drop-in replacement for asdf. It supports the same `.tool-versions` files that
you may have used with asdf and can use asdf plugins through
the [asdf backend](/dev-tools/backends/asdf.html).

It will not, however, reuse existing asdf directories
(so you'll need to either reinstall them or move them), and 100% compatibility is not a design goal.
That said,
if you're coming from asdf-bash (0.15 and below), mise actually
has [fewer breaking changes than asdf-go (0.16 and above)](https://asdf-vm.com/guide/upgrading-to-v0-16.html)
despite 100% compatibility not being a design goal of mise.

Casual users coming from asdf have generally found mise to just be a faster, easier to use asdf.

:::tip
Make sure you have a look at [environments](/environments/) and [tasks](/tasks/) which
are major portions of mise that have no asdf equivalent.
:::

## Migrate from asdf to mise

If you're moving from asdf to mise, please
review [#how-do-i-migrate-from-asdf](/faq.html#how-do-i-migrate-from-asdf) for guidance.

## asdf in go (0.16+)

asdf has gone through a rewrite in go. Because this is quite new as of this writing (2025-01-01),
I'm going to keep information about 0.16+ asdf versions (which I call "asdf-go" vs "asdf-bash") in
this section and the rest of this doc will apply to asdf-bash (0.15 and below).

In terms of performance, mise is still faster than the go asdf, however the difference is much
closer. asdf is likely fast enough that the difference in overhead between asdf-go and mise may not
even be enough to notice for you—after all there are plenty of people still using asdf-bash that
claim they don't even notice how slow it is (don't ask me how):

![asdf vs mise exec performance comparison chart](./asdf-mise-exec-perf.jpg)

I don't think performance is a good enough reason to switch though now that asdf-go is a thing. It's
a reason, but it's a minor one. The improved security in mise, better DX, and lack of reliance on
shims are all more important than performance.

Given they went through the trouble of rewriting asdf—that's also an indication they want to keep
working on it (which is awesome that they're doing that btw). This does mean that some of what's
written here may go out of date if they address some of the problems
with asdf.

## Supply chain security

asdf plugins are not secure. This is explained
in [SECURITY.md](https://github.com/jdx/mise/blob/main/SECURITY.md), but the quick explanation is
that asdf plugins involve shell code which can essentially do anything on your machine. It's
dangerous code. What's worse is asdf plugins are rarely written by the tool vendor (who you need to
trust anyway to use the tool), which means for every asdf plugin you use you'll be trusting a random
developer to not go rogue and to not get hacked themselves and publish changes to a plugin with an
exploit.

mise still uses asdf plugins for some tools, but we're actively reducing that count as well as
moving things into the [mise-plugins org](https://github.com/mise-plugins). It looks like asdf has a
similar model with their asdf-community org, but it isn't. asdf gives plugin authors commit access
to their plugin in [asdf-community](https://github.com/asdf-community) when they move it in, which I
feel like defeats the purpose of having a dedicated org in the first place. By the end of 2025 I
would like for there to no longer be any asdf plugins in the registry that aren't owned by me.

I've also been adopting extra security verification steps when vendors offer that ability such as
gpg verification on node installs, and native Cosign/SLSA/Minisign/GitHub attestation verification for aqua tools.

## UX

![CleanShot 2024-01-28 at 12 36 20@2x](https://github.com/jdx/mise-docs/assets/216188/47f381d7-1566-4b78-9260-3b85a21dd6ec)

Some commands are the same in asdf but others have been changed. Everything that's possible
in asdf should be possible in mise but may use slightly different syntax. mise has more forgiving
commands,
such as using fuzzy-matching, e.g.: `mise install node@20`. While in asdf you *can* run
`asdf install node latest:20`, you can't use `latest:20` in a `.tool-versions` file or many other
places.
In `mise` you can use fuzzy-matching everywhere.

asdf requires several steps to install a new runtime if the plugin isn't installed, e.g.:

```sh
asdf plugin add node
asdf install node latest:20
asdf local node latest:20
```

In `mise` this can all be done in a single step which installs the plugin, installs the runtime,
and sets the version:

```sh
mise use node@20
```

If you have an existing `.tool-versions` file, or `.mise.toml`, you can install all plugins
and runtimes with a single command:

```sh
mise install
```

I've found asdf to be particularly rigid and difficult to learn. It also made strange decisions like
having `asdf list all` but `asdf latest --all` (why is one a flag and one a positional argument?).
`mise` makes heavy use of aliases so you don't need to remember if it's `mise plugin add node` or
`mise plugin install node`. If I can guess what you meant, then I'll try to get mise to respond
in the right way.

That said, there are a lot of great things about asdf. It's the best multi-runtime manager out there
and I've really been impressed with the plugin system. Most of the design decisions the authors made
were very good. I really just have 2 complaints: the shims and the fact it's written in Bash.

## Performance

asdf made (what I consider) a poor design decision to use shims that go between a call to a runtime
and the runtime itself. e.g.: when you call `node` it will call an asdf shim file
`~/.asdf/shims/node`,
which then calls `asdf exec`, which then calls the correct version of node.

These shims have terrible performance, adding ~120ms to every runtime call. `mise activate` does not
use shims and instead
updates `PATH` so that it doesn't have any overhead when simply calling binaries. These shims are
the main reason that I wrote this. Note that in the demo GIF at the top of this README
that `mise` isn't actually used when calling `node -v` for this reason. The performance is
identical to running node without using mise.

I don't think it's possible for asdf to fix these issues. The author of asdf did a great writeup
of [performance problems](https://stratus3d.com/blog/2022/08/11/asdf-performance/). asdf is written
in bash which certainly makes it challenging to be performant, however I think the real problem is
the
shim design. I don't think it's possible to fix that without a complete rewrite.

mise does call an internal command `mise hook-env` every time the directory has changed, but because
it's written in Rust, this is very quick—taking ~10ms on my machine. 4ms if there are no changes,
14ms if it's
a full reload.

tl;dr: asdf adds overhead (~120ms) when calling a runtime, mise adds a small amount of overhead (~
5ms)
when the prompt loads.

## Windows support

asdf does not run on Windows at all. With mise, tools using non-asdf backends can support Windows.
Of course, this means the tool
vendor must provide Windows binaries but if they do, and the backend isn't asdf, the tool should
work on Windows.

## Security

asdf plugins are insecure. They typically are written by individuals with no ties to the vendors
that provide the underlying tool.
Where possible, mise does not use asdf plugins and instead uses backends like aqua and github which do
not require separate plugins.

Aqua tools include native Cosign/SLSA/Minisign/GitHub attestation verification built into mise.
See [SECURITY](https://github.com/jdx/mise/blob/main/SECURITY.md) for more information.

## Command Compatibility

In nearly all places you can use the exact syntax that works in asdf, however this likely won't
show up in the help or CLI reference. If you're coming from asdf and comfortable with that way of
working you can almost always use the same syntax with mise, e.g.:

```sh
mise install node 20.0.0
mise local node 20.0.0
```

UPDATE (2025-01-01): asdf-go (0.16+) actually got rid of `asdf global|local` entirely in favor of
`asdf set` which we can't support since we already have a command named `mise set`. mise command
compatibility will likely not be as good with asdf-go 0.16+.

It's not recommended though. You almost always want to modify config files and install things so
`mise use node@20` saves an extra command. Also, the "@" in the command is preferred since it allows
you to install multiple tools at once: `mise use|install node@20 node@18`. Also, there are edge
cases
where it's not possible—or at least very challenging—for us to definitively know which syntax is
being
used and so we default to mise-style. While there aren't many of these, asdf-compatibility is done
as a "best-effort" in order to make transitioning from asdf feel familiar for those users who can
rely on their muscle memory. Ensuring asdf-syntax works with everything is not a design goal.

## Extra backends

mise has support for backends other than asdf plugins. For example you can install CLIs
directly from cargo and npm:

```sh
mise use -g cargo:ripgrep@14
mise use -g npm:prettier@3
```

---

---
url: /dev-tools/backends/conda.md
---
# Conda Backend&#x20;

You may install packages directly from [conda-forge](https://conda-forge.org/) and other
Anaconda channels without needing conda or mamba installed.

This backend fetches pre-built packages from the anaconda.org API and extracts them directly,
making it a lightweight way to install conda packages as standalone CLI tools.

The code for this is inside the mise repository at [`./src/backend/conda.rs`](https://github.com/jdx/mise/blob/main/src/backend/conda.rs).

## Dependencies

None. Unlike other conda tools, this backend does not require conda, mamba, or micromamba
to be installed. It downloads and extracts packages directly from anaconda.org.

## Usage

The following installs the latest version of [ruff](https://anaconda.org/conda-forge/ruff)
and sets it as the active version on PATH:

```sh
$ mise use -g conda:ruff
$ ruff --version
ruff 0.8.0
```

The version will be set in `~/.config/mise/config.toml` with the following format:

```toml
[tools]
"conda:ruff" = "latest"
```

### Specifying a Version

```sh
mise use -g conda:ruff@0.7.0
```

### Using a Different Channel

By default, packages are installed from `conda-forge`. You can specify a different channel:

```sh
mise use -g "conda:ruff[channel=bioconda]"
```

Or in `mise.toml`:

```toml
[tools]
"conda:ruff" = { version = "latest", channel = "bioconda" }
```

## Platform Support

The conda backend automatically selects the appropriate package for your platform:

| Platform    | Conda Subdir  |
| ----------- | ------------- |
| Linux x64   | linux-64      |
| Linux ARM64 | linux-aarch64 |
| macOS x64   | osx-64        |
| macOS ARM64 | osx-arm64     |
| Windows x64 | win-64        |

If a platform-specific package is not available, the backend will fall back to `noarch` packages.

## Settings

Set these with `mise settings set [VARIABLE] [VALUE]` or by setting the environment variable listed.

## Tool Options

The following [tool-options](/dev-tools/#tool-options) are available for the `conda` backend—these
go in `[tools]` in `mise.toml`.

### `channel`

Override the conda channel for a specific package:

```toml
[tools]
"conda:bioconductor-deseq2" = { version = "latest", channel = "bioconda" }
```

## Common Channels

* `conda-forge` - Community-maintained packages (default)
* `bioconda` - Bioinformatics packages
* `nvidia` - NVIDIA CUDA packages

## Limitations

* Only installs single packages, not full conda environments with dependencies
* Best suited for standalone CLI tools that don't require complex dependency trees
* Does not manage Python environments or package dependencies like full conda/mamba

---

---
url: /configuration/environments.md
---
# Config Environments

It's possible to have separate `mise.toml` files in the same directory for different
environments like `development` and `production`. To enable, set `MISE_ENV` to an
environment like `development` or `production` using one of these methods:

* CLI flag: `-E development` or `--env development`
* Environment variable: `MISE_ENV=development`
* `.miserc.toml` file: `env = ["development"]`

mise will then look for a `mise.{MISE_ENV}.toml` file in the current directory,
parent directories and the `MISE_CONFIG_DIR` directory.

## Setting MISE\_ENV in .miserc.toml

You can set `MISE_ENV` in a `.miserc.toml` file, which is loaded very early before
other config files are discovered. This allows you to commit your environment
configuration to version control:

```toml
# .miserc.toml
env = ["development"]
```

File locations searched (in order of precedence):

1. `.miserc.toml` and `.config/miserc.toml` in current directory and parent directories
2. `~/.config/mise/miserc.toml` (global)
3. `/etc/mise/miserc.toml` (system)

Note: `MISE_ENV` cannot be set in `mise.toml` because it determines which config
files to load in the first place.

mise will also look for "local" files like `mise.local.toml` and `mise.{MISE_ENV}.local.toml`
in the current directory and parent directories.
These are intended to not be committed to version control.
(Add `mise.local.toml` and `mise.*.local.toml` to your `.gitignore` file.)

The priority of these files goes in this order (top overrides bottom):

* `mise.{MISE_ENV}.local.toml`
* `mise.local.toml`
* `mise.{MISE_ENV}.toml`
* `mise.toml`

If `MISE_OVERRIDE_CONFIG_FILENAMES` is set, that will be used instead of all of this.

You can also use paths like `mise/config.{MISE_ENV}.toml` or `.config/mise.{MISE_ENV}.toml` Those rules
follow the order in [Configuration](/configuration).

Use `mise config` to see which files are being used.

The rules around which file is written are different because we ultimately need to choose one. See
the docs for [`mise use`](/cli/use.html) for more information.

Multiple environments can be specified, e.g. `MISE_ENV=ci,test` with the last one taking precedence.

---

---
url: /configuration.md
---
# Configuration

Learn how to configure mise for your project with `mise.toml` files, environment variables, and various configuration options to manage your development environment.

## `mise.toml`

`mise.toml` is the config file for mise. They can be at any of the following file paths (in order of precedence, top overrides configuration of lower paths):

* `mise.local.toml` - used for local config, this should not be committed to source control
* `mise.toml`
* `mise/config.toml`
* `.mise/config.toml`
* `.config/mise.toml` - use this in order to group config files into a common directory
* `.config/mise/config.toml`
* `.config/mise/conf.d/*.toml` - all files in this directory will be loaded in alphabetical order

::: tip
Run [`mise cfg`](/cli/config.html) to figure out what order mise is loading files on your particular setup. This is often
a lot easier than figuring out mise's rules.
:::

Notes:

* Paths which start with `mise` can be dotfiles, e.g.: `.mise.toml` or `.mise/config.toml`.
* This list doesn't include [Configuration Environments](/configuration/environments) which allow for environment-specific config files like `mise.development.toml`—set with `MISE_ENV=development`.
* See [`LOCAL_CONFIG_FILENAMES` in `src/config/mod.rs`](https://github.com/jdx/mise/blob/main/src/config/mod.rs) for the actual code for these paths and their precedence. Some legacy paths are not listed here for brevity.

## Configuration Hierarchy

mise uses a sophisticated hierarchical configuration system that merges settings from multiple sources. Understanding this hierarchy helps you organize your development environments effectively.

### How Configuration Merging Works

These files recurse upwards, so if you have a `~/src/work/myproj/mise.toml` file, what is defined
there will override anything set in
`~/src/work/mise.toml` or `~/.config/mise.toml`. The config contents are merged together.

### Configuration Resolution Process

When mise needs configuration, it follows this process:

1. **Walks up the directory tree** from your current location to the root (or `MISE_CEILING_PATHS`)
2. **Collects all config files** it finds along the way
3. **Merges them in order** with more specific (closer to your current directory) settings overriding broader ones
4. **Applies environment-specific configs** like `mise.dev.toml` if `MISE_ENV` is set

### Visual Configuration Hierarchy

```
/
├── etc/mise/                         # System-wide config (highest precedence)
│   ├── conf.d/*.toml                 # System fragments, loaded alphabetically
│   ├── config.toml                   # System defaults
│   └── config.<env>.toml             # Env-specific system config (MISE_ENV or -E)
└── home/user/
    ├── .config/mise/
    │   ├── conf.d/*.toml             # User fragments, loaded alphabetically
    │   ├── config.toml               # Global user config
    │   ├── config.<env>.toml         # Env-specific user config
    │   ├── config.local.toml         # User-local overrides
    │   └── config.<env>.local.toml   # Env-specific user-local overrides
    └── work/
        ├── mise.toml                 # Work-wide settings
        └── myproject/
            ├── mise.local.toml       # Local overrides (git-ignored)
            ├── mise.toml             # Project config
            ├── mise.<env>.toml       # Env-specific project config
            ├── mise.<env>.local.toml # Env-specific project local overrides
            └── backend/
                └── mise.toml         # Service-specific config (lowest precedence)
```

### Merge Behavior by Section

Different configuration sections merge in different ways:

**Tools** (`[tools]`): Additive with overrides

```toml
# Global: node@18, python@3.11
# Project: node@20, go@1.21
# Result: node@20, python@3.11, go@1.21
```

**Environment Variables** (`[env]`): Additive with overrides

```toml
# Global: NODE_ENV=development
# Project: NODE_ENV=production, API_URL=localhost
# Result: NODE_ENV=production, API_URL=localhost
```

**Tasks** (`[tasks]`): Completely replaced per task

```toml
# Global: [tasks.test] = "npm test"
# Project: [tasks.test] = "yarn test"
# Result: "yarn test" (completely replaces global)
```

**Settings** (`[settings]`): Additive with overrides

```toml
# Global: experimental = true
# Project: jobs = 4
# Result: experimental = true, jobs = 4
```

::: tip
Run `mise config` to see what files mise has loaded in order of precedence.
:::

### Target File for Write Operations

When commands like [`mise use`](/cli/use), [`mise set`](/cli/set), or [`mise unuse`](/cli/unuse) need to write to a config file, they use the **lowest precedence file in the highest precedence directory**. This means:

* If both `mise.toml` and `mise.local.toml` exist, writes go to `mise.toml`
* If both `mise.toml` and `mise.production.toml` exist, writes go to `mise.toml`
* If only `mise.local.toml` exists, writes go to `mise.local.toml`

This behavior ensures that shared configuration (`mise.toml`) is updated by default, while local overrides (`mise.local.toml`) and environment-specific configs remain untouched unless explicitly targeted.

::: info Example

```bash
# With both mise.toml and mise.local.toml present:
$ mise use node@22              # writes to mise.toml
$ mise use --env local node@20  # writes to mise.local.toml
$ mise set NODE_ENV=production  # writes to mise.toml
```

:::

Here is what a `mise.toml` looks like:

```toml
[env]
NODE_ENV = 'production'

[tools]
terraform = '1.0.0'
erlang = '24.0'

[tasks.build]
run = 'echo "running build tasks"'
```

`mise.toml` files are hierarchical. The configuration in a file in the current directory will
override conflicting configuration in parent directories. For example, if `~/src/myproj/mise.toml`
defines the following:

```toml
[tools]
node = '20'
python = '3.10'
```

And `~/src/myproj/backend/mise.toml` defines:

```toml
[tools]
node = '18'
ruby = '3.1'
```

Then when inside of `~/src/myproj/backend`, `node` will be `18`, `python` will be `3.10`, and `ruby`
will be `3.1`. You can check the active versions with `mise ls --current`.

You can also have environment specific config files like `.mise.production.toml`, see
[Configuration Environments](/configuration/environments) for more details.

### `[tools]` - Dev tools

See [Tools](/dev-tools/). In addition to specifying versions, each tool entry can include options such as:

* `os`: Restrict installation to certain operating systems
* `install_env`: Environment vars used during install
* `postinstall`: Command to run after installation completes for that specific tool

Examples:

```toml
[tools]
node = { version = "22", postinstall = "corepack enable" }
```

### `[env]` - Arbitrary Environment Variables

See [environments](/environments/).

### `[tasks.*]` - Run files or shell scripts

See [Tasks](/tasks/).

### `[settings]` - Mise Settings

See [Settings](/configuration/settings) for the full list of settings.

### `[plugins]` - Specify Custom Plugin Repository URLs

Use `[plugins]` to add/modify plugin shortnames. Note that this will only modify
*new* plugin installations. Existing plugins can use any URL.

```toml
[plugins]
elixir = "https://github.com/my-org/mise-elixir.git"
node = "https://github.com/my-org/mise-node.git#DEADBEEF" # supports specific gitref
"vfox-backend:myplugin" = "https://github.com/jdx/vfox-npm"
```

The plugin type prefix (e.g., `asdf:`, `vfox:` or `vfox-backend:`) is optional. If omitted, mise will fall back to
either using `asdf` or `vfox` if the URL contains `vfox-` in the repo name.

If you simply want to install a plugin from a specific URL once, it's better to use
`mise plugin install <NAME> <GIT_URL>`. Add this section to `mise.toml` if you want
to share the plugin location/revision with other developers in your project.

This is similar
to [`MISE_SHORTHANDS`](https://github.com/jdx/mise#mise_shorthands_fileconfigmiseshorthandstoml)
but doesn't require a separate file.

### `[tool_alias]` - Tool version aliases

::: tip
`[alias]` has been renamed to `[tool_alias]` to distinguish it from `[shell_alias]`.
The old `[alias]` key still works but is deprecated.
:::

The following makes `mise install node@my_custom_node` install node-20.x
this can also be specified in a [plugin](/dev-tools/aliases.md).
note adding an alias will also add a symlink, in this case:

```sh
~/.local/share/mise/installs/node/20 -> ./20.x.x
```

```toml
[tool_alias.node.versions]
my_custom_node = '20'
```

### `[shell_alias]` - Shell aliases

Define shell aliases that are set when entering a directory and unset when leaving:

```toml
[shell_alias]
ll = "ls -la"
gs = "git status"
dev = "npm run dev"
```

These work similar to environment variables—they're set dynamically based on your current directory.
See [Shell Aliases](/shell-aliases) for more details.

### Minimum mise version

Specify the minimum supported version of mise required for the configuration file.

You can set a hard minimum (errors if unmet) or a soft minimum (warns and continues):

```toml
# (equivalent to hard)
min_version = '2024.11.1'

# new object form
min_version = { hard = '2024.11.1' }

# soft recommendation
min_version = { soft = '2024.11.1' }

# both
min_version = { hard = '2024.11.1', soft = '2024.9.0' }
```

When a soft minimum is not met, mise will print a warning and (if available) show self-update instructions. When a hard minimum is not met, mise errors and shows self-update instructions.

### Monorepo root&#x20;

Mark a configuration file as a monorepo root to enable target path syntax for tasks. Requires `MISE_EXPERIMENTAL=1`.

```toml
experimental_monorepo_root = true
```

When enabled:

* Tasks in subdirectories are available with namespaced paths (e.g., `//projects/frontend:build`)
* Subdirectory tasks use tools from parent configs
* Tasks are only loaded when needed (e.g., when running them, or with `mise tasks ls --all`)
* All descendant config files are **implicitly trusted** when the root is trusted
* Eliminates the need to individually trust each subdirectory's configuration

See [Monorepo Tasks](/tasks/monorepo) for detailed usage and examples.

### `mise.toml` schema

* You can find the JSON schema for `mise.toml` in [schema/mise.json](https://github.com/jdx/mise/blob/main/schema/mise.json) or at <https://mise.jdx.dev/schema/mise.json>.
* Some editors can load it automatically to provide autocompletion and validation for when editing a `mise.toml` file ([VSCode](https://code.visualstudio.com/docs/languages/json#_json-schemas-and-settings), [IntelliJ](https://www.jetbrains.com/help/idea/json.html#ws_json_using_schemas), [neovim](https://github.com/b0o/SchemaStore.nvim), etc.). It is also available in the [JSON schema store](https://www.schemastore.org/).
* Note that for `included tasks` (see [task configuration](/tasks/task-configuration), there is another schema: <https://mise.jdx.dev/schema/mise-task.json>)

## Global config: `~/.config/mise/config.toml`

mise can be configured in `~/.config/mise/config.toml`. It's like local `mise.toml` files except
that
it is used for all directories.

```toml [~/.config/mise/config.toml]
[tools]
# global tool versions go here
# you can set these with `mise use -g`
node = 'lts'
python = ['3.10', '3.11']

[settings]
# tools can read the versions files used by other version managers
# for example, .nvmrc in the case of node's nvm
idiomatic_version_file_enable_tools = ['node']

# configure `mise install` to always keep the downloaded archive
always_keep_download = false        # deleted after install by default
always_keep_install = false         # deleted on failure by default

# configure how frequently (in minutes) to fetch updated plugin repository changes
# this is updated whenever a new runtime is installed
# (note: this isn't currently implemented but there are plans to add it: https://github.com/jdx/mise/discussions/6735)
plugin_autoupdate_last_check_duration = '1 week' # set to 0 to disable updates

# config files with these prefixes will be trusted by default
trusted_config_paths = [
    '~/work/my-trusted-projects',
]

verbose = false       # set to true to see full installation output, see `MISE_VERBOSE`
http_timeout = "30s"  # set the timeout for http requests as duration string, see `MISE_HTTP_TIMEOUT`
jobs = 4              # number of plugins or runtimes to install in parallel. The default is `4`.
raw = false           # set to true to directly pipe plugins to stdin/stdout/stderr
yes = false           # set to true to automatically answer yes to all prompts

not_found_auto_install = true # see MISE_NOT_FOUND_AUTO_INSTALL
task.output = "prefix" # see Tasks Runner for more information
paranoid = false       # see MISE_PARANOID

shorthands_file = '~/.config/mise/shorthands.toml' # path to the shorthands file, see `MISE_SHORTHANDS_FILE`
disable_default_shorthands = false # disable the default shorthands, see `MISE_DISABLE_DEFAULT_SHORTHANDS`
disable_tools = ['node']           # disable specific tools, generally used to turn off core tools

env_file = '.env' # load env vars from a dotenv file, see `MISE_ENV_FILE`

experimental = true # enable experimental features

# configure messages displayed when entering directories with config files
status = {
  missing_tools = "if_other_versions_installed",
  show_env = false,
  show_tools = false,
}

# "_" is a special key for information you'd like to put into mise.toml that mise will never parse
[_]
foo = "bar"
```

## System config: `/etc/mise/config.toml`

Similar to `~/.config/mise/config.toml` but for all users on the system. This is useful for
setting defaults for all users.

## `.tool-versions`

The `.tool-versions` file is asdf's config file and it can be used in mise just like `mise.toml`.
It isn't as flexible so it's recommended to use `mise.toml` instead. It can be useful if you
already have a lot of `.tool-versions` files or work on a team that uses asdf.

Here is an example with all the supported syntax:

```text
node        20.0.0       # comments are allowed
ruby        3            # can be fuzzy version
shellcheck  latest       # also supports "latest"
jq          1.6
erlang      ref:master   # compile from vcs ref
go          prefix:1.19  # uses the latest 1.19.x version—needed in case "1.19" is an exact match
shfmt       path:./shfmt # use a custom runtime
node        lts          # use lts version of node (not supported by all plugins)

node        sub-2:lts      # install 2 versions behind the latest lts (e.g.: 18 if lts is 20)
python      sub-0.1:latest # install python-3.10 if the latest is 3.11
```

See [the asdf docs](https://asdf-vm.com/manage/configuration.html#tool-versions) for more info on
this file format.

## Scopes

Both `mise.toml` and `.tool-versions` support "scopes" which modify the behavior of the version:

* `ref:<SHA>` - compile from a vcs (usually git) ref
* `prefix:<PREFIX>` - use the latest version that matches the prefix. Useful for Go since `1.20`
  would only match `1.20` exactly but `prefix:1.20` will match `1.20.1` and `1.20.2` etc.
* `path:<PATH>` - use a custom compiled version at the given path. One use-case is to re-use
  Homebrew tools (e.g.: `path:/opt/homebrew/opt/node@20`).
* `sub-<PARTIAL_VERSION>:<ORIG_VERSION>` - subtracts PARTIAL\_VERSION from ORIG\_VERSION. This can
  be used to express something like "2 versions behind lts" such as `sub-2:lts`. Or 1 minor
  version behind the latest version: `sub-0.1:latest`.

## Idiomatic version files

mise supports "idiomatic version files" just like asdf. They're language-specific files
like `.node-version`
and `.python-version`. These are ideal for setting the runtime version of a project without forcing
other developers to use a specific tool like mise or asdf.

They support aliases, which means you can have an `.nvmrc` file with `lts/hydrogen` and it will work
in mise and nvm. Here are some of the supported idiomatic version files:

| Plugin     | Idiomatic Files                           |
| ---------- | ----------------------------------------- |
| atmos      | `.atmos-version`                          |
| bun        | `.bun-version`, `package.json`            |
| crystal    | `.crystal-version`                        |
| deno       | `.deno-version`, `package.json`           |
| dotnet     | `global.json`                             |
| elixir     | `.exenv-version`                          |
| go         | `.go-version`                             |
| java       | `.java-version`, `.sdkmanrc`              |
| node       | `.nvmrc`, `.node-version`, `package.json` |
| npm        | `package.json`                            |
| opentofu   | `.opentofu-version`                       |
| packer     | `.packer-version`                         |
| pnpm       | `package.json`                            |
| python     | `.python-version`, `.python-versions`     |
| ruby       | `.ruby-version`, `Gemfile`                |
| terraform  | `.terraform-version`, `main.tf`           |
| terragrunt | `.terragrunt-version`                     |
| terramate  | `.terramate-version`                      |
| yarn       | `.yvmrc`, `package.json`                  |

In mise, these are disabled by default, see <https://github.com/jdx/mise/discussions/4345> for rationale.

* `mise settings add idiomatic_version_file_enable_tools python` for a specific tool such as Python ([docs](/configuration/settings.html#idiomatic_version_file_enable_tools))

There is a performance cost to having these when they're parsed as it's performed by the plugin in
`bin/parse-version-file`. However, these are [cached](/cache-behavior) so it's not a huge deal.
You may not even notice.

::: info
asdf called these "legacy version files". I think this was a bad name since it implies
that they shouldn't be used—which is definitely not the case IMO. I prefer the term "idiomatic"
version files since they are version files not specific to asdf/mise and can be used by other tools.
(`.nvmrc` being a notable exception, which is tied to a specific tool.)
:::

## Settings

See [Settings](/configuration/settings) for the full list of settings.

## Tasks

See [Tasks](/tasks/) for the full list of configuration options.

## Environment variables

::: tip
Normally environment variables in mise are used to set [settings](/configuration/settings) so most
environment variables are in that doc. The following are environment variables that are not settings.

A setting in mise is generally something that can be configured either as an environment variable
or set in a config file.
:::

mise can also be configured via environment variables. The following options are available:

### `MISE_DATA_DIR`

Default: `~/.local/share/mise` or `$XDG_DATA_HOME/mise`

This is the directory where mise stores plugins and tool installs. These are not supposed to be
shared
across machines.

### `MISE_CACHE_DIR`

Default (Linux): `~/.cache/mise` or `$XDG_CACHE_HOME/mise`
Default (macOS): `~/Library/Caches/mise` or `$XDG_CACHE_HOME/mise`

This is the directory where mise stores internal cache. This is not supposed to be shared
across machines. It may be deleted at any time mise is not running.

### `MISE_TMP_DIR`

Default: [`std::env::temp_dir()`](https://doc.rust-lang.org/std/env/fn.temp_dir.html) implementation
in rust

This is used for temporary storage such as when installing tools.

### `MISE_SYSTEM_DIR`

Default: `/etc/mise`

This is the directory where mise stores system-wide configuration.

### `MISE_GLOBAL_CONFIG_FILE`

Default: `$MISE_CONFIG_DIR/config.toml` (Usually ~/.config/mise/config.toml)

This is the path to the config file.

### `MISE_GLOBAL_CONFIG_ROOT`

Default: `$HOME`

::: v-pre
This is the path which is used as `{{config_root}}` for the global config file.
:::

### `MISE_ENV_FILE`

Set to a filename to read from env from a dotenv file. e.g.: `MISE_ENV_FILE=.env`.
Uses [dotenvy](https://crates.io/crates/dotenvy) under the hood.

### `MISE_${PLUGIN}_VERSION`

Set the version for a runtime. For example, `MISE_NODE_VERSION=20` will use <node@20.x> regardless
of what is set in `mise.toml`/`.tool-versions`.

### `MISE_TRUSTED_CONFIG_PATHS`

This is a list of paths that mise will automatically mark as
trusted. They can be separated with `:`.

### `MISE_CEILING_PATHS`

This is a list of paths where mise will stop searching for
configuration files and file tasks. This is useful to stop
mise searching for files in slow loading directories. They are separated according to platform conventions for the PATH environment variable. On most Unix platforms, the separator is `:` and on Windows it is `;`.

### `MISE_LOG_LEVEL=trace|debug|info|warn|error`

These change the verbosity of mise.

You can also use `MISE_DEBUG=1`, `MISE_TRACE=1`, and `MISE_QUIET=1` as well as
`--log-level=trace|debug|info|warn|error`.

### `MISE_LOG_FILE=~/mise.log`

Output logs to a file.

### `MISE_LOG_FILE_LEVEL=trace|debug|info|warn|error`

Same as `MISE_LOG_LEVEL` but for the log *file* output level. This is useful if you want
to store the logs but not have them litter your display.

### `MISE_LOG_HTTP=1`

Display HTTP requests/responses in the logs.

### `MISE_QUIET=1`

Equivalent to `MISE_LOG_LEVEL=warn`.

### `MISE_HTTP_TIMEOUT`

Set the timeout for http requests in seconds. The default is `30`.

### `MISE_RAW=1`

Set to "1" to directly pipe plugin scripts to stdin/stdout/stderr. By default stdin is disabled
because when installing a bunch of plugins in parallel you won't see the prompt. Use this if a
plugin accepts input or otherwise does not seem to be installing correctly.

Sets `MISE_JOBS=1` because only 1 plugin script can be executed at a time.

### `MISE_FISH_AUTO_ACTIVATE=1`

Configures the vendor\_conf.d script for fish shell to automatically activate.
This file is automatically used in homebrew and potentially other installs to
automatically activate mise without configuring.

Defaults to enabled, set to "0" to disable.

---

---
url: /contact.md
---
# Contact

`mise` is mostly built and maintained by me, [Jeff Dickey](https://jdx.dev). The goal is
to make local development of software easy and consistent across languages. I
have spent many years building dev tools and thinking about the problems that `mise`
addresses.

I try to use the first-person in these docs since the reality is it's generally me
writing them and I think it makes it more interesting having a bit of my personality
in the text.

This project is simply a labor of love. I am making it because I want to make
your life as a developer easier. I hope you find it useful. Feedback is a massive
driver for me. If you have anything positive or negative to say-even if it's just
to say hi-please reach out to me either on [Twitter](https://twitter.com/jdxcode),
[Mastodon](https://fosstodon.org/@jdx), [Discord](https://discord.gg/UBa7pJUN7Z),
or `jdx at this domain`.

---

---
url: /continuous-integration.md
---
# Continuous integration

You can use Mise in continuous integration environments to provision the environment with the tools the project needs.
We recommend that your project pins the tools to a specific version to ensure the environment is reproducible.

## Any CI provider

Continuous integration pipelines allow running arbitrary commands. You can use this to install Mise and run `mise install` to install the tools:

```yaml
script: |
  curl https://mise.run | sh
  mise install
```

To ensure you run the version of the tools installed by Mise, make sure you run them through the `mise x` command:

```yaml
script: |
  mise x -- npm test
```

Alternatively, you can add the [shims](/dev-tools/shims.md) directory to your `PATH`, if the CI provider allows it.

### Bootstrapping

An alternative to calling `curl https://mise.run | sh` is to use [`mise generate bootstrap`](/cli/generate/bootstrap.html) to generate a script that runs and install `mise`.

```shell
mise generate bootstrap -l -w
```

Add the `.mise/` to your `.gitignore` and commit the generated `./bin/mise` file. You can now use `./bin/mise` to install and run `mise` directly in CI.

```yaml
script: |
  ./bin/mise install
  ./bin/mise x -- npm test
```

## GitHub Actions

If you use GitHub Actions, we provide a [mise-action](https://github.com/jdx/mise-action) that wraps the installation of Mise and the tools. All you need to do is to add the action to your workflow:

```yaml
name: test
on:
  pull_request:
    branches:
      - main
  push:
    branches:
      - main
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: jdx/mise-action@v3
        with:
          version: 2024.12.14 # [default: latest] mise version to install
          install: true # [default: true] run `mise install`
          cache: true # [default: true] cache mise using GitHub's cache
          experimental: true # [default: false] enable experimental features
          # automatically write this mise.toml file
          mise_toml: |
            [tools]
            shellcheck = "0.9.0"
          # or, if you prefer .tool-versions:
          tool_versions: |
            shellcheck 0.9.0
      - run: shellcheck scripts/*.sh
```

## GitLab CI

You can use any docker image with `mise` installed to run your CI jobs.
Here's an example using `debian-slim` as base image:
::: details Example Dockerfile

```dockerfile
FROM debian:12-slim

RUN apt-get update  \
    && apt-get -y --no-install-recommends install  \
      # install any tools you need
      sudo curl git ca-certificates build-essential \
    && rm -rf /var/lib/apt/lists/*

RUN curl https://mise.run | MISE_VERSION=v... MISE_INSTALL_PATH=/usr/local/bin/mise sh
```

:::

When configuring your job, you can cache some of the [Mise directories](/directories).

```yaml
build-job:
  stage: build
  image: mise-debian-slim # Use the image you created
  variables:
    MISE_DATA_DIR: $CI_PROJECT_DIR/.mise/mise-data
  cache:
    - key:
        prefix: mise-
        files: ["mise.toml", "mise.lock"] # mise.lock is optional, only if using `lockfile = true`
      paths:
        - $MISE_DATA_DIR
  script:
    - mise install
    - mise exec --command 'npm build'
```

### Example with the bootstrap script

An alternative is to use [`mise generate bootstrap`](/cli/generate/bootstrap.html) to easily [bootstrap](#bootstrapping) `mise` on GitLab CI.

```
mise generate bootstrap -l -w
```

You can now use a generic docker image such as this one to run and install `mise` in CI.

::: details Example Dockerfile

```dockerfile
FROM debian:12-slim

RUN apt-get update  \
    && apt-get -y --no-install-recommends install sudo curl git ca-certificates build-essential \
    && rm -rf /var/lib/apt/lists/*
```

:::

Here's an example of a `.gitlab-ci.yml` file:

```yaml
.mise-cache: &mise-cache
  key:
    prefix: mise-
    files: ["mise.toml", "./bin/mise"]
  paths:
    - .mise/installs
    - .mise/mise-2025.1.3

build-job:
  stage: build
  image: my-debian-slim-image # Use the image you created
  cache:
    - <<: *mise-cache
      policy: pull-push
  script:
    - ./bin/mise install
    - ./bin/mise exec --command 'npm build'
```

## Xcode Cloud

If you are using Xcode Cloud, you can use custom `ci_post_clone.sh` [build script](https://developer.apple.com/documentation/xcode/writing-custom-build-scripts) to install Mise. Here's an example:

```bash
#!/bin/sh
curl https://mise.run | sh
export PATH="$HOME/.local/bin:$PATH"

mise install # Installs the tools in mise.toml
eval "$(mise activate bash --shims)" # Adds the activated tools to $PATH

swiftlint {args}
```

---

---
url: /contributing.md
---

# Contributing

Before submitting a PR, unless it's something obvious, consider creating a
[discussion](https://github.com/jdx/mise/discussions)
or simply mention what you plan to do in the
[Discord](https://discord.gg/UBa7pJUN7Z).
PRs are often either rejected or need to change significantly after submission
so make sure before you start working on something it won't be a wasted effort.

## Contributing Guidelines

1. **Before starting**: Create a discussion or discuss in Discord for non-obvious changes
2. **Test thoroughly**: Ensure both unit and E2E tests pass
3. **Follow conventions**: Use existing code style and patterns
4. **Update documentation**: Add/update docs for new features

### Pull Request Workflow

1. **PR titles**: Must follow conventional commit format (validated
   automatically)
   * For new tools in registry: Use `registry: add tool-name (backend:full/name)`
2. **Auto-formatting**: Code will be automatically formatted by autofix.ci
3. **CI checks**: All tests must pass across Linux, macOS, and Windows
4. **Coverage**: New code should maintain or improve test coverage
5. **Dependencies**: New dependencies are validated with cargo-deny

### Development Tips

1. **Disable mise during development**: If you use mise in your shell, disable
   it when running tests to avoid conflicts
2. **Test specific features**: Use `cargo test test_name` for targeted testing
3. **Update snapshots**: Use `mise run snapshots` when changing test outputs
4. **Rate limiting**: Set `MISE_GITHUB_TOKEN` to avoid GitHub API rate limits
   during development

## Packaging and Self-Update Instructions

When mise is installed via a package manager, in-app self-update is disabled and users should update via their package manager. Packaging should install a TOML file with platform-specific instructions at `lib/mise-self-update-instructions.toml` (or `lib/mise/mise-self-update-instructions.toml`). Example contents:

```toml
# Debian/Ubuntu (APT)
message = "To update mise from the APT repository, run:\n\n  sudo apt update && sudo apt install --only-upgrade mise\n"
```

```toml
# Fedora/CentOS Stream (DNF)
message = "To update mise from COPR, run:\n\n  sudo dnf upgrade mise\n"
```

## Testing

mise has a comprehensive test suite with multiple types of tests to ensure
reliability and functionality across different platforms and scenarios.

### Unit Tests

Unit tests are fast, focused tests for individual components and functions:

```bash
# Run all unit tests
cargo test --all-features

# Run specific unit tests
cargo test <test_name>
```

**Unit test structure:**

* Located in `src/` directory alongside source code
* Use Rust's built-in test framework
* Test individual functions and modules
* Fast execution (used for quick feedback during development)

### E2E Tests

End-to-end tests validate the complete functionality of mise in realistic
scenarios:

```bash
# Run all E2E tests
mise run test:e2e

# Run specific E2E test
./e2e/run_test test_name

# Run E2E tests matching pattern
./e2e/run_test task  # runs tests matching *task*

# Run all tests including slow ones
TEST_ALL=1 mise run test:e2e
```

**E2E test structure:**

* Located in `e2e/` directory
* Organized by functionality:
  * `e2e/cli/` - Command-line interface tests
  * `e2e/core/` - Core functionality tests
  * `e2e/env/` - Environment variable tests
  * `e2e/tasks/` - Task runner tests
  * `e2e/config/` - Configuration tests
  * `e2e/tools/` - Tool management tests
  * `e2e/shell/` - Shell integration tests
  * `e2e/backend/` - Backend tests
  * `e2e/plugins/` - Plugin tests

**E2E test categories:**

* **Fast tests** (`test_*`): Run in normal test suites
* **Slow tests** (`test_*_slow`): Only run when `TEST_ALL=1` is set
* **Isolated environment**: Each test runs in a clean, isolated environment

### Coverage Tests

Coverage tests measure how much of the codebase is covered by tests:

```bash
# Run coverage tests
mise run test:coverage

# Coverage tests run in parallel tranches for CI
TEST_TRANCHE=0 TEST_TRANCHE_COUNT=8 mise run test:coverage
```

### Windows E2E Tests

Windows has its own test suite written in PowerShell:

```powershell
# Run all Windows E2E tests
pwsh e2e-win\run.ps1

# Run specific Windows tests
pwsh e2e-win\run.ps1 task  # run tests matching *task*
```

### Plugin Tests

Test plugin functionality across different backends:

```bash
# Test specific plugin
mise test-tool ripgrep

# Test all plugins in registry
mise test-tool --all

# Test all plugins in config files
mise test-tool --all-config

# Test with parallel jobs
mise test-tool --all --jobs 4
```

### Test Environment Setup

Tests run in isolated environments to avoid conflicts:

```bash
# Disable mise during development testing
export MISE_DISABLE_TOOLS=1

# Run tests with specific environment
MISE_TRUSTED_CONFIG_PATHS=$PWD cargo test
```

### Test Assertions

The E2E tests use a custom assertion framework (`e2e/assert.sh`):

```bash
# Basic assertions
assert "command" "expected_output"
assert_contains "command" "substring"
assert_fail "command" "expected_error"

# JSON assertions
assert_json "command" '{"key": "value"}'
assert_json_partial_array "command" "fields" '[{...}]'

# File/directory assertions
assert_directory_exists "/path/to/dir"
assert_directory_not_exists "/path/to/dir"
assert_empty "command"
```

### Running Specific Test Categories

```bash
# Run all tests (unit + e2e)
mise run test

# Run only unit tests
mise run test:unit

# Run only e2e tests
mise run test:e2e

# Run tests with shuffle (for detecting order dependencies)
mise run test:shuffle

# Run nightly tests (with bleeding edge Rust)
rustup default nightly && mise run test
```

### Running Individual Tests

#### Running Single Unit Tests

```bash
# Run a specific unit test by name
cargo test test_name

# Run tests matching a pattern
cargo test pattern

# Run tests in a specific module
cargo test module_name

# Run a single test with output
cargo test test_name -- --nocapture
```

#### Running Single E2E Tests

```bash
# Run a specific E2E test by name
./e2e/run_test test_name

# Run E2E tests matching a pattern
mise run test:e2e pattern

# Examples:
./e2e/run_test test_use                    # Run specific test
./e2e/run_test test_config_set            # Run config-related test
mise run test:e2e task                     # Run all tests matching "task"
```

#### Testing Individual Plugins

```bash
# Test a specific plugin
mise test-tool ripgrep

# Test a plugin with verbose output
mise test-tool ripgrep --raw

# Test multiple plugins
mise test-tool ripgrep jq terraform
```

### Performance Testing

```bash
# Run performance benchmarks
mise run test:perf

# Build performance test workspace
mise run test:build-perf-workspace
```

### Snapshot Testing

Used for testing output consistency:

```bash
# Update test snapshots when output changes
mise run snapshots

# Use cargo-insta for snapshot testing
cargo insta test --accept --unreferenced delete
```

## Development Setup

### Prerequisites

* [Rust](https://www.rust-lang.org/) (latest stable, we don't use mise to
  manage rust)
* mise

### Getting Started

```bash
# Clone the repository
git clone https://github.com/jdx/mise.git
cd mise

# Install dependencies
mise install

# Build the project
mise run build
```

### Development Shim

Create a development shim to easily run mise during development:

```bash
# Create ~/.local/bin/@mise
#!/bin/sh
exec cargo run -q --all-features --manifest-path ~/src/mise/Cargo.toml -- "$@"
```

Then use `@mise` to run the development version:

```bash
@mise --help
eval "$(@mise activate zsh)"
```

## Project Structure

```text
mise/
├── src/           # Main Rust source code
├── e2e/           # End-to-end tests
├── docs/          # Documentation
├── tasks.toml     # Development tasks
├── mise.toml      # Project configuration
├── Cargo.toml     # Rust project configuration
└── xtasks/        # Additional build scripts
```

## Available Development Tasks

Use `mise tasks` to see all available development tasks:

### Common Tasks

* `mise run build` - Build the project
* `mise run test` - Run all tests (unit + E2E)
* `mise run test:unit` - Run unit tests only
* `mise run test:e2e` - Run E2E tests only
* `mise run lint` - Run linting
* `mise run lint:fix` - Run linting with fixes
* `mise run format` - Format code
* `mise run clean` - Clean build artifacts
* `mise run snapshots` - Update test snapshots
* `mise run render` - Generate documentation and completions

### Documentation Tasks

* `mise run docs` - Start documentation development server
* `mise run docs:build` - Build documentation
* `mise run render:help` - Generate help documentation
* `mise run render:completions` - Generate shell completions

### Release Tasks

* `mise run release` - Create a release
* `mise run ci` - Run CI tasks (format, build, test)

## Setup

Shouldn't require anything special I'm aware of, but `mise run build` is a good
sanity check to run and make sure it's all working.

## Pre-commit Hooks & Code Quality

mise uses [hk](https://hk.jdx.dev) as its git hook manager for
linting and code quality checks. hk is a modern alternative to lefthook written
by the same author as mise.

### hk Configuration

The project uses `hk.pkl` (written in the Pkl configuration language) to define
linting rules:

```bash
# Run all linting checks
hk check --all

# Run linting with fixes
hk fix --all

# Run specific linter
hk check --step shellcheck
```

### Available Linters in hk

* **prettier**: Code formatting for multiple languages
* **clippy**: Rust linting with `cargo clippy`
* **shellcheck**: Shell script linting
* **shfmt**: Shell script formatting
* **pkl**: Pkl configuration file validation

### Using hk in Development

```bash
# Run linting (used in CI and pre-commit)
mise run lint  # This runs hk check --all

# Run linting with fixes
hk fix --all

# Check specific file types
hk check --step prettier
hk check --step shellcheck
```

### Pre-commit Task Configuration

mise defines a `pre-commit` task that runs the main linting checks:

```toml
[pre-commit]
env = { PRE_COMMIT = 1 }
run = ["mise run lint"]
```

This task:

1. Sets `PRE_COMMIT=1` environment variable
2. Runs `mise run lint`, which executes `hk check --all`

### Setting Up Pre-commit Hooks

```bash
# Set up git hook to run mise's pre-commit task
mise generate git-pre-commit --write --task=pre-commit
```

### Running Pre-commit Checks Manually

```bash
# Run all pre-commit checks
mise run pre-commit

# Run specific linting checks
mise run lint

# Run linting with fixes
hk fix --all

# Run checks on specific files
hk check --files="src/**/*.rs"
```

## Running the CLI

I use the following shim in `~/.local/bin/@mise`:

```sh
#!/bin/sh
exec cargo run -q --all-features --manifest-path ~/src/mise/Cargo.toml -- "$@"
```

::: info
Don't forget to change the manifest path to the correct path for your setup.
:::

Then if that is in PATH just use `@mise` to run mise by compiling it on the fly.

```sh
@mise --help
eval "$(@mise activate zsh)"
@mise activate fish | source
```

## Releasing

Run `mise run release -x [minor|patch]`. (minor if it is the first release in a
month)

## Linting

* Lint codebase: `mise run lint`
* Lint and fix codebase: `mise run lint:fix`

## Generating readme and shell completion files

```sh
mise run render
```

## Dependency Management

mise uses several tools to validate dependencies and code quality:

* **cargo-deny**: Validates licenses, security advisories, and dependency
  duplicates
* **cargo-msrv**: Verifies minimum supported Rust version compatibility
* **cargo-machete**: Detects unused dependencies in Cargo.toml

These checks run automatically in CI and can be run locally:

```bash
# Run checks (tools are automatically available via mise.toml)
cargo deny check
cargo msrv verify
cargo machete --with-metadata
```

## Conventional Commits

mise uses [Conventional Commits](https://www.conventionalcommits.org/) for
consistent commit messages and automated changelog generation. All commits
should follow this format:

```text
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

### Commit Types

* **feat**: New features (🚀 Features)
* **fix**: Bug fixes (🐛 Bug Fixes)
* **refactor**: Code refactoring (🚜 Refactor)
* **docs**: Documentation changes (📚 Documentation)
* **style**: Code style changes (🎨 Styling)
* **perf**: Performance improvements (⚡ Performance)
* **test**: Testing changes (🧪 Testing)
* **chore**: Maintenance tasks, dependency updates
* **revert**: Reverting previous changes (◀️ Revert)

### Examples

```bash
feat(cli): add new command for listing plugins
fix(parser): handle edge case in version parsing
refactor(config): simplify configuration loading logic
docs(readme): update installation instructions
test(e2e): add tests for new plugin functionality
chore(deps): update dependencies to latest versions
```

### Scopes

Common scopes used in mise:

* `cli` - Command line interface changes
* `config` - Configuration system changes
* `parser` - Parsing logic changes
* `deps` - Dependency updates
* `security` - Security-related changes

### Breaking Changes

#### Breaking Change Policy

Breaking changes are rarely accepted into mise and are only performed in
exceptional situations where there is no better alternative. When a breaking
change is necessary, the process includes:

1. **CLI warnings**: Users receive deprecation warnings in the CLI
2. **Migration period**: Several months are provided for users to migrate
3. **Documentation**: Clear migration guides are provided
4. **Community notice**: Announcements in Discord and GitHub discussions

For breaking changes, add `!` after the type or include `BREAKING CHANGE:` in
the footer:

```bash
feat(api)!: remove deprecated configuration options
# OR
feat(api): remove deprecated configuration options

BREAKING CHANGE: The old configuration format is no longer supported
```

## CI/CD & Pull Request Automation

mise uses several automated workflows to maintain code quality and streamline
development:

### Automated Code Formatting

* **autofix.ci**: Automatically formats code and fixes linting issues in PRs
* Runs `mise run render` and `mise run lint-fix` automatically
* Commits fixes directly to the PR branch

### PR Title Validation

* **semantic-pr-lint**: Validates PR titles follow conventional commit format
* PR titles must match: `<type>[optional scope]: <description>`
* Example: `feat(cli): add new command for listing plugins`

### Continuous Integration

* **Cross-platform testing**: Ubuntu, macOS, and Windows
* **Unit tests**: Fast component-level tests
* **E2E tests**: Full integration testing with multiple test tranches
* **Dependency validation**: `cargo deny`, `cargo msrv`, `cargo machete`

### Release Automation

* **release-plz**: Automated release management based on conventional commits
* Automatically creates release PRs and publishes releases
* Runs daily via scheduled workflow
* Handles version bumping and changelog generation

## Adding a new setting

To add a new setting, add it to
[`settings.toml`](https://github.com/jdx/mise/blob/main/settings.toml) in the
root of the project and run `mise run render` to update the codebase.

## Adding Tools

Adding tools to mise involves adding entries to the
[registry/](https://github.com/jdx/mise/blob/main/registry/) file. This
allows users to install tools using short names like `mise use ripgrep` instead
of the full backend specification.

### Quick Start

1. **Choose the right backend** for your tool:

   * **[aqua](dev-tools/backends/aqua.md)** - Preferred for GitHub releases with security
     features
   * **[github](dev-tools/backends/github.md)** - Simple GitHub releases following
     standard conventions
   * **Language package managers** - `npm`, `pipx`, `cargo`, `gem`, etc. for
     ecosystem-specific tools
   * **[Core tools](core-tools.md)** - Built-in support for major languages
     (not user-contributed)

2. **Add to registry/**:

   ```toml
   [tools.your-tool]
   description = "Brief description of the tool"
   backends = ["aqua:owner/repo", "github:owner/repo"]
   test = ["your-tool --version", "{{version}}"]
   ```

3. **Test the tool** works properly with `mise test-tool your-tool`

### Guidelines and Requirements

When adding a new tool, the following requirements apply (automatically
enforced by [GitHub Actions workflow](https://github.com/jdx/mise/blob/main/.github/workflows/registry_comment.yml)):

* **New asdf plugins are not accepted** - Use aqua/github instead
* **A test is required in `registry/`** - Must include a `test` field to
  verify installation
* **Tools may be rejected if they are not notable** - The tool should be
  reasonably popular and well-maintained. There are no specific guidelines for this and
  a lot of factors are taken into account. @jdx won't explain why a given tool wasn't
  accepted.

### Registry Format

The `registry/` file uses this format:

```toml
# Tool name "your-tool" (becomes the short name for `mise use`)
[tools.your-tool]
description = "Tool description"
backends = [
    "aqua:owner/repo",           # Preferred backend first
    "github:owner/repo",         # Fallback backends
    "npm:package-name"           # Multiple backends supported
]
test = [
    "your-tool --version",       # Command to run
    "{{version}}"                # Expected output pattern
]
aliases = ["alt-name"] # Optional alternative names
os = ["linux", "macos"] # Optional OS restrictions
```

### Backend Priority

List backends in order of preference. Users will get the first available
backend, but can override with explicit syntax like `mise use aqua:owner/repo`.

### Tool Testing

All tools must include a test to verify proper installation:

```toml
test = [
    "command-to-run",
    "expected-output-pattern"
]
```

The test command should be reliable and the output pattern should use
`{{version}}` to match any version number.

### Registry Examples

Recent tool additions:

* **DuckDB**: Simple github backend ([#4248](https://github.com/jdx/mise/pull/4248))

  ```toml
  [tools.duckdb]
  backends = ["github:duckdb/duckdb"]
  test = ["duckdb --version", "{{version}}"]
  ```

* **Biome**: Multiple backends ([#4283](https://github.com/jdx/mise/pull/4283))

  ```toml
  [tools.biome]
  backends = ["aqua:biomejs/biome", "github:biomejs/biome"]
  test = ["biome --version", "Version: {{version}}"]
  ```

## Adding Backends

:::warning Backend vs Tool Confusion
**Most contributors want to add tools, not backends.** Before reading this
section, make sure you actually need a new backend. Tools are individual
software packages (like `node` or `ripgrep`), while backends are installation
mechanisms (like `aqua` or `github`). If you want to add a specific tool to mise,
see [Adding Tools](#adding-tools) instead.
:::

:::warning Core Backend Acceptance Policy
**New backends are unlikely to be accepted into mise core.** They require
a lot of maintenance so it's generally better to use the [backend plugin system](backend-plugin-development.md) to add backends without core changes. A new backend would only be accepted for a major package manager
or tool that would greatly enhance mise's capabilities.

If you need a custom backend:

1. **Discuss with jdx first** in [Discord](https://discord.gg/UBa7pJUN7Z) or by
   creating a [discussion](https://github.com/jdx/mise/discussions)
2. **Consider if existing backends** (github, aqua, npm, pipx, etc.) can meet your
   needs
3. **Create a plugin** - use the [plugin system](tool-plugin-development.md) to create plugins for private/custom tools without core changes. Start with the [mise-tool-plugin-template](https://github.com/jdx/mise-tool-plugin-template) for a quick setup

Most tool installation needs can be met by existing backends, especially
[github](dev-tools/backends/github.md) for GitHub releases and
[aqua](dev-tools/backends/aqua.md) for comprehensive package management.
:::

Backends are mise's abstraction for different tool installation methods. Each
backend implements the `Backend` trait to provide consistent functionality
across different installation systems.

### Backend Types

* **Core Backends** (`src/backend/core/`) - Built-in language runtimes like
  Node.js, Python, Ruby
* **Package Manager Backends** (`src/backend/`) - npm, pipx, cargo, gem, go
  modules
* **Universal Installers** (`src/backend/`) - github, aqua for GitHub releases and
  package management
* **Plugin Backends** (`src/backend/`) - plugins can provide custom backends or individual tools

### Implementation Steps

1. **Create the backend module** in `src/backend/` (e.g., `my_backend.rs`)

2. **Implement the Backend trait**:

   ```rust
   use crate::backend::{Backend, BackendType};
   use crate::install_context::InstallContext;

   #[derive(Debug)]
   pub struct MyBackend {
       // backend-specific fields
   }

   impl Backend for MyBackend {
       fn get_type(&self) -> BackendType { BackendType::MyBackend }

       async fn list_remote_versions(&self) -> Result<Vec<String>> {
           // Implementation for listing available versions
       }

       async fn install_version(&self, ctx: &InstallContext,
                                 tv: &ToolVersion) -> Result<()> {
           // Implementation for installing a specific version
       }

       async fn uninstall_version(&self, tv: &ToolVersion) -> Result<()> {
           // Implementation for uninstalling a version
       }

       // ... other required methods
   }
   ```

3. **Register the backend** in `src/backend/mod.rs`:

   * Add your backend to the imports
   * Add it to the backend registry/factory function
   * Add the `BackendType` enum variant

4. **Add CLI argument parsing** in `src/cli/args/backend_arg.rs` if needed

5. **Update the registry** in `registry/` if it should be available as a
   shorthand

### Testing Requirements

* **Integration tests** in `e2e/backend/test_my_backend`
* **Test both installation and usage** of tools from your backend
* **Windows testing** if the backend supports Windows

### Documentation

* **Update backend documentation** in `docs/dev-tools/backends/`
* **Add usage examples** showing how to install tools with your backend
* **Update the registry documentation** if adding new shorthand tools

### Implementation Examples

Look at existing backends for patterns:

* `src/backend/github.rs` - Simple GitHub release installer
* `src/backend/npm.rs` - Package manager integration
* `src/backend/core/node.rs` - Full language runtime implementation

For detailed architecture information, see
[Backend Architecture](dev-tools/backend_architecture.md).

## Testing packaging

This is only necessary to test if actually changing the packaging setup.

### Ubuntu (apt)

This is for arm64, but you can change the arch to amd64 if you want.

```sh
docker run -ti --rm ubuntu
apt update -y
apt install -y curl
install -dm 755 /etc/apt/keyrings
curl -fSso /etc/apt/keyrings/mise-archive-keyring.pub https://mise.jdx.dev/gpg-key.pub
echo "deb [signed-by=/etc/apt/keyrings/mise-archive-keyring.pub arch=arm64] \
https://mise.jdx.dev/deb stable main" >/etc/apt/sources.list.d/mise.list
apt update -y
apt install -y mise
mise -V
```

### Fedora (dnf)

```sh
docker run -ti --rm fedora
dnf copr enable -y jdxcode/mise && dnf install -y mise && mise -v
```

### RHEL (dnf)

```sh
docker run -ti --rm registry.access.redhat.com/ubi9/ubi:latest
dnf copr enable -y jdxcode/mise && dnf install -y mise && mise -v
```

---

---
url: /mise-cookbook.md
---
# Cookbook

Here we are sharing a few mise setups that other people have found useful.

* [C++](cpp.md)
* [Docker](docker.md)
* [Node.JS](nodejs.md)
* [Python](python.md)
* [Ruby](ruby.md)
* [Terraform](terraform.md)
* [Neovim](neovim.md)

Finally, here is how to create [presets](presets.md) and some [shell tricks](shell-tricks.md) you might find useful.

## Contributing

If you would like to share your setup, please share it in this [cookbook thread](https://github.com/jdx/mise/discussions/3645).

---

---
url: /core-tools.md
---
# Core Tools

`mise` comes with some plugins built into the CLI written in Rust. These are new and will improve over
time.

They can be easily overridden by installing an asdf/vfox plugin with the same name, e.g.: `mise plugin install python https://github.com/asdf-community/asdf-python`.

You can see the core plugins with `mise registry -b core`.

* [Bun](/lang/bun)
* [Deno](/lang/deno)
* [Elixir](/lang/elixir)
* [Erlang](/lang/erlang)
* [Go](/lang/go)
* [Java](/lang/java)
* [NodeJS](/lang/node)
* [Python](/lang/python)
* [Ruby](/lang/ruby)
* [Rust](/lang/rust)
* [Swift](/lang/swift)&#x20;
* [Zig](/lang/zig)

---

---
url: /demo.md
---
# Demo

The following demo shows:

* how to use `mise exec` to run a command with a specific version of a tool
* how you can use `mise` to install and many other tools such as `jq`, `terraform`, or `go`.
* how to use `mise` to manage multiple versions of `node` on the same system.

## Transcript

`mise exec <tool> -- <command>` allows you to run any tools with mise

```shell
mise exec node@24 -- node -v
# mise node@24.x.x ✓ installed
# v24.x.x
```

node is only available in the mise environment, not globally

```shell
node -v
# bash: node: command not found
```

***

Here is another example where we run terraform with `mise exec`

```shell
mise exec terraform -- terraform -v
# mise terraform@1.11.3 ✓ installed
# Terraform v1.11.3
```

***

`mise exec` is great for running one-off commands, however it can be convenient to activate mise. When activated, mise will automatically update your `PATH` to include the tools you have installed, making them available directly.

We will start by installing node@lts and make it the global default

```shell
mise use --global node@lts
# v22.14.0
```

```shell
node -v
# v22.14.0
```

```shell
which node
# /root/.local/share/mise/installs/node/22.14.0/bin/node
```

Note that we get back the path to the real node here, not a shim.

***

We can also install other tools with mise. For example, we will install terraform, jq, and go

```shell
mise use -g terraform jq go
# mise jq@1.7.1 ✓ installed
# mise terraform@1.11.3 ✓ installed
# mise go@1.24.1 ✓ installed
# mise ~/.config/mise/config.toml tools: go@1.24.1, jq@1.7.1, terraform@1.11.3
```

```shell
terraform -v
# Terraform v1.11.3
```

```shell
jq --version
# jq-1.7
```

```shell
go version
# go version go1.24.1 linux/amd64
```

```shell
mise ls
# Tool       Version  Source                      Requested
# go         1.24.1   ~/.config/mise/config.toml  latest
# jq         1.7.1    ~/.config/mise/config.toml  latest
# node       22.14.0  ~/.config/mise/config.toml  lts
# terraform  1.11.3   ~/.config/mise/config.toml  latest
```

***

Let's enter a project directory where we will set up node@23

```shell
cd myproj
mise use node@23 pnpm@10
# mise node@23.10.0 ✓ installed
# mise pnpm@10.7.0 ✓ installed
```

```shell
node -v
# v23.10.0
pnpm -v
# 10.7.0
```

As expected, `node -v` is now v23.x

```shell
cat mise.toml
# [tools]
# node = "23"
# pnpm = "10"
```

We will leave this directory. The node version will revert to the global LTS version

```shell
cd ..
node -v
# v22.14.0
```

---

---
url: /lang/deno.md
---
# Deno

`mise` can be used to install and manage multiple versions of [deno](https://deno.land/) on the same system.

> The following are instructions for using the deno mise core plugin. This is used when there isn't a
> git plugin installed named "deno". If you want to use [asdf-deno](https://github.com/asdf-community/asdf-deno)
> then run `mise plugins install deno https://github.com/asdf-community/asdf-deno`.

The code for this is inside the mise repository at
[`./src/plugins/core/deno.rs`](https://github.com/jdx/mise/blob/main/src/plugins/core/deno.rs).

## Usage

The following installs deno and makes it the global default:

```sh
mise use -g deno@1       # install deno 1.x
mise use -g deno@latest  # install latest deno
```

See available versions with `mise ls-remote deno`.

> \[!NOTE]
> Avoid using `deno upgrade` to upgrade `deno` as `mise` will not be aware of the change.

---

---
url: /dev-tools.md
---
# Dev Tools

> *Like [asdf](https://asdf-vm.com) (or [nvm](https://github.com/nvm-sh/nvm)
> or [pyenv](https://github.com/pyenv/pyenv) but for any language), it manages dev tools like node,
> python, cmake, terraform, and [hundreds more](/registry.html).*

`mise` is a tool that manages installations of programming language runtimes and other tools for local development. For example, it can be used to manage multiple versions of Node.js, Python, Ruby, Go, etc. on the same machine.

Once [activated](/getting-started.html#activate-mise), mise can automatically switch between different versions of tools based on the directory you're in.
This means that if you have a project that requires Node.js 18 and another that requires Node.js 22, mise will automatically switch between them as you move between the two projects. See tools available for mise with in the [registry](/registry).

To know which tool version to use, mise will typically look for a `mise.toml` file in the current directory and its parents. To get an idea of how tools are specified, here is an example of a [mise.toml](/configuration.html) file:

```toml [mise.toml]
[tools]
node = '22'
python = '3'
ruby = 'latest'
```

It's also compatible
with asdf `.tool-versions` files as well as [idiomatic version files](/configuration#idiomatic-version-files) like `.node-version` and
`.ruby-version`. See [configuration](/configuration) for more details.

When specifying tool versions, you can also refer to environment variables defined in your config hierarchy,
including values produced by env directives like `_.source`, `_.file`, or env modules. These are resolved
before tool version templates are rendered.

::: info
mise is inspired by [asdf](https://asdf-vm.com) and can leverage asdf's
vast [plugin ecosystem](https://github.com/mise-plugins/registry)
under the hood. However, [it is *much* faster than asdf and has a more friendly user experience](./comparison-to-asdf).
:::

## How it works

mise manages development tools through a sophisticated but user-friendly system that automatically handles tool installation, version management, and environment setup.

### Tool Resolution Flow

When you enter a directory or run a command, mise follows this process:

1. **Configuration Discovery**: mise walks up the directory tree looking for configuration files (`mise.toml`, `.tool-versions`, etc.) and merges them hierarchically
2. **Tool Resolution**: mise resolves version specifications (like `node@latest` or `python@3`) to specific versions using registries and version lists
3. **Backend Selection**: mise chooses the appropriate [backend](/dev-tools/backend_architecture) to handle each tool (core, asdf, aqua, etc.)
4. **Installation Check**: mise verifies if the required tool versions are installed, automatically installing missing ones
5. **Environment Setup**: mise configures your `PATH` and environment variables to use the resolved tool versions

### Environment Integration

mise provides several ways to integrate with your development environment:

**Automatic Activation**: With `mise activate`, mise hooks into your shell prompt and automatically updates your environment when you change directories:

```bash
eval "$(mise activate zsh)"  # In your ~/.zshrc
cd my-project               # Automatically loads mise.toml tools
```

**On-Demand Execution**: Use `mise exec` to run commands with mise's environment without permanent activation:

```bash
mise exec -- node my-script.js  # Runs with tools from mise.toml
```

**Shims**: mise can create lightweight wrapper scripts that automatically use the correct tool versions:

```bash
mise activate --shims  # Creates shims instead of modifying PATH
```

### Path Management

mise modifies your `PATH` environment variable to prioritize the correct tool versions:

```bash
# Before mise
echo $PATH
/usr/local/bin:/usr/bin:/bin

# After mise activation in a project with node@20
echo $PATH
/home/user/.local/share/mise/installs/node/20.11.0/bin:/usr/local/bin:/usr/bin:/bin
```

This ensures that when you run `node`, you get the version specified in your project configuration, not a system-wide installation.

### Configuration Hierarchy

mise supports nested configuration that cascades from broad to specific settings:

```bash
~/.config/mise/config.toml      # Global defaults
~/work/mise.toml                # Work-specific tools
~/work/project/mise.toml        # Project-specific overrides
~/work/project/.tool-versions   # Legacy asdf compatibility
```

Each level can override or extend the previous ones, giving you fine-grained control over tool versions across different contexts.

## Tool Options

Tool options allow you to customize how tools are installed and configured. They support nested configurations for better organization, particularly useful for platform-specific settings.

### Table Format (Recommended)

The cleanest way to specify nested options is using TOML tables:

```toml
[tools."http:my-tool"]
version = "1.0.0"

[tools."http:my-tool".platforms]
macos-x64 = {
  url = "https://example.com/my-tool-macos-x64.tar.gz",
  checksum = "sha256:abc123",
}
linux-x64 = {
  url = "https://example.com/my-tool-linux-x64.tar.gz",
  checksum = "sha256:def456",
}
```

### Dotted Notation

You can also use dotted notation for simpler nested configurations:

```toml
[tools."http:my-tool"]
version = "1.0.0"
platforms.macos-x64.url = "https://example.com/my-tool-macos-x64.tar.gz"
platforms.linux-x64.url = "https://example.com/my-tool-linux-x64.tar.gz"
simple_option = "value"
```

### Generic Nested Support

Any backend can use nested options for organizing complex configurations:

```toml
[tools."custom:my-backend"]
version = "1.0.0"

[tools."custom:my-backend".database]
host = "localhost"
port = 5432

[tools."custom:my-backend".cache.redis]
host = "redis.example.com"
port = 6379
```

Internally, nested options are flattened to dot notation (e.g., `platforms.macos-x64.url`, `database.host`, `cache.redis.port`) for backend access.

### Tool postinstall commands

Run a command immediately after a tool finishes installing by adding a `postinstall` field to that tool's configuration. This is separate from `[hooks].postinstall` and applies only to when a specific tool is installed.

```toml
[tools]
node = { version = "22", postinstall = "corepack enable" }
```

Behavior:

* The command runs once the install completes successfully for that tool/version.
* The tool's bin path is on PATH during the command, so you can invoke the installed tool directly.
* Environment variables include `MISE_TOOL_INSTALL_PATH` pointing to the tool's install directory.
* If the install fails, the `postinstall` command is not run.

## OS-Specific Tools

You can restrict tools to specific operating systems using the `os` field:

```toml
[tools]
# Only install on Linux and macOS
ripgrep = { version = "latest", os = ["linux", "macos"] }

# Only install on Windows
"npm:windows-terminal" = { version = "latest", os = ["windows"] }

# Works with other options
"cargo:usage-cli" = {
    version = "latest",
    os = ["linux", "macos"],
    install_env = { RUST_BACKTRACE = "1" }
}
```

The `os` field accepts an array of operating system identifiers:

* `"linux"` - All Linux distributions
* `"macos"` - macOS (Darwin)
* `"windows"` - Windows

If a tool specifies an `os` restriction and the current operating system is not in the list, mise will skip installing and using that tool.

## Caching and Performance

mise uses intelligent caching to minimize overhead:

* **Version lists**: Cached daily to avoid repeated API calls
* **Installation artifacts**: Cached downloads to speed up reinstalls
* **Environment resolution**: Cached environment setups for faster shell prompts
* **Plugin metadata**: Cached plugin information for quicker operations

This ensures that mise adds minimal latency to your daily development workflow.

::: info
After activating, mise will update env vars like PATH whenever the directory is changed or the prompt is *displayed*.
See the [FAQ](/faq#what-does-mise-activate-do).
:::

After activating, every time your prompt displays it will call `mise hook-env` to fetch new
environment variables.
This should be very fast. It exits early if the directory wasn't changed or
`mise.toml`/`.tool-versions` files haven't been modified.

`mise` modifies `PATH` ahead of time so the runtimes are called directly. This means that calling a tool has zero overhead and commands like `which node` returns the real path to the binary.
Other tools like asdf only support shim files to dynamically locate runtimes when they're called which adds a small delay and can cause issues with some commands. See [shims](/dev-tools/shims) for more information.

## Common commands

Here are some of the most important commands when it comes to working with dev tools. Click the
header
for each command to go to its reference documentation page to see all available flags/options and
more
examples.

### [`mise use`](/cli/use)

For some users, `mise use` might be the only command you need to learn. It will do the following:

* Install the tool's plugin if needed
* Install the specified version
* Set the version as active (i.e. update the `PATH`)
* Update the current configuration file (`mise.toml` or `.tool-versions`)

```shell
> cd my-project
> mise use node@24
# download node, verify signature...
mise node@24.x.x ✓ installed
mise ~/my-project/mise.toml tools: node@24.x.x # mise.toml created/updated

> which node
~/.local/share/installs/node/24.x.x/bin/node
```

`mise use node@24` will install the latest version of node-24 and create/update the
`mise.toml`
config file in the local directory. Anytime you're in that directory, that version of `node` will be
used.

`mise use -g node@24` will do the same but update the [global config](/configuration.html#global-config-config-mise-config-toml) (~/.config/mise/config.toml) so
unless there is a config file in the local directory hierarchy, node-24 will be the default version
for
the user.

### [`mise install`](/cli/install)

`mise install` will install but not activate tools—meaning it will download/build/compile the tool
into `~/.local/share/mise/installs` but you won't be able to use it without "setting" the version
in a `.mise-toml` or `.tool-versions` file.

::: tip
If you're coming from `asdf`, there is no need to also run `mise plugin add` to first install
the plugin, that will be done automatically if needed. Of course, you can manually install plugins
if you wish or you want to use a plugin not in the default registry.
:::

There are many ways it can be used:

* `mise install node@20.0.0` - install a specific version
* `mise install node@20` - install the latest version matching this prefix
* `mise install node` - install whatever version of node currently specified in `mise.toml` (or other
  config files)
* `mise install` - install all plugins and tools specified in the config files

### [`mise exec`|`mise x`](/cli/exec)

`mise x` can be used for one-off commands using specific tools. e.g.: if you want to run a script
with python3.12:

```sh
mise x python@3.12 -- ./myscript.py
```

Python will be installed if it is not already. `mise x` will read local/global
`.mise-toml`/`.tool-versions` files
as well, so if you don't want to use `mise activate` or shims you can use mise by just prefixing
commands with
`mise x --`:

```sh
$ mise use node@20
$ mise x -- node -v
20.x.x
```

::: tip
If you use this a lot, an alias can be helpful:

```sh
alias mx="mise x --"
```

:::

Similarly, `mise run` can be used to [execute tasks](/tasks/) which will also activate the mise
environment with all of your tools.

## Auto-Install Mechanisms

mise provides several mechanisms to automatically install missing tools or versions as needed. Below, these are grouped by how and when they are triggered, with relevant settings for each. All mechanisms require the global [auto\_install](/configuration/settings.html#auto_install) setting to be enabled (**all auto\_install settings are enabled by default**).

### On-Demand Execution ([`mise x`](/cli/exec), [`mise r`](/cli/run))

When you run a command like [`mise x`](/cli/exec) or [`mise r`](/cli/run), mise will automatically install any missing tool versions required to execute the command.

* **When it triggers:** Whenever you use [`mise x`](/cli/exec) or [`mise r`](/cli/run) with a tool/version that is not yet installed.
* **How to control:**
  * Setting: [`exec_auto_install`](/configuration/settings.html#exec_auto_install) (default: true)
  * Setting: [`task_auto_install`](/configuration/settings.html#task_auto_install) (default: true)

### Command Not Found Handler (Shell Integration)

If you type a command in your shell (e.g., `node`) and it is not found, mise can attempt to auto-install the missing tool version if it knows which tool provides that binary.

* **When it triggers:** When a command is not found in the shell and the handler is enabled.
* **How to control:**
  * Setting: [`not_found_auto_install`](/configuration/settings.html#not_found_auto_install) (default: true)
* **Limitation:** Only works for tools that already have at least one version installed, since mise cannot know which tool provides a binary otherwise.

::: tip
Disable auto\_install for specific tools by setting [`auto_install_disable_tools`](/configuration/settings.html#auto_install_disable_tools) to a list of tool names.
:::

---

---
url: /environments/secrets/age.md
---
# Direct age Encryption&#x20;

Encrypt individual environment variable values directly in `mise.toml` using [age](https://github.com/FiloSottile/age) encryption. The age tool is not required—mise has support built-in.

This is a simple method of storing encrypted environment variables directly in `mise.toml`. You can use it simply by running `mise set --age-encrypt <key>=<value>`. By default, mise will use your ssh key (`~/.ssh/id_ed25519` or `~/.ssh/id_rsa`) if it exists.

* **Inline storage**: values live alongside other env vars in `mise.toml`
* **Multiple recipients**: x25519 age keys and SSH recipients
* **Automatic decryption**: at runtime when identities are available

## Quick start

1. \[optional] Generate an age key (if you want to create a new age key and don't want to use your ssh key):

```bash
age-keygen -o ~/.config/mise/age.txt
# Note the public key output for encryption
```

2. Encrypt a value:

```bash
mise set --age-encrypt --prompt DB_PASSWORD
# Enter value for DB_PASSWORD: [hidden input]
```

::: warning
It's recommended to use `--prompt` to avoid accidentally exposing the value to your shell history. You don't have to though, you can use `mise set --age-encrypt DB_PASSWORD="password123"`.
:::

3. Values are stored encrypted in `mise.toml` as an age directive:

```toml
[env]
DB_PASSWORD = { age = { value = "<base64>" } }
```

4. Decryption happens automatically:

```bash
mise env  # Variables are decrypted automatically
```

## CLI flags

* `--age-encrypt` — enable age encryption for the value
* `--age-recipient <KEY>` — x25519 recipient (can be set multiple times)
* `--age-ssh-recipient <PATH|KEY>` — SSH public key or path to `.pub`/private key (can be set multiple times)
* `--age-key-file <PATH>` — use recipients derived from an age identity file
* `--prompt` — prompt for the value to avoid accidentally exposing it to your shell history

If no recipients are provided explicitly, mise will try defaults (see below).

## Storage format

Encrypted values are stored as base64 along with a `format` field:

* `format = "raw"` — uncompressed ciphertext (typically for small values)
* `format = "zstd"` — zstd-compressed ciphertext (used when ciphertext > 1KB)

## Decryption identities

mise looks for identities in this order:

1. `MISE_AGE_KEY` environment variable
   * Can contain one or more raw `AGE-SECRET-KEY-...` lines, or an age identity file payload
2. `settings.age.identity_files` (list of paths)
3. `settings.age.key_file` (single path)
4. Default `~/.config/mise/age.txt` if it exists
5. SSH identities from `settings.age.ssh_identity_files` and common defaults (`~/.ssh/id_ed25519`, `~/.ssh/id_rsa`)

Decrypted values are always marked as redacted.

If no identities are found or decryption fails, mise returns the encrypted value as-is (non-strict behavior).

## Defaults for recipients (encryption)

When `--age-encrypt` is used without explicit recipients, mise attempts to derive recipients from:

* The public keys corresponding to identities in the default key file `~/.config/mise/age.txt`
* Public keys inferred from SSH private keys if a corresponding `.pub` file exists

If none are found, the command fails with an error asking you to provide recipients or configure `settings.age.key_file`.

## Settings

## Notes

* Feature is experimental; flags and behavior may change.
* `mise set KEY` will print the decrypted value

---

---
url: /directories.md
---
# Directory Structure

The following are the directories that mise uses.

::: tip
If you often find yourself using these directories (as I do), I suggest setting all of them to `~/.mise` for easy access.
:::

## `~/.config/mise`

* Override: `$MISE_CONFIG_DIR`
* Default: `${XDG_CONFIG_HOME:-$HOME/.config}/mise`

This directory stores the global configuration file `~/.config/mise/config.toml`. This is intended to go into your
dotfiles repo to share across machines.

## `~/.cache/mise`

* Override: `$MISE_CACHE_DIR`
* Default: `${XDG_CACHE_HOME:-$HOME/.cache}/mise`, *macOS: `~/Library/Caches/mise`.*

Stores internal cache that mise uses for things like the list of all available versions of a
plugin. Do not share this across machines. You may delete this directory any time mise isn't actively installing something.
Do this with `mise cache clear`.
See [Cache Behavior](/cache-behavior) for more information.

## `~/.local/state/mise`

* Override: `$MISE_STATE_DIR`
* Default: `${XDG_STATE_HOME:-$HOME/.local/state}/mise`

Used for storing state local to the machine such as which config files are trusted. These should not be shared across
machines.

## `~/.local/share/mise`

* Override: `$MISE_DATA_DIR`
* Default: `${XDG_DATA_HOME:-$HOME/.local/share}/mise`

This is the main directory that mise uses and is where plugins and tools are installed into.
It is nearly identical to `~/.asdf` in asdf, so much so that you may be able to get by
symlinking these together and using asdf and mise simultaneously. (Supporting this isn't a
project goal, however).

This directory *could* be shared across machines but only if they run the same OS/arch. In general I wouldn't advise
doing so.

### `~/.local/share/mise/downloads`

This is where plugins may optionally cache downloaded assets such as tarballs. Use the
`always_keep_downloads` setting to prevent mise from removing files from here.

### `~/.local/share/mise/plugins`

mise installs plugins to this directory when running `mise plugins install`. If you are working on a
plugin, I suggest
symlinking it manually by running:

```sh
ln -s ~/src/mise-my-tool ~/.local/share/mise/plugins/my-tool
```

### `~/.local/share/mise/installs`

This is where tools are installed to when running `mise install`. For example, `mise install
node@20.0.0` will install to `~/.local/share/mise/installs/node/20.0.0`

This will also create other symlinks to this directory for version prefixes ("20" and "20.15")
and matching aliases ("lts", "latest").
For example:

```sh
$ tree ~/.local/share/mise/installs/node
20 -> ./20.15.0
20.15 -> ./20.15.0
lts -> ./20.15.0
latest -> ./20.15.0
```

You can set the `MISE_INSTALLS_DIR` environment variable to override this location.

### `~/.local/share/mise/shims`

This is where mise places shims. Generally these are used for IDE integration or if `mise activate`
does not work for some reason.

---

---
url: /direnv.md
---
# direnv&#x20;

[direnv](https://direnv.net) and mise both manage environment variables based on directory. Because
they both analyze
the current environment variables before and after their respective "hook" commands are run, they
can sometimes conflict with each other.

::: warning
The official stance is you should not use direnv with mise. Issues arising
from incompatibilities are not considered bugs. If mise has feature gaps
that direnv resolves, please open an issue so we can close those gaps.
While that's the official stance, the reality is mise and direnv usually
will work together just fine despite this. It's only more advanced use-cases
where problems arise.
:::

If you have an issue, it's likely to do with the ordering of PATH. This means it would
really only be a problem if you were trying to manage the same tool with direnv and mise. For
example,
you may use `layout python` in an `.envrc` but also be maintaining a `.tool-versions` file with
python
in it as well.

A more typical usage of direnv would be to set some arbitrary environment variables, or add
unrelated
binaries to PATH. In these cases, mise will not interfere with direnv.

## mise inside of direnv (`use mise` in `.envrc`)

::: warning
`use mise` is deprecated and no longer supported. If `mise activate` does
not fit your use-case please post an issue.
:::

If you do encounter issues with `mise activate`, or just want to use direnv in an alternate way,
this is a simpler setup that's less likely to cause issues—at the cost of functionality.

This may be required if you want to use direnv's `layout python` with mise. Otherwise there are
situations where mise will override direnv's PATH. `use mise` ensures that direnv always has
control.

To do this, first use `mise` to build a `use_mise` function that you can use in `.envrc` files:

```sh
mise direnv activate > ~/.config/direnv/lib/use_mise.sh
```

Now in your `.envrc` file add the following:

```sh
use mise
```

direnv will now call mise to export its environment variables. You'll need to make sure to
add `use_mise`
to all projects that use mise (or use direnv's `source_up` to load it from a subdirectory). You can
also add `use mise` to `~/.config/direnv/direnvrc`.

Note that in this method direnv typically won't know to refresh `.tool-versions` files
unless they're at the same level as a `.envrc` file. You'll likely always want to have
a `.envrc` file next to your `.tool-versions` for this reason. To make this a little
easier to manage, I encourage *not* actually using `.tool-versions` at all, and instead
setting environment variables entirely in `.envrc`:

```sh
export MISE_NODE_VERSION=20.0.0
export MISE_PYTHON_VERSION=3.11
```

Of course if you use `mise activate`, then these steps won't have been necessary and you can use
mise
as if direnv was not used.

If you continue to struggle, you can also try using the [shims method](dev-tools/shims.md).

### Do you need direnv?

While making mise compatible with direnv is, and will always be a major goal of this project, I also
want mise to be capable of replacing direnv if needed. This is why mise includes support for
managing
env vars and [virtualenv](lang/python.md#automatic-virtualenv-activation)
for python using `mise.toml`.

---

---
url: /dev-tools/backends/dotnet.md
---
# Dotnet backend

The code for this is inside the mise repository at [`./src/backend/dotnet.rs`](https://github.com/jdx/mise/blob/main/src/backend/dotnet.rs).

::: tip Important
The dotnet backend requires having the .NET runtime installed. You can install it using mise:

```sh
# Install the latest version
mise use dotnet

# Or install a specific version (8, 9, etc.)
mise use dotnet@8
mise use dotnet@9
```

This will install the .NET runtime, which is required for dotnet tools to work properly.
:::

## Usage

The following installs the latest version of [GitVersion.Tool](https://gitversion.net/) and
sets it as the active version on PATH:

```sh
$ mise use dotnet:GitVersion.Tool@5.12.0
$ dotnet-gitversion /version
5.12.0+Branch.support-5.x.Sha.3f75764963eb3d7956dcd5a40488c074dd9faf9e
```

The version will be set in `~/.config/mise/config.toml` with the following format:

```toml
[tools]
"dotnet:GitVersion.Tool" = "5.12.0"
```

```sh
$ mise use dotnet:GitVersion.Tool
$ dotnet-gitversion /version
6.1.0+Branch.main.Sha.8856e3041dbb768118a55a31ad4e465ae70c6767
```

The version will be set in `~/.config/mise/config.toml` with the following format:

```toml
[tools]
"dotnet:GitVersion.Tool" = "latest"
```

### Supported Dotnet Syntax

| Description                           | Usage                           |
| ------------------------------------- | ------------------------------- |
| Dotnet shorthand latest version       | `dotnet:GitVersion.Tool`        |
| Dotnet shorthand for specific version | `dotnet:GitVersion.Tool@5.12.0` |

## Settings

Set these with `mise settings set [VARIABLE] [VALUE]` or by setting the environment variable listed.

## Tool Options

The following [tool-options](/dev-tools/#tool-options) are available for the `dotnet` backend—these
go in `[tools]` in `mise.toml`.

---

---
url: /lang/elixir.md
---
# Elixir

`mise` can be used to manage multiple [`elixir`](https://elixir-lang.org/) versions on the same system.

> The following are instructions for using the elixir core plugin. This is used when there isn't a git plugin installed named "elixir".

The code for this is inside the mise repository at
[`./src/plugins/core/elixir.rs`](https://github.com/jdx/mise/blob/main/src/plugins/core/elixir.rs).

## Usage

Use the latest stable version of elixir:

```sh
mise use -g erlang elixir
```

Note that [`erlang`](/lang/erlang.html) is required to install `elixir`.

---

---
url: /env-plugin-development.md
---
# Environment Plugin Development

Environment plugins are a special type of mise plugin that provide environment variables and PATH modifications without managing tool versions. They're ideal for integrating external services, managing secrets, and standardizing environment configuration across teams.

Unlike [tool plugins](tool-plugin-development.md) and [backend plugins](backend-plugin-development.md), environment plugins:

* ✅ Don't implement version management (`Available`, `PreInstall`, `PostInstall` hooks)
* ✅ Only implement environment hooks (`MiseEnv`, `MisePath`)
* ✅ Are configured via `env._.<plugin-name>` syntax
* ✅ Can accept configuration options as TOML values
* ✅ Execute on every environment activation

## Quick Start

The fastest way to create an environment plugin is to use the [mise-env-plugin-template](https://github.com/jdx/mise-env-plugin-template).

::: tip
The [mise-env-plugin-template](https://github.com/jdx/mise-env-plugin-template) provides a ready-to-use starting point with LuaCATS type definitions, stylua formatting, and hk linting pre-configured.
:::

To get started:

```bash
# Clone the template
git clone https://github.com/jdx/mise-env-plugin-template my-env-plugin
cd my-env-plugin

# Customize for your use case
# Edit metadata.lua, hooks/mise_env.lua, hooks/mise_path.lua
```

## Plugin Structure

Environment plugins are implemented in Lua (version 5.1 at the moment). A minimal environment plugin has this structure:

```
my-env-plugin/
├── metadata.lua           # Plugin metadata
└── hooks/
    ├── mise_env.lua      # Returns environment variables (required)
    └── mise_path.lua     # Returns PATH entries (optional)
```

### metadata.lua

The `metadata.lua` file defines your plugin's basic information:

```lua
PLUGIN = {}

--- Plugin name (required)
PLUGIN.name = "my-env-plugin"

--- Plugin version (required)
PLUGIN.version = "1.0.0"

--- Plugin description (required)
PLUGIN.description = "Provides environment variables for my service"

--- Plugin homepage (optional)
PLUGIN.homepage = "https://github.com/username/my-env-plugin"

--- Plugin license (optional)
PLUGIN.license = "MIT"

--- Minimum mise/vfox version required (optional)
PLUGIN.minRuntimeVersion = "0.3.0"
```

### hooks/mise\_env.lua

The `MiseEnv` hook returns environment variables to set:

```lua
function PLUGIN:MiseEnv(ctx)
    -- Access configuration from mise.toml via ctx.options
    local api_url = ctx.options.api_url or "https://api.example.com"
    local debug = ctx.options.debug or false

    -- Return array of environment variables
    return {
        {
            key = "API_URL",
            value = api_url
        },
        {
            key = "DEBUG",
            value = tostring(debug)
        },
        {
            key = "SERVICE_TOKEN",
            value = get_token_from_somewhere()  -- Your custom logic
        }
    }
end
```

::: tip
When `cmd.exec()` is called from `MiseEnv` or `MisePath` hooks, it inherits the mise-constructed environment — including `_.path` entries and environment variables from preceding directives. If the module directive is configured with `tools = true` (e.g., `_.my-plugin = { tools = true }`), tool installation bin paths are also included, so mise-managed tools are directly callable (e.g., `cmd.exec("node --version")`).
:::

**Return value**: Either a simple array of env keys, or a table with caching metadata.

Simple format - array of tables, each with:

* `key` (string, required): Environment variable name
* `value` (string, required): Environment variable value

Extended format - table with:

* `env` (array, required): Array of `{key, value}` tables (same as simple format)
* `cacheable` (boolean, optional): If `true`, mise can cache this plugin's output. Default: `false`
* `watch_files` (array of strings, optional): File paths to watch for changes. If any file's mtime changes, the cache is invalidated.

Example using extended format with caching:

```lua
function PLUGIN:MiseEnv(ctx)
    local config_path = ctx.options.config_file or "config.json"
    local config = load_config(config_path)

    return {
        cacheable = true,
        watch_files = {config_path},
        env = {
            {key = "API_URL", value = config.api_url},
            {key = "API_KEY", value = config.api_key}
        }
    }
end
```

When `cacheable = true`, mise will cache the environment variables and only re-execute the plugin when:

* Any file in `watch_files` changes
* The mise configuration changes
* The cache TTL expires (configured via `env_cache_ttl` setting)

::: tip
For caching to work, users must enable the `env_cache` setting:

```toml
# ~/.config/mise/config.toml
[settings]
env_cache = true
```

:::

### hooks/mise\_path.lua

The `MisePath` hook returns directories to add to PATH (optional):

```lua
function PLUGIN:MisePath(ctx)
    -- Return array of paths to prepend to PATH
    local paths = {
        "/opt/my-service/bin"
    }

    -- Optionally add user-configured path
    if ctx.options.custom_bin_path then
        table.insert(paths, ctx.options.custom_bin_path)
    end

    return paths
end
```

**Return value**: Array of strings (directory paths)

## Context Object

Both hooks receive a `ctx` parameter with:

* **`ctx.options`**: TOML table of user configuration from `mise.toml`

For environment plugins, `ctx.options` is the primary way to accept user configuration.

## Configuration in mise.toml

Users configure environment plugins using the `env._` directive:

Simple activation with no options:

```toml
[env]
_.my-env-plugin = {}
```

With configuration options:

```toml
[env]
_.my-env-plugin = {
  api_url = "https://prod.api.example.com",
  debug = false,
  custom_bin_path = "/custom/path/bin",
}
```

All fields in the TOML table are passed to your hooks as `ctx.options`.

## Complete Example: Secret Manager Plugin

Here's a complete example of a plugin that fetches secrets from an external service:

**metadata.lua**:

```lua
PLUGIN = {}
PLUGIN.name = "vault-secrets"
PLUGIN.version = "1.0.0"
PLUGIN.description = "Fetch secrets from HashiCorp Vault"
PLUGIN.minRuntimeVersion = "0.3.0"
```

**hooks/mise\_env.lua**:

```lua
local http = require("http")
local json = require("json")

function PLUGIN:MiseEnv(ctx)
    local vault_url = ctx.options.vault_url or error("vault_url required")
    local secrets_path = ctx.options.secrets_path or error("secrets_path required")
    local vault_token = os.getenv("VAULT_TOKEN") or error("VAULT_TOKEN not set")

    -- Fetch secrets from Vault
    local url = vault_url .. "/v1/" .. secrets_path
    local response = http.get({
        url = url,
        headers = {
            ["X-Vault-Token"] = vault_token
        }
    })

    if response.status_code ~= 200 then
        error("Failed to fetch secrets: " .. response.status_code)
    end

    local data = json.decode(response.body)
    local env_vars = {}

    -- Convert Vault secrets to environment variables
    for key, value in pairs(data.data.data) do
        table.insert(env_vars, {
            key = key,
            value = value
        })
    end

    return env_vars
end
```

**Usage in mise.toml**:

```toml
[env]
_.vault-secrets = {
  vault_url = "https://vault.example.com",
  secrets_path = "secret/data/myapp/production",
}
```

## Available Lua Modules

Environment plugins have access to mise's built-in Lua modules:

* **`http`**: Make HTTP requests
* **`json`**: Encode/decode JSON
* **`file`**: Read/write files
* **`cmd`**: Execute shell commands
* **`strings`**: String manipulation utilities
* **`env`**: Access environment variables

See [Plugin Lua Modules](/plugin-lua-modules.html) for complete documentation.

## Best Practices

### 1. Provide Sensible Defaults

```lua
function PLUGIN:MiseEnv(ctx)
    local api_url = ctx.options.api_url or "https://api.example.com"
    local timeout = ctx.options.timeout or 30

    -- ...
end
```

### 2. Validate Required Options

```lua
function PLUGIN:MiseEnv(ctx)
    if not ctx.options.api_key then
        error("api_key is required in mise.toml configuration")
    end

    -- ...
end
```

### 3. Handle Errors Gracefully

```lua
function PLUGIN:MiseEnv(ctx)
    local response = http.get({url = ctx.options.api_url})

    if response.status_code ~= 200 then
        error("API request failed: " .. response.status_code .. " - " .. response.body)
    end

    -- ...
end
```

### 4. Use Built-in Caching for Expensive Operations

For plugins that fetch data from external services, use mise's built-in caching by returning the extended format with `cacheable = true`:

```lua
function PLUGIN:MiseEnv(ctx)
    local config_file = ctx.options.config_file or "secrets.json"

    -- Fetch secrets (mise will cache the result)
    local secrets = fetch_secrets(ctx.options)

    return {
        cacheable = true,
        watch_files = {config_file},  -- Re-fetch if config changes
        env = secrets
    }
end
```

This is preferred over manual caching because:

* mise handles cache invalidation automatically
* Cache is encrypted with session-scoped keys
* Integrates with `mise cache clear` and `mise cache prune`
* Respects the `env_cache_ttl` setting

Note: Users must enable `env_cache = true` in their settings for caching to work.

### 5. Support Multiple Environments

```lua
function PLUGIN:MiseEnv(ctx)
    local env_name = ctx.options.environment or "development"

    -- Load different config based on environment
    local config = load_config(env_name)

    return {
        {key = "ENV", value = env_name},
        {key = "API_URL", value = config.api_url},
        -- ...
    }
end
```

## Testing Your Plugin

### Local Testing

1. Link your plugin for development:

```bash
mise plugin link my-env-plugin /path/to/my-env-plugin
```

2. Configure it in `mise.toml`:

```toml
[env]
_.my-env-plugin = { test_option = "value" }
```

3. Test the environment:

```bash
# See environment variables
mise env | grep MY_

# Run a command with the environment
mise exec -- env | grep MY_

# Debug with MISE_DEBUG
MISE_DEBUG=1 mise env
```

### Common Issues

**Plugin not found**: Make sure you've installed/linked the plugin:

```bash
mise plugin ls
```

**Hook not executing**: Enable debug logging:

```bash
MISE_DEBUG=1 mise env
```

**Options not passed**: Verify TOML syntax in `mise.toml`:

```toml
[env]
# Correct: TOML table
_.my-plugin = { key = "value" }

# Wrong: String value
_.my-plugin = "value"  # This won't work
```

## Publishing Your Plugin

Once your environment plugin is ready:

1. **Create a GitHub repository** for your plugin
2. **Add a README** with usage instructions
3. **Tag releases** following semantic versioning
4. (Optional) share the repository URL so others can install it directly with `mise plugin install`.

See [Plugin Publishing](/plugin-publishing.html) for detailed instructions.

## Examples

* [mise-env-sample](https://github.com/jdx/mise-env-plugin-template) - Simple example showing basic usage
* The [mise-plugins](https://github.com/mise-plugins) organization currently hosts tool plugins only—add your environment plugin there (or share it with the community) so others can learn from more examples

## Migration from Tool Plugins

If you have an existing tool plugin that only sets environment variables, you can simplify it to an environment-only plugin:

**Before** (tool plugin with unused hooks):

```
my-plugin/
├── metadata.lua
└── hooks/
    ├── available.lua        # Returns empty list
    ├── pre_install.lua      # Not used
    ├── post_install.lua     # Not used
    └── env_keys.lua         # Actually sets env vars
```

**After** (environment plugin):

```
my-plugin/
├── metadata.lua
└── hooks/
    └── mise_env.lua         # Clean and focused
```

## Related Documentation

* [Plugin Overview](/plugins.html) - Overview of all plugin types
* [Tool Plugin Development](/tool-plugin-development.html) - For plugins that manage tool versions
* [Backend Plugin Development](/backend-plugin-development.html) - For multi-tool backends
* [Plugin Lua Modules](/plugin-lua-modules.html) - Available Lua APIs
* [Plugin Publishing](/plugin-publishing.html) - Publishing your plugin
* [Environment Variables](/environments/) - How mise manages environments

---

---
url: /environments.md
---
# Environments

> Like [direnv](https://github.com/direnv/direnv) it
> manages *environment variables* for
> different project directories.

Use mise to specify environment variables used for different projects.

To get started, create a `mise.toml` file in the root of your project directory:

```toml [mise.toml]
[env]
NODE_ENV = 'production'
```

To clear an env var, set it to `false`:

```toml [mise.toml]
[env]
NODE_ENV = false # unset a previously set NODE_ENV
```

You can also use the CLI to get/set env vars:

```sh
mise set NODE_ENV=development
# mise set NODE_ENV
# development

mise set
# key       value        source
# NODE_ENV  development  mise.toml

cat mise.toml
# [env]
# NODE_ENV = 'development'

mise unset NODE_ENV
```

Additionally, the [mise env \[--json\] \[--dotenv\]](/cli/env.html) command can be used to export the environment variables in various formats (including `PATH` and environment variables set by tools or plugins).

## Using environment variables

Environment variables are available when using [`mise x|exec`](/cli/exec.html), or with [`mise r|run`](/cli/run.html) (i.e. with [tasks](/tasks/)):

```shell
mise set MY_VAR=123
mise exec -- echo $MY_VAR
# 123
```

You can of course combine them with [tools](/dev-tools/):

```sh
mise use node@24
mise set MY_VAR=123
cat mise.toml
# [tools]
# node = '24'
# [env]
# MY_VAR = '123'
mise exec -- node --eval 'console.log(process.env.MY_VAR)'
# 123
```

If [mise is activated](/getting-started.html#activate-mise), it will automatically set environment variables in the current shell session when you `cd` into a directory.

```shell
cd /path/to/project
mise set NODE_ENV=production
cat mise.toml
# [env]
# NODE_ENV = 'production'

echo $NODE_ENV
# production
```

If you are using [`shims`](/dev-tools/shims.html), the environment variables will be available when using the shim:

```shell
mise set NODE_ENV=production
mise use node@24
# using the absolute path for the example
~/.local/share/mise/shims/node --eval 'console.log(process.env.NODE_ENV)'
```

Finally, you can also use [`mise en`](/cli/en.html) to start a new shell session with the environment variables set.

```shell
mise set FOO=bar
mise en
> echo $FOO
# bar
```

## Environment in tasks

It is also possible to define environment inside a task

```toml [mise.toml]
[tasks.print]
run = "echo $MY_VAR"
env = { _.file = '/path/to/file.env', "MY_VAR" = "my variable" }
```

## Lazy eval

Environment variables typically are resolved before tools—that way you can configure tool installation
with environment variables. However, sometimes you want to access environment variables produced by
tools. To do that, turn the value into a map with `tools = true`:

```toml
[env]
MY_VAR = { value = "tools path: {{env.PATH}}", tools = true }
_.path = { path = ["{{env.GEM_HOME}}/bin"], tools = true } # directives may also set tools = true
NODE_VERSION = { value = "{{ tools.node.version }}", tools = true }
```

## Redactions

Variables can be redacted from the output by setting `redact = true`:

```toml
[env]
SECRET = { value = "my_secret", redact = true }
_.file = { path = ".env.json", redact = true }
```

You can also use the `redactions` array to mark multiple environment variables as sensitive:

```toml
redactions = ["SECRET_*", "*_TOKEN", "PASSWORD"]
[env]
SECRET_KEY = "sensitive_value"
API_TOKEN = "token_123"
PASSWORD = "my_password"
```

### Viewing Redacted Environment Variables

The `mise env` command provides flags to work with redacted variables:

```bash
# Show only redacted environment variables
mise env --redacted

# Show only values (useful for piping)
mise env --values

# Show only values of redacted variables
mise env --redacted --values
```

::: danger
Because mise may output sensitive values that could show up in CI logs you'll need to be configure your CI setup
to know which values are sensitive.

For example, when using GitHub Actions, you should use `::add-mask::` to prevent secrets from appearing in logs:

```bash
# In a GitHub Actions workflow
for value in $(mise env --redacted --values); do
  echo "::add-mask::$value"
done
```

Note: If you're using [mise-action](https://github.com/jdx/mise-action), it will automatically redact values marked with `redact = true` or matching patterns in the `redactions` array.
:::

## Required Variables

You can mark environment variables as required by setting `required = true`. This ensures that the variable is defined either before mise runs or in a later config file (like `mise.local.toml`):

```toml
[env]
DATABASE_URL = { required = true }
API_KEY = { required = true }
```

You can also provide help text to guide users on how to set the variable:

```toml
[env]
DATABASE_URL = {
  required = "Set DATABASE_URL to your PostgreSQL connection string (e.g., postgres://user:pass@localhost/dbname)",
}
API_KEY = {
  required = "Get your API key from https://example.com/api-keys",
}
AWS_REGION = {
  required = "Set to your AWS region (e.g., us-east-1, eu-west-1)",
}
```

When a required variable is missing, mise will show the help text in the error message to assist users.

### Required Variable Behavior

When a variable is marked as `required = true`, mise validates that it is defined through one of these sources:

1. **Pre-existing environment** - Variable was set before running mise
2. **Later config file** - Variable is defined in a config file processed after the one declaring it as required

```toml
# In mise.toml
[env]
DATABASE_URL = { required = true }
```

```toml
# In mise.local.toml (processed later)
[env]
DATABASE_URL = "postgres://prod.example.com/db"  # This satisfies the requirement
```

### Validation Behavior

* **Regular commands** (like `mise env`): Fail with clear error messages when required variables are missing
* **Shell activation** (`hook-env`): Warns about missing required variables but continues execution to avoid breaking shell setup

```bash
# This will fail if DATABASE_URL is not pre-defined or in a later config
$ mise env
Error: Required environment variable 'DATABASE_URL' is not defined...

# This will warn but continue (used by shell activation)
$ mise hook-env --shell bash
mise WARN Required environment variable 'DATABASE_URL' is not defined...
# Shell activation continues successfully
```

### Use Cases

Required variables are useful for:

* **Database connections** - Ensure critical connection strings are explicitly set
* **API keys** - Require explicit configuration of sensitive credentials
* **Environment-specific settings** - Force explicit configuration per environment
* **Team collaboration** - Document which variables team members must configure

```toml
[env]
# API keys (must be set in environment or mise.local.toml)
STRIPE_API_KEY = { required = true }
SENTRY_DSN = { required = true }

# Database connection (must be set in environment or mise.local.toml)
DATABASE_URL = { required = true }

# Feature flags (must be explicitly configured)
ENABLE_BETA_FEATURES = { required = true }
```

## `config_root`

`config_root` is the canonical project root directory that mise uses when resolving relative paths inside configuration files. Generally, when you use relative paths in mise you're referring to this directory.

* When your config lives at nested paths like `.config/mise/config.toml` or `.mise/config.toml`, `config_root` points to the project directory that contains those files (for example, `/path/to/project`).
* When your config lives at the project root (for example, `mise.toml`), `config_root` is simply the current directory.
* Relative paths in environment directives are resolved against `config_root` so they behave consistently regardless of where the config file itself lives.

Here's some example config files and their `config_root`:

| Config File                                 | `config_root` |
| ------------------------------------------- | ------------- |
| `~/src/foo/.config/mise/conf.d/config.toml` | `~/src/foo`   |
| `~/src/foo/.config/mise/config.toml`        | `~/src/foo`   |
| `~/src/foo/.mise/config.toml`               | `~/src/foo`   |
| `~/src/foo/mise.toml`                       | `~/src/foo`   |

You can see the implementation in [config\_root.rs](https://github.com/jdx/mise/blob/main/src/config/config_file/config_root.rs).

Examples:

```toml
[env]
# These are equivalent and both resolve against the project root
_.path = ["tools/bin", "{{config_root}}/tools/bin"]

# Likewise, a relative source path resolves against the project root
_.source = "scripts/env.sh"          # == "{{config_root}}/scripts/env.sh"
```

## `env._` directives

`env._.*` define special behavior for setting environment variables. (e.g.: reading env vars
from a file). Since nested environment variables do not make sense,
we make use of this fact by creating a key named "\_" which is a
TOML table for the configuration of these directives.

### `env._.file`

In `mise.toml`: `env._.file` can be used to specify a [dotenv](https://dotenv.org) file to load.

```toml
[env]
_.file = '.env'
```

::: info
This uses [dotenvy](https://crates.io/crates/dotenvy) under the hood. If you have problems with
the way `env._.file` works, you will likely need to post an issue there,
not to mise since there is not much mise can do about the way that crate works.
:::

The `env._.file` directive supports:

* A single file as a string or an object
* Multiple files as an array of strings and objects
* Using relative or absolute paths
* Using `dotenv`, `json`, or `yaml` file formats
* The `redact` and `tools` options

```toml
[env]
_.file = '.env.yaml'
```

```toml
[env]
# Load env from the dotenv file after tools have defined environment variables
_.file = { path = ".env", tools = true }
```

```toml
[env]
_.file = [
    # Load env from the json file relative to this config file
    '.env.json',
    # Load env from the dotenv file at an absolute path
    '/User/bob/.env',
    # Load env from the yaml file relative to this config file and redacts the values
    { path = ".secrets.yaml", redact = true }
]
```

You can set [`MISE_ENV_FILE=.env`](/configuration#mise-env-file) to automatically load dotenv files in any
directory.

See [secrets](/environments/secrets/) for ways to read encrypted files with `env._.file`.

### `env._.path`

`PATH` is treated specially. Use `env._.path` to add extra directories to the `PATH`, making any executables in those directories available in the shell without needing to type the full path:

```toml
[env]
_.path = './bin'
```

The `env._.path` directive supports:

* A single path as a string or an object
* Multiple paths as an array of strings and objects
* Using relative or absolute paths
* The `tools` option

```toml
[env]
_.path = 'scripts'
```

```toml
[env]
# Define this path directory after tools have defined environment variables
_.path = { path = ["{{env.GEM_HOME}}/bin"], tools = true }
```

```toml
[env]
_.path = [
    # adds an absolute path
    "~/.local/share/bin",
    # adds a path relative to the project root (config_root)
    "{{config_root}}/node_modules/.bin",
    # adds a relative path (equivalent to "{{config_root}}/tools/bin")
    "tools/bin",
]
```

Relative paths like `tools/bin` or `./tools/bin` are resolved against `{{config_root}}`. For example, with a config file at `/path/to/project/.config/mise/config.toml`, `tools/bin` resolves to `/path/to/project/tools/bin`.

### `env._.source`

Source an external bash script and pull exported environment variables out of it:

```toml
[env]
_.source = "./script.sh"
```

::: info
This **must** be a script that runs in bash as if it were executed like this:

```sh
source ./script.sh
```

The shebang will be **ignored**. See [#1448](https://github.com/jdx/mise/discussions/6734)
for a potential alternative that would work with binaries or other script languages.
:::

The `env._.source` directive supports:

* A single source as a string or an object
* Multiple sources as an array of strings and objects
* Using relative or absolute paths
* The `redact` and `tools` options

```toml
[env]
_.source = 'source.sh'
```

```toml
[env]
# Source this file after tools have defined environment variables
_.source = { path = "my/env.sh", tools = true }
```

```toml
[env]
_.source = [
    # Sources the file relative to the config root
    './scripts/base.sh',
    # Sources a file at an absolute path
    '/User/bob/env.sh',
    # Sources the file relative to the config root and redacts the values
    { path = ".secrets.sh", redact = true }
]
```

## Plugin-provided `env._` Directives

Plugins can provide their own `env._` directives that dynamically set environment variables and modify your PATH. This is particularly useful for:

* Integrating with external secret management systems
* Setting environment variables based on dynamic conditions
* Managing complex PATH configurations
* Providing team-wide environment standardization

### Basic Usage

Simple plugin activation:

```toml
[env]
_.my-plugin = {}
```

Plugin with configuration options:

```toml
[env]
_.my-plugin = { option1 = "value1", option2 = "value2" }
```

### How It Works

When you use `env._.<plugin-name>`, mise:

1. Loads the plugin from your installed plugins
2. Calls the plugin's `MiseEnv` hook to get environment variables
3. Calls the plugin's `MisePath` hook to get PATH entries (if defined)
4. Applies these to your environment when running `mise env` or using shell integration

The configuration options you provide (the TOML table after `=`) are passed to the plugin's hooks via `ctx.options`, allowing plugins to be configured per-project or per-environment.

### Example: Secret Management Plugin

```toml
[env]
# Fetch secrets from a vault
_.vault-secrets = {
  vault_url = "https://vault.example.com",
  secrets_path = "secret/myapp"
}
```

The plugin could then fetch secrets from HashiCorp Vault and expose them as environment variables.

### Example: Dynamic Environment Plugin

```toml
[env]
# Set environment based on git branch
_.git-env = { production_branch = "main" }
```

The plugin could detect the current git branch and set `ENVIRONMENT=production` when on `main`, or `ENVIRONMENT=development` otherwise.

### Creating Environment Plugins

See [Environment Plugins](/plugins#environment-plugins) in the Plugins documentation for a complete guide to creating your own environment plugins.

For a working example, see the [mise-env-plugin-template](https://github.com/jdx/mise-env-plugin-template) repository.

## Multiple `env._` Directives

It may be necessary to use multiple `env._` directives, however TOML fails with this syntax
because it has 2 identical keys in a table:

```toml
[env]
_.source = "./script_1.sh"
_.source = "./script_2.sh" # invalid // [!code error]
```

For this use-case, you can optionally make `[env]` an array-of-tables instead by using `[[env]]` instead:

```toml
[[env]]
_.source = "./script_1.sh"
[[env]]
_.source = "./script_2.sh"
```

It works identically but you can have multiple tables.

## Templates

Environment variable values can be templates, see [Templates](/templates) for details.

```toml
[env]
LD_LIBRARY_PATH = "/some/path:{{env.LD_LIBRARY_PATH}}"
```

## Using env vars in other env vars

You can use the value of an environment variable in later env vars:

```toml
[env]
MY_PROJ_LIB = "{{config_root}}/lib"
LD_LIBRARY_PATH = "/some/path:{{env.MY_PROJ_LIB}}"
```

Of course the ordering matters when doing this.

## Shell-style variable expansion

As a simpler alternative to Tera templates for referencing env vars, you can use shell-style `$VAR` syntax
by enabling the [`env_shell_expand`](/configuration/settings.html#env_shell_expand) setting:

```toml
[settings]
env_shell_expand = true

[env]
MY_PROJ_LIB = "{{config_root}}/lib"
LD_LIBRARY_PATH = "$MY_PROJ_LIB:$LD_LIBRARY_PATH"
```

Supported syntax:

| Syntax            | Description                                                                           |
| ----------------- | ------------------------------------------------------------------------------------- |
| `$VAR`            | Expands to the value of `VAR`                                                         |
| `${VAR}`          | Same, useful when followed by alphanumeric characters (e.g., `${VAR}_suffix`)         |
| `${VAR:-default}` | Uses `default` if `VAR` is unset or empty                                             |
| `${VAR:-}`        | Expands to empty string if `VAR` is unset (suppresses the undefined variable warning) |

Expansion runs after Tera template rendering, so both syntaxes can be mixed.
Undefined variables without a default are left unexpanded and produce a warning.

The setting is a 3-way toggle:

* **`true`** — enable shell expansion
* **`false`** — disable shell expansion, no warning
* **unset** (default) — disable shell expansion but warn if `$` is detected

::: tip
Shell expansion will become the default behavior in the 2026.7.0 release. Set `env_shell_expand = true` now to opt in early, or `env_shell_expand = false` to preserve the current behavior.
:::

---

---
url: /lang/erlang.md
---
# Erlang

`mise` can be used to install and manage multiple versions of [erlang](https://www.erlang.org/) on the same system.

> The following are instructions for using the erlang core plugin.
> This is used when there isn't a git plugin installed named "erlang".

The code for this is inside the mise repository at
[`./src/plugins/core/erlang.rs`](https://github.com/jdx/mise/blob/main/src/plugins/core/erlang.rs).

## Usage

The following installs erlang and makes it the global default:

```sh
mise use -g erlang@26
```

See available versions with `mise ls-remote erlang`.

## kerl

The plugin uses [kerl](https://github.com/kerl/kerl) under the hood to build erlang.
See kerl's docs for information on configuring kerl.

## Settings

---

---
url: /errors.md
---
# Errors

TODO

---

---
url: /external-resources.md
---
# External Resources

Links to articles, videos, and other resources that are relevant to mise.

* 2025-04-09 - Keeping your Swift apps' sensitive data secret - <https://tuist.dev/blog/2025/04/09/secrets>
* 2025-02-17 - hk: git hook manager that pairs well with mise - <https://hk.jdx.dev>
* 2025-02-17 - pitchfork: process manager for developers that pairs well with mise - <https://pitchfork.jdx.dev>
* 2025-02-04 - A Mise guide for Swift developers - <https://tuist.dev/blog/2025/02/04/mise>
* 2025-01-26 - devtools.fm: Jeff Dickey - Mise, Usage, and Pitchfork and the Future of Polyglot Tools - <https://www.devtools.fm/episode/129>
* 2025-01-12 - \[fr] Mise-En-Place: Simplifiez la Gestion de vos Environnements et Tâches – <https://blog.stephane-robert.info/docs/developper/autres-outils/mise-en-place/>
* 2024-11-20 - Migrating from nvm to mise - <https://dev.to/hverlin/migrating-from-nvm-to-mise-4mfp>
* 2024-06-27 - Managing Development Tool Versions with mise - <https://haril.dev/en/blog/2024/06/27/Easy-devtools-version-management-mise>
* 2024-06-09 - Replacing pyenv, nvm, direnv with Mise - <https://arunmozhi.in/2024/09/06/replacing-pyenv-nvm-direnv-with-mise>
* 2024-04-14 - Shims: How they work in mise-en-place: <https://jdx.dev/posts/2024-04-13-shims-how-they-work-in-mise-en-place/>
* 2024-04-07 - Lalaluka stream: Grroxy, Cook, and jdx/mise - <https://www.youtube.com/watch?v=zA1hjrLQiPw>
* 2024-20-02 - Can Mise replace Volta? - <https://ricostacruz.com/posts/mise-vs-volta>
* 2024-01-14 - Manage all your runtime versions with one tool (asdf, mise) - <https://blog.andreyfadeev.com/p/manage-all-your-runtime-versions>
* 2023-12-30 - You should be using mise - <https://andrei-calazans.com/posts/you-should-be-using-rtx/>
* 2023-03-04 - Beginner's Guide to rtx (mise) - <https://dev.to/jdxcode/beginners-guide-to-rtx-ac4>

---

---
url: /faq.md
---
# FAQs

## I don't want to put a `mise.toml`/`.tool-versions` file into my project since git shows it as an untracked file

Use [`mise.local.toml`](https://mise.jdx.dev/configuration.html#mise-toml) and put that into your global gitignore file. This file should never be committed.

If you really want to use a `mise.toml` or `.tool-versions`, here are 3 ways to make git ignore these files:

* Adding `mise.toml` to project's `.git/info/exclude`. This file is local to your project so
  there is no need to commit it.
* Adding `mise.toml` to project's `.gitignore` file. This has the downside that you need to
  commit the change to the ignore file.
* Adding `mise.toml` to global gitignore (`core.excludesFile`). This will cause git to
  ignore `mise.toml` files in all projects. You can explicitly add one to a project if needed
  with `git add --force mise.toml`.

## What is the difference between "nodejs" and "node" (or "golang" and "go")?

These are aliased. For example, `mise use nodejs@14.0` is the same as `mise install node@14.0`. This
means it is not possible to have these be different plugins.

This is for convenience so you don't need to remember which one is the "official" name. However if
something with the aliasing is acting up, submit a ticket or just stick to using "node" and "go".
Under the hood, when mise reads a config file or takes CLI input it will swap out "nodejs" and
"golang".

## What does `mise activate` do?

It registers a shell hook to run `mise hook-env` every time the shell prompt is displayed.
`mise hook-env` checks the current env vars (most importantly `PATH` but there are others like
`GOROOT` or `JAVA_HOME` for some tools) and adds/removes/updates the ones that have changed.

For example, if you `cd` into a different directory that has `java 18` instead of `java 17`
specified, just before the next prompt is displayed the shell runs: `eval "$(mise hook-env)"`
which will execute something like this in the current shell session:

```sh
export JAVA_HOME=$HOME/.local/share/installs/java/18
export PATH=$HOME/.local/share/installs/java/18/bin:$PATH
```

In reality updating `PATH` is a bit more complex than that because it also needs to remove java-17,
but you get the idea.

You may think that is excessive to run `mise hook-env` every time the prompt is displayed
and it should only run on `cd`, however there are plenty of
situations where it needs to run without the directory changing, for example if `.tool-versions` or
`mise.toml` was just edited in the current shell.

Because it runs on prompt display, if you attempt to use `mise activate` in a
non-interactive session (like a bash script), it will never call `mise hook-env` and in effect will
never modify PATH because it never displays a prompt. For this type of setup, you can either call
`mise hook-env` manually every time you wish to update PATH, or use [shims](/dev-tools/shims.md)
instead (preferred).
Or if you only need to use mise for certain commands, just prefix the commands with
[`mise x --`](./cli/exec).
For example, `mise x -- npm test` or `mise x -- ./my_script.sh`.

`mise hook-env` will exit early in different situations if no changes have been made. This prevents
adding latency to your shell prompt every time you run a command. You can run `mise hook-env`
yourself
to see what it outputs, however it is likely nothing if you're in a shell that has already been
activated.

`mise activate` also creates a shell function (in most shells) called `mise`.
This is a trick that makes it possible for `mise shell`
and `mise deactivate` to work without wrapping them in `eval "$(mise shell)"`.

## Windows support?

::: warning
While mise runs great in WSL, native Windows is also supported, though via the use of shims until
someone adds [powershell](https://github.com/jdx/mise/discussions/6733) support.

As you'll need to use shims, this means you won't have environment variables from mise.toml unless you run mise via
[`mise x`](/cli/exec) or [`mise run`](/cli/run)—though that's actually how I use mise on my mac so
for me that's my preferred workflow anyway.
:::

## How do I use mise with http proxies?

Short answer: just set `http_proxy` and `https_proxy` environment variables. These should be
lowercase.

This may not work with all plugins if they are not configured to use these env vars.
If you're having a proxy-related issue installing something specific you should post an issue on the
plugin's repository.

## How do the shorthand plugin names map to repositories?

e.g.: how does `mise plugin install elixir` know to fetch <https://github.com/asdf-vm/asdf-elixir>?

We maintain [an index](https://github.com/mise-plugins/registry) of shorthands that mise uses as a
base.
This is regularly updated every time that mise has a release. This repository is stored directly
into
the codebase in [registry/](https://github.com/jdx/mise/blob/main/registry/).

## Does "node@20" mean the newest available version of node?

It depends on the command. Normally, for most commands and inside of config files, "node@20" will
point to the latest *installed* version of node-20.x. You can find this version by running
`mise latest --installed node@20` or by seeing what the `~/.local/share/mise/installs/node/20`
symlink
points to:

```sh
$ ls -l ~/.local/share/mise/installs/node/20
[...] /home/jdx/.local/share/mise/installs/node/20 -> node-v20.0.0-linux-x64
```

There are some exceptions to this, such as the following:

* `mise install node@20`
* `mise latest node@20`
* `mise upgrade node@20`

These will use the latest *available* version of node-20.x. This generally makes sense because you
wouldn't want to install a version that is already installed.

## How do I migrate from asdf?

* Install mise and set up `mise activate` as described in the [getting started guide](/getting-started)
* remove asdf from your shell rc file
* Run `mise install` in a directory with an asdf `.tool-versions` file and mise will install the tools

::: info
Note that `mise` does not consider `~/.tool-versions` files to be a global config file like `asdf` does. `mise` uses a
`~/.config/mise/config.toml` file for global configuration.
:::

Here is an example script you can use to migrate your global `.tool-versions` file to mise:

```shell
mv ~/.tool-versions ~/.tool-versions.bak
cat ~/.tool-versions.bak | tr -s ' ' | tr ' ' '@' | xargs -n2 mise use -g
```

Once you are comfortable with mise, you can remove the `.tool-versions.bak` file and [uninstall `asdf`](https://asdf-vm.com/manage/core.html#uninstall)

## How compatible is mise with asdf?

mise should be able to read/install any `.tool-versions` file used by asdf. Any asdf plugin
should be usable in mise. The commands in mise are slightly
different, such as `mise install node@20.0.0` vs `asdf install node 20.0.0`—this is done so
multiple tools can be specified at once. However, asdf-style syntax is still supported: (`mise
install node 20.0.0`). This is the case for most commands, though the help for the command may
say that asdf-style syntax is supported. When in doubt, just try asdf syntax and see if it works—it probably does.

::: info
UPDATE (2025-01-01): mise was designed to be compatible with the asdf written in bash (<=0.15). The new asdf written in go (>=0.16)
has commands mise does not support like `asdf set`. `mise set` is an existing command that is completely different than `asdf set`—in mise that sets env vars.

This isn't important for usability reasons so much as making it so plugins continue to work that
call asdf commands inside of the plugin code.
:::

Using commands like `mise use` may output `.tool-versions` files that are not compatible with asdf,
such as using fuzzy versions. You can set `--pin` or `MISE_PIN=1` to make `mise use` output asdf-compatible versions
in `.tool-versions`. Alternatively, you can have `mise.toml` and `.tool-versions` sitting side-by-side. `mise.toml` tools
will override tools defined in a `.tool-versions` in the same directory.

That said, in general compatibility with asdf is no longer a design goal. It's long been the case
that there is no reason to prefer asdf to mise so users should migrate. While plenty of users have
teams which use both in tandem, issues with such a setup are unlikely to be prioritized.

## How do I disable/force CLI color output?

mise uses [console.rs](https://docs.rs/console/latest/console/fn.colors_enabled.html) which
honors the [clicolors spec](https://bixense.com/clicolors/):

* `CLICOLOR != 0`: ANSI colors are supported and should be used when the program isn't piped.
* `CLICOLOR == 0`: Don't output ANSI color escape codes.
* `CLICOLOR_FORCE != 0`: ANSI colors should be enabled no matter what.

## Is mise secure?

Providing a secure supply chain is incredibly important. mise already provides a more secure
experience when compared to asdf. Security-oriented evaluations and contributions are welcome.
We also urge users to look after the plugins they use, and urge plugin authors to look after
the users they serve.

For more details see [SECURITY.md](https://github.com/jdx/mise/blob/main/SECURITY.md).

## What is usage?

usage (<https://usage.jdx.dev/>) is a spec and CLI for defining CLI tools.

Arguments, flags, environment variables, and config files can all be defined in a Usage spec. It can be thought of like OpenAPI (swagger) for CLIs.

`usage` can be installed with `mise` using `mise use -g usage` and is required to get the autocompletion working. See [autocompletion](/installing-mise.html#autocompletion).

You can leverage usage in file tasks to get auto-completion working, see [file tasks arguments](/tasks/file-tasks.html#arguments).

## What is pitchfork?

pitchfork (<https://pitchfork.jdx.dev/>) is a process manager for developers.

It handles daemon management with features like automatic restarts on failure, smart readiness checks, shell-based auto-start/stop when entering project directories, and cron-style scheduling for periodic tasks.

## VSCode for windows extension with error `spawn EINVAL`

In VSCode, many extensions will throw an "error spawn EINVAL" due to a [Node.js security fix](https://nodejs.org/en/blog/vulnerability/april-2024-security-releases-2#command-injection-via-args-parameter-of-child_processspawn-without-shell-option-enabled-on-windows-cve-2024-27980---high).

The default `exe` shim mode should resolve this. If you're using an older mode, you can change [windows\_shim\_mode](https://mise.jdx.dev/configuration/settings.html#windows_shim_mode) to `exe`, `hardlink`, or `symlink`.

## How does mise versioning work?

mise uses [Calver](https://calver.org/) versioning (`2024.1.0`).
Breaking changes will be few but when they do happen,
they will be communicated in the CLI with plenty of notice whenever possible.

Rather than have SemVer major releases to communicate change in large releases,
new functionality and changes can be opted-into with settings like `experimental = true`.
This way plugin authors and users can
test out new functionality immediately without waiting for a major release.

The numbers in Calver (YYYY.MM.RELEASE) simply represent the date of the release—not compatibility
or how many new features were added.
Each release will be small and incremental.

---

---
url: /tasks/file-tasks.md
---
# File Tasks

In addition to defining tasks through the configuration, they can also be defined as standalone script files in one of the following directories:

* `mise-tasks/:task_name`
* `.mise-tasks/:task_name`
* `mise/tasks/:task_name`
* `.mise/tasks/:task_name`
* `.config/mise/tasks/:task_name`

Note that you can configure directories using the [task\_config](/tasks/task-configuration.html#task-config-options) section.

Here is an example of a file task that builds a Rust CLI:

```bash [mise-tasks/build]
#!/usr/bin/env bash
#MISE description="Build the CLI"
cargo build
```

::: tip Important
Ensure that the file is executable, otherwise mise will not be able to detect it.

```shell
chmod +x mise-tasks/build
```

:::

Having the code in a bash file and not TOML helps make it work
better in editors since they can do syntax highlighting and linting more easily.

They also still work great for non-mise users—though
of course they'll need to find a different way to install their dev tools the tasks might use.

## Task Configuration

All configuration options can be found here [task configuration](/tasks/task-configuration)
You can provide additional configuration for file tasks by adding `#MISE` comments at the top of the file.

```bash
#MISE description="Build the CLI"
#MISE alias="b"
#MISE sources=["Cargo.toml", "src/**/*.rs"]
#MISE outputs=["target/debug/mycli"]
#MISE env={RUST_BACKTRACE = "1"}
#MISE depends=["lint", "test"]
#MISE tools={rust="1.50.0"}
```

Assuming that file was located in `mise-tasks/build`, it can then be run with `mise run build` (or with its alias: `mise run b`).

:::tip
Beware of formatters changing `#MISE` to `# MISE`.
It's intentionally ignored by mise to avoid unintentional configuration.
To workaround this, use the alternative: `# [MISE]`.
:::

## Shebang

The shebang line is optional, but if it is present, it will be used to determine the shell to run the script with.
You can also use it to run the script with various programming languages.

::: code-group

```js [node]
#!/usr/bin/env node
//MISE description="Hello, World in Node.js"

console.log("Hello, World!");
```

```python
#!/usr/bin/env python
#MISE description="Hello, World in Python"

print('Hello, World!')
```

```ts [deno]
#!/usr/bin/env -S deno run --allow-env
//MISE description="Hello, World in Deno"

console.log(`PATH, ${Deno.env.get("PATH")}`);
```

```powershell [powershell]
#!/usr/bin/env pwsh
#MISE description="Hello, World in PowerShell"

$current_directory = Get-Location
Write-Host "Hello from PowerShell, current directory is $current_directory"
```

:::

## Editing tasks

This script can be edited by running `mise tasks edit build` (using `$EDITOR`). If it doesn't exist it will be created.
This is convenient for quickly editing or creating new scripts.

## Task Grouping

File tasks in `mise-tasks`, `.mise/tasks`, `mise/tasks`, or `.config/mise/tasks` can be grouped into
sub-directories which will automatically apply prefixes to their names
when loaded.

**Example**: With a folder structure like below:

```text
mise-tasks
├── build
└── test
    ├── _default
    ├── integration
    └── units
```

Running `mise tasks` will give the below output:

```shellsession
$ mise tasks
Name              Description Source
build                         ./mise-tasks/build
test                          ./mise-tasks/test/_default
test:integration              ./mise-tasks/test/integration
test:units                    ./mise-tasks/test/units
```

## Arguments

::: tip
For comprehensive information about task arguments, see the dedicated [Task Arguments](/tasks/task-arguments) page.
:::

[usage](https://usage.jdx.dev) spec can be used within these files to provide argument parsing, autocompletion,
documentation when running mise and can be exported to markdown. Essentially this turns tasks into
fully-fledged CLIs.

:::tip
The `usage` CLI is not required to execute mise tasks with the usage spec.
However, for completions to work, the `usage` CLI must be installed and available in the PATH.
:::

### Example file task with arguments

Here is an example of a file task that builds a Rust CLI using some of the features of usage:

```bash [mise-tasks/build]
#!/usr/bin/env bash
set -e

#USAGE flag "-c --clean" help="Clean the build directory before building"
#USAGE flag "-p --profile <profile>" help="Build with the specified profile" default="debug" {
#USAGE   choices "debug" "release"
#USAGE }
#USAGE flag "-u --user <user>" help="The user to build for"
#USAGE complete "user" run="mycli users"
#USAGE arg "<target>" help="The target to build"

if [ "${usage_clean:-false}" = "true" ]; then
  cargo clean
fi

cargo build --profile "${usage_profile?}" --target "${usage_target?}"
```

::: tip
For details on bash parameter expansion patterns like `${var?}`, `${var:-default}`, and `${var:+value}`, see [Bash Variable Expansion for Usage Variables](/tasks/task-arguments#bash-variable-expansion).
:::

If you have installed `usage`, completions will be enabled for your task. In this example,

* `mise run -- build --profile <tab><tab>`
  will show `debug` and `release` as options.
* The `--user` flag will also show completions generated by the output of `mycli users`.
* Note: Use `--` to separate mise flags from task arguments: `mise run -- build --profile release <target>`

(Note that cli and markdown help for tasks is not yet implemented in mise as of this writing but that is planned.)

:::tip
If you don't get any autocomplete suggestions, use the `-v` (verbose) flag to see what's going on.
For example, if you use `mise run build -v` and have an invalid `usage` spec, you will see an error message such as `DEBUG failed to parse task file with usage`
:::

### Example of a NodeJS file task with arguments

Here is how you can use [usage](https://usage.jdx.dev/cli/scripts#usage-scripts) to parse arguments in a Node.js script:

```js [mise-tasks/greet]
#!/usr/bin/env -S node
//MISE description="Write a greeting to a file"
//USAGE flag "-f --force" help="Overwrite existing <file>"
//USAGE flag "-u --user <user>" help="User to run as"
//USAGE arg "<output_file>" help="The file to write" default="file.txt" {
//USAGE   choices "greeting.txt" "file.txt"
//USAGE }

const fs = require("fs");

const { usage_user, usage_force, usage_output_file } = process.env;

if (usage_force === "true") {
  fs.rmSync(usage_output_file, { force: true });
}

const user = usage_user ?? "world";
fs.appendFileSync(usage_output_file, `Hello, ${user}\n`);
console.log(`Greeting written to ${usage_output_file}`);
```

Run it with:

```shell
mise run greet greeting.txt --user Alice
# Greeting written to greeting.txt
```

If you pass an invalid argument, you will get an error message:

```shell
mise run greet invalid.txt --user Alice
# [greet] ERROR
#   0: Invalid choice for arg output_file: invalid.txt, expected one of greeting.txt, file.txt
```

Autocomplete will show the available choices for the `output_file` argument if `usage` is installed.

```shell
mise run greet <TAB>
# > greeting.txt
#   file.txt
```

## CWD

mise sets the current working directory to the directory of `mise.toml` before running tasks.
This can be overridden by setting `dir="{{cwd}}"` in the task header:

```bash
#!/usr/bin/env bash
#MISE dir="{{cwd}}"
```

Also, the original working directory is available in the `MISE_ORIGINAL_CWD` environment variable:

```bash
#!/usr/bin/env bash
cd "$MISE_ORIGINAL_CWD"
```

## Running tasks directly

Tasks don't need to be configured as part of a config, you can just run them directly by passing the path to the script:

```bash
mise run ./path/to/script.sh
```

Note that the path must start with `/` or `./` to be considered a file path. (On Windows it can be `C:\` or `.\`)

---

---
url: /dev-tools/backends/forgejo.md
---
# Forgejo Backend

You may install Codeberg and other Forgejo compatible release assets directly using the `forgejo` backend. This backend downloads release assets from Forgejo repositories and is ideal for tools that distribute pre-built binaries through Forgejo releases.

By default, the Forgejo backend uses the public Codeberg instance at <https://codeberg.org>. For other or self-hosted Forgejo instances, you can specify a custom API URL using the `api_url` tool option.

The code for this is inside of the mise repository at [`./src/backend/forgejo.rs`](https://github.com/jdx/mise/blob/main/src/backend/forgejo.rs).

## Usage

The following installs the latest version of a tool from Forgejo releases
and sets it as the active version on PATH:

```sh
$ mise use -g forgejo:forgejo/runner[api_url=https://code.forgejo.org/api/v1,bin=forgejo-runner,bin=forgejo-runner]
$ forgejo-runner -v
forgejo-runner version v12.4.0
```

The version will be set in `~/.config/mise/config.toml` with the following format:

```toml
[tools]
"forgejo:forgejo/runner" = {
  version = "latest",
  api_url = "https://code.forgejo.org/api/v1",
  bin = "forgejo-runner",
}
```

## Tool Options

The following [tool-options](/dev-tools/#tool-options) are available for the `forgejo` backend—these
go in `[tools]` in `mise.toml`.

### Asset Autodetection

When no `asset_pattern` is specified, mise automatically selects the best asset for your platform. The system scores assets based on:

* **OS compatibility** (linux, macos, windows)
* **Architecture compatibility** (x64, arm64, x86, arm)
* **Libc variant** (gnu or musl for Linux, msvc for Windows)
* **Archive format preference** (tar.gz, zip, etc.)
* **Build type** (avoids debug/test builds)

For most tools, you can simply install without specifying patterns:

```sh
mise install forgejo:user/repo
```

::: tip
The autodetection logic is implemented in [`src/backend/asset_detector.rs`](https://github.com/jdx/mise/blob/main/src/backend/asset_detector.rs), which is shared by the Forgejo, GitHub and GitLab backends.
:::

### `asset_pattern`

Specifies the pattern to match against release asset names. This is useful when there are multiple assets for your OS/arch combination or when you need to override autodetection.

```toml
[tools]
"forgejo:user/repo" = { version = "latest", asset_pattern = "tool_*_linux_x64.tar.gz" }
```

### `version_prefix`

Specifies a custom version prefix for release tags. By default, mise handles the common `v` prefix (e.g., `v1.0.0`), but some repositories use different prefixes like `release-`, `version-`, or no prefix at all.

When `version_prefix` is configured, mise will:

* Filter available versions with the prefix and strip it
* Add the prefix when searching for releases
* Try both prefixed and non-prefixed versions during installation

```toml
[tools]
"forgejo:user/repo" = { version = "latest", version_prefix = "release-" }
```

**Examples:**

* With `version_prefix = "release-"`:
  * User specifies `1.0.0` → mise searches for `release-1.0.0` tag
  * Available versions show as `1.0.0` (prefix stripped)
* With `version_prefix = ""` (empty string):
  * User specifies `1.0.0` → mise searches for `1.0.0` tag (no prefix)
  * Useful for repositories that don't use any prefix

### Platform-specific Asset Patterns

For different asset patterns per platform:

```toml
[tools."forgejo:user/repo"]
version = "latest"

[tools."forgejo:user/repo".platforms]
linux-x64 = { asset_pattern = "tool_*_linux_x64.tar.gz" }
macos-arm64 = { asset_pattern = "tool_*_macOS_arm64.tar.gz" }
```

### `checksum`

Verify the downloaded file with a checksum:

```toml
[tools."forgejo:owner/repo"]
version = "1.0.0"
asset_pattern = "tool-1.0.0-x64.tar.gz"
checksum = "sha256:a1b2c3d4e5f6789..."
```

*Instead of specifying the checksum here, you can use [mise.lock](/dev-tools/mise-lock) to manage checksums.*

### Platform-specific Checksums

```toml
[tools."forgejo:user/repo"]
version = "latest"

[tools."forgejo:user/repo".platforms]
linux-x64 = {
  asset_pattern = "tool_*_linux_x64.tar.gz",
  checksum = "sha256:a1b2c3d4e5f6789...",
}
macos-arm64 = {
  asset_pattern = "tool_*_macOS_arm64.tar.gz",
  checksum = "sha256:b2c3d4e5f6789...",
}
```

### `size`

Verify the downloaded asset size:

```toml
[tools]
"forgejo:user/repo" = { version = "latest", size = "12345678" }
```

### `strip_components`

Number of directory components to strip when extracting archives:

```toml
[tools]
"forgejo:user/repo" = { version = "latest", strip_components = 1 }
```

::: info
If `strip_components` is not explicitly set, mise will automatically detect when to apply `strip_components = 1`. This happens when the extracted archive contains exactly one directory at the root level and no files. This is common with tools like ripgrep that package their binaries in a versioned directory (e.g., `mytool-14.1.0-x86_64-unknown-linux-musl/mytool`). The auto-detection ensures the binary is placed directly in the install path where mise expects it.
:::

### `bin`

Rename the downloaded binary to a specific name. This is useful when downloading single binaries that have platform-specific names:

```toml
[tools."forgejo:user/repo"]
version = "2.29.1"
bin = "my-tool"  # Rename the downloaded binary to my-tool
```

::: info
When downloading single binaries (not archives), mise automatically removes OS/arch suffixes from the filename. For example, `docker-compose-linux-x86_64` becomes `docker-compose` automatically. Use the `bin` option only when you need a specific custom name.
:::

### `rename_exe`

Rename the executable after extraction from an archive. This is useful when the archive contains a binary with a platform-specific name that you want to rename:

```toml
[tools."forgejo:user/repo"]
version = "latest"
asset_pattern = "tool_linux.zip"
rename_exe = "tool"  # Rename the extracted binary to tool
```

::: tip
Use `rename_exe` for archives where the binary inside has a different name than desired. Use `bin` for single binary downloads (non-archives).
:::

### `bin_path`

Specify the directory containing binaries within the extracted archive, or where to place the downloaded file. This supports Tera templating with variables like `{{ version }}`, `{{ os }}`, `{{ arch }}`, and arch aliases (`{{ darwin_os }}`, `{{ amd64_arch }}`, `{{ x86_64_arch }}`, `{{ gnu_arch }}`):

```toml
[tools."forgejo:user/repo"]
version = "latest"
bin_path = "tool-{{ version }}/bin" # expands to tool-1.0.0/bin
```

**Binary path lookup order:**

1. If `bin_path` is specified, use that directory
2. If `bin_path` is not set, look for a `bin/` directory in the install path
3. If the install path root contains an executable file, use the install path root
4. If no `bin/` directory exists, search subdirectories for `bin/` directories
5. If no `bin/` directories are found, searches immediate subdirectories for any executable files. If an executable is found directly within a subdirectory, that entire subdirectory is considered a binary path.
6. If no executables are found, use the root of the extracted directory

### `filter_bins`

Comma-separated list of binaries to symlink into a filtered `.mise-bins` directory. This is useful when the tool comes with extra binaries that you do not want to expose on PATH.

```toml
[tools]
"forgejo:user/repo" = { version = "latest", filter_bins = "tool" }
```

When enabled:

* A `.mise-bins` subdirectory is created with symlinks only to the specified binaries
* Other binaries (like `tool-helper` or `tool-server`) are not exposed on PATH

### `api_url`

For other Forgejo compatible or self-hosted instances, specify the API URL:

```toml
[tools]
"forgejo:user/repo" = { version = "latest", api_url = "https://forgejo.mycompany.com/api/v1" }
```

## Self-hosted Forgejo

If you are using a self-hosted Forgejo instance, set the `api_url` tool option and optionally the `MISE_FORGEJO_ENTERPRISE_TOKEN` environment variable for authentication:

```sh
export MISE_FORGEJO_ENTERPRISE_TOKEN="your-token"
```

## Supported Forgejo Syntax

* **Forgejo shorthand for latest release version:** `forgejo:user/repo`
* **Forgejo shorthand for specific release version:** `forgejo:user/repo@2.40.1`

## Settings

---

---
url: /dev-tools/backends/gem.md
---
# gem Backend

mise can be used to install CLIs from RubyGems. The code for this is inside of the mise repository at [`./src/backend/gem.rs`](https://github.com/jdx/mise/blob/main/src/backend/gem.rs).

## Dependencies

This relies on having `gem` (provided with ruby) installed. You can install it with or without mise.
Here is how to install `ruby` with mise:

```sh
mise use -g ruby
```

## Usage

The following installs the latest version of [rubocop](https://rubygems.org/gems/rubocop) and sets it as the active version on PATH:

```sh
mise use -g gem:rubocop
rubocop --version
```

The version will be set in `~/.config/mise/config.toml` with the following format:

```toml
[tools]
"gem:rubocop" = "latest"
```

## Ruby upgrades

If the ruby version used by a gem package changes, (by mise or system ruby), you may need to
reinstall the gem. This can be done with:

```sh
mise install -f gem:rubocop
```

Or you can reinstall all gems with:

```sh
mise install -f "gem:*"
```

## Settings

Set these with `mise settings set [VARIABLE] [VALUE]` or by setting the environment variable listed.

---

---
url: /getting-started.md
---
# Getting Started

This will show you how to install mise and get started with it. This is a suitable way when using an interactive shell like `bash`, `zsh`, or `fish`.

## 1. Install `mise` CLI {#installing-mise-cli}

See [installing mise](/installing-mise) for other ways to install mise (`macport`, `apt`, `yum`, `nix`, etc.).

:::tabs key:installing-mise
\== Linux/macOS

```shell
curl https://mise.run | sh
```

By default, mise will be installed to `~/.local/bin` (this is simply a suggestion. `mise` can be installed anywhere).
You can verify the installation by running:

```shell
~/.local/bin/mise --version
# mise 2024.x.x
```

* `~/.local/bin` does not need to be in `PATH`. mise will automatically add its own directory to `PATH`
  when [activated](#activate-mise).

\== Brew

```shell
brew install mise
```

\== Windows
::: code-group

```shell [winget]
winget install jdx.mise
```

```shell [scoop]
# https://github.com/ScoopInstaller/Main/pull/6374
scoop install mise
```

```shell [chocolatey]
choco install mise
```

\== Debian/Ubuntu (apt)

```sh
sudo apt update -y && sudo apt install -y curl
sudo install -dm 755 /etc/apt/keyrings
curl -fSs https://mise.jdx.dev/gpg-key.pub | sudo tee /etc/apt/keyrings/mise-archive-keyring.asc 1> /dev/null
echo "deb [signed-by=/etc/apt/keyrings/mise-archive-keyring.asc] https://mise.jdx.dev/deb stable main" | sudo tee /etc/apt/sources.list.d/mise.list
sudo apt update -y
sudo apt install -y mise
```

\== Fedora 41+, RHEL/CentOS Stream 9+ (dnf)

```sh
sudo dnf copr enable jdxcode/mise
sudo dnf install mise
```

See the [copr page](https://copr.fedorainfracloud.org/coprs/jdxcode/mise/) for more information.

\== Snap (beta)

```sh
sudo snap install mise --classic --beta
```

See the [snapcraft.io page](https://snapcraft.io/mise) for more information.

:::

`mise` respects [`MISE_DATA_DIR`](/configuration) and [`XDG_DATA_HOME`](/configuration) if you'd like
to change these locations.

## 2. mise `exec` and `run` {#mise-exec-run}

Once `mise` is installed, you can immediately start using it. `mise` can be used to install and run [tools](/dev-tools/), launch [tasks](/tasks/), and manage [environment variables](/environments/).

The most essential feature `mise` provides is the ability to run [tools](/dev-tools/) with specific versions. A simple way to run a shell command with a given tool is to use [`mise x|exec`](/cli/exec.html). For example, here is how you can start a Python 3 interactive shell (REPL):

> *In the examples below, use `~/.local/bin/mise` (or the absolute path to `mise`) if `mise` is not already on `PATH`*

```sh
mise exec python@3 -- python
# this will download and install Python if it is not already installed
# Python 3.13.2
# >>> ...
```

or run node 24:

```sh
mise exec node@24 -- node -v
# v24.x.x
```

[`mise x|exec`](/cli/exec.html) is a powerful way to load the current `mise` context (tools & environment variables) without modifying your shell session or running ad-hoc commands with mise tools set. Installing [`tools`](/dev-tools/) is as simple as running [`mise u|use`](/cli/use.html).

```shell
mise use --global node@24 # install node 24 and set it as the global default
mise exec -- node my-script.js
# run my-script.js with node 24...
```

Another useful command is [`mise r|run`](/cli/run.html) which allows you to run a [`mise task`](/tasks/) or a script with the `mise` context.

::: tip
You can set a shell alias in your shell's rc file like `alias x="mise x --"` to save some keystrokes.
:::

## 3. Activate `mise`  {#activate-mise}

While using [`mise x|exec`](/cli/exec.html) is useful, for interactive shells, you might prefer to activate `mise` to automatically load the `mise` context (`tools` and `environment variables`) in your shell session. Another option is to use [shims](dev-tools/shims.md).

* [`mise activate`](/cli/activate) method updates your environment variable and `PATH` every time your prompt is run to ensure you use the correct versions.
* [Shims](dev-tools/shims.md) are symlinks to the `mise` binary that intercept commands and load the appropriate environment. Note that [**shims do not support all the features of `mise activate`**](/dev-tools/shims.html#shims-vs-path).

For interactive shells, `mise activate` is recommended. In non-interactive sessions, like CI/CD, IDEs, and scripts, using `shims` might work best. You can also not use any and call `mise exec/run` directly instead.
See [this guide](dev-tools/shims.md) for more information.

Here is how you can activate `mise` depending on your shell and the installation method:

:::tabs key:installing-mise

\== https://mise.run

::: code-group

```sh [bash]
echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc
```

```sh [zsh]
echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc
```

```sh [fish]
echo '~/.local/bin/mise activate fish | source' >> ~/.config/fish/config.fish
```

\== Brew

::: code-group

```sh [bash]
echo 'eval "$(mise activate bash)"' >> ~/.bashrc
```

```sh [zsh]
echo 'eval "$(mise activate zsh)"' >> ~/.zshrc
```

```sh [fish]
# do nothing! mise is automatically activated when using brew and fish
# you can disable this behavior with `set -Ux MISE_FISH_AUTO_ACTIVATE 0`
```

\== Windows

Add the following to your PowerShell profile (`$PROFILE`):

```powershell
(&mise activate pwsh) | Out-String | Invoke-Expression
```

In case you need to open your PowerShell profile:

```powershell
# create profile if it doesn't already exist
if (-not (Test-Path $profile)) { New-Item $profile -Force }
# open the profile
Invoke-Item $profile
```

* If not using PowerShell, add `<homedir>\AppData\Local\mise\shims` to `PATH`.

\== Other package managers

::: code-group

```sh [bash]
echo 'eval "$(mise activate bash)"' >> ~/.bashrc
```

```sh [zsh]
echo 'eval "$(mise activate zsh)"' >> ~/.zshrc
```

```sh [fish]
echo 'mise activate fish | source' >> ~/.config/fish/config.fish
```

:::

Make sure you restart your shell session after modifying your rc file in order for it to take effect.
You can run [`mise dr|doctor`](/cli/doctor.html) to verify that mise is correctly installed and activated.

Now that `mise` is activated or its shims have been added to `PATH`, `node` is also available directly! (without using `mise exec`):

```sh
mise use --global node@24
node -v
# v24.x.x
```

Note that when you ran `mise use --global node@24`, `mise` updated the global `mise` configuration.

```toml [~/.config/mise/config.toml]
[tools]
node = "24"
```

## 4. Use tools from backends (npm, pipx, core, aqua, github) {#tool-backends}

```mermaid
flowchart LR
  subgraph Backends
    core
    aqua
    github
    npm
    pipx
  end

  core --> node["core:node"]
  core --> python["core:python"]
  aqua -->gh["aqua:cli/cli"]
  github -->ripgrep["github:BurntSushi/ripgrep"]
  github -->ruff["github:astral-sh/ruff"]
  npm --> prettier["npm:prettier"]
  npm --> claude_code["npm:@anthropic-ai/claude-code"]
  pipx -->black["pipx:black"]
  pipx -->pycowsay["pipx:pycowsay"]
  aqua -->terraform["aqua:hashicorp/terraform"]

  subgraph Tools
    node
    python
    gh
    ripgrep
    ruff
    prettier
    claude_code
    black
    pycowsay
    terraform
  end
```

Backends are ecosystems or package managers that mise uses to install tools. With `mise use`, you can install multiple tools from each backend.

For example, to install [claude-code](https://www.npmjs.com/package/@anthropic-ai/claude-code) with the npm backend:

```sh
# run claude-code via mise x|exec
mise exec npm:@anthropic-ai/claude-code -- claude --version

# or if mise is activated in your shell
mise use --global npm:@anthropic-ai/claude-code
claude --version
```

Install [black](https://github.com/psf/black) with the pipx backend:

```sh
# run black via mise x|exec
mise exec pipx:black -- black --version

# or if mise is activated in your shell
mise use --global pipx:black
black --version
```

mise can also install tools directly from github with the github backend:

```sh
# run ripgrep via mise x|exec
mise exec github:BurntSushi/ripgrep -- rg --version

# or if mise is activated in your shell
mise use --global github:BurntSushi/ripgrep
rg --version
```

See [Backends](/dev-tools/backends/) for more ecosystems and details.

## 5. Setting environment variables {#environment-variables}

You can set environment variables in `mise.toml` which will be set if mise is activated or if `mise x|exec` is used in a directory:

```toml [mise.toml]
[env]
NODE_ENV = "production"
```

```sh
mise exec -- node --eval 'console.log(process.env.NODE_ENV)'

# or if mise is activated in your shell
echo "node env: $NODE_ENV"
# node env: production
```

## 6. Run a task {#run-a-task}

You can define simple tasks in `mise.toml` and run them with `mise run`:

```toml [mise.toml]
[tasks]
hello = "echo hello from mise"
```

Run it:

```sh
mise run hello
# hello from mise
```

:::tip
mise tasks will automatically install all of the tools from `mise.toml` before running the task.
:::

See [tasks](/tasks/) for more information on how to define and use tasks.

## 7. Next steps {#next-steps}

Follow the [walkthrough](/walkthrough) for more examples on how to use mise.

### Set up autocompletion {#autocompletion}

See [autocompletion](/installing-mise.html#autocompletion) to learn how to set up autocompletion for your shell.

### GitHub API rate limiting {#github-api-rate-limiting}

::: warning
Many tools in mise require the use of the GitHub API. Unauthenticated requests to the GitHub API are
often rate limited. If you see 4xx errors while using mise, you can set `MISE_GITHUB_TOKEN` or `GITHUB_TOKEN`
to a token [generated from here](https://github.com/settings/tokens/new?description=MISE_GITHUB_TOKEN) which
will likely fix the issue. The token does not require any scopes.
:::

---

---
url: /dev-tools/backends/github.md
---
# GitHub Backend

You may install GitHub release assets directly using the `github` backend. This backend downloads release assets from GitHub repositories and is ideal for tools that distribute pre-built binaries through GitHub releases.

The code for this is inside of the mise repository at [`./src/backend/github.rs`](https://github.com/jdx/mise/blob/main/src/backend/github.rs).

## Usage

The following installs the latest version of ripgrep from GitHub releases
and sets it as the active version on PATH:

```sh
$ mise use -g github:BurntSushi/ripgrep
$ rg --version
ripgrep 14.1.1
```

The version will be set in `~/.config/mise/config.toml` with the following format:

```toml
[tools]
"github:BurntSushi/ripgrep" = "latest"
```

## Tool Options

The following [tool-options](/dev-tools/#tool-options) are available for the `github` backend—these
go in `[tools]` in `mise.toml`.

### Asset Autodetection

When no `asset_pattern` is specified, mise automatically selects the best asset for your platform. The system scores assets based on:

* **OS compatibility** (linux, macos, windows)
* **Architecture compatibility** (x64, arm64, x86, arm)
* **Libc variant** (gnu or musl for Linux, msvc for Windows)
* **Archive format preference** (tar.gz, zip, etc.)
* **Build type** (avoids debug/test builds)

For most tools, you can simply install without specifying patterns:

```sh
mise install github:user/repo
```

::: tip
The autodetection logic is implemented in [`src/backend/asset_matcher.rs`](https://github.com/jdx/mise/blob/main/src/backend/asset_matcher.rs), which is shared by both the GitHub and GitLab backends.
:::

### `asset_pattern`

Specifies the pattern to match against release asset names. This is useful when there are multiple assets for your OS/arch combination or when you need to override autodetection.

```toml
[tools]
"github:cli/cli" = { version = "latest", asset_pattern = "gh_*_linux_x64.tar.gz" }
```

### `version_prefix`

Specifies a custom version prefix for release tags. By default, mise handles the common `v` prefix (e.g., `v1.0.0`), but some repositories use different prefixes like `release-`, `version-`, or no prefix at all.

When `version_prefix` is configured, mise will:

* Filter available versions with the prefix and strip it
* Add the prefix when searching for releases
* Try both prefixed and non-prefixed versions during installation

```toml
[tools]
"github:user/repo" = { version = "latest", version_prefix = "release-" }
```

**Examples:**

* With `version_prefix = "release-"`:
  * User specifies `1.0.0` → mise searches for `release-1.0.0` tag
  * Available versions show as `1.0.0` (prefix stripped)
* With `version_prefix = ""` (empty string):
  * User specifies `1.0.0` → mise searches for `1.0.0` tag (no prefix)
  * Useful for repositories that don't use any prefix

### Platform-specific Asset Patterns

For different asset patterns per platform:

```toml
[tools."github:cli/cli"]
version = "latest"

[tools."github:cli/cli".platforms]
linux-x64 = { asset_pattern = "gh_*_linux_x64.tar.gz" }
macos-arm64 = { asset_pattern = "gh_*_macOS_arm64.tar.gz" }
```

### `checksum`

Verify the downloaded file with a checksum:

```toml
[tools."github:owner/repo"]
version = "1.0.0"
asset_pattern = "tool-1.0.0-x64.tar.gz"
checksum = "sha256:a1b2c3d4e5f6789..."
```

*Instead of specifying the checksum here, you can use [mise.lock](/dev-tools/mise-lock) to manage checksums.*

### Platform-specific Checksums

```toml
[tools."github:cli/cli"]
version = "latest"

[tools."github:cli/cli".platforms]
linux-x64 = {
  asset_pattern = "gh_*_linux_x64.tar.gz",
  checksum = "sha256:a1b2c3d4e5f6789...",
}
macos-arm64 = {
  asset_pattern = "gh_*_macOS_arm64.tar.gz",
  checksum = "sha256:b2c3d4e5f6789...",
}
```

### `size`

Verify the downloaded asset size:

```toml
[tools]
"github:cli/cli" = { version = "latest", size = "12345678" }
```

### `strip_components`

Number of directory components to strip when extracting archives:

```toml
[tools]
"github:cli/cli" = { version = "latest", strip_components = 1 }
```

::: info
If `strip_components` is not explicitly set, mise will automatically detect when to apply `strip_components = 1`. This happens when the extracted archive contains exactly one directory at the root level and no files. This is common with tools like ripgrep that package their binaries in a versioned directory (e.g., `ripgrep-14.1.0-x86_64-unknown-linux-musl/rg`). The auto-detection ensures the binary is placed directly in the install path where mise expects it.
:::

### `bin`

Rename the downloaded binary to a specific name. This is useful when downloading single binaries that have platform-specific names:

```toml
[tools."github:docker/compose"]
version = "2.29.1"
bin = "docker-compose"  # Rename the downloaded binary to docker-compose
```

::: info
When downloading single binaries (not archives), mise automatically removes OS/arch suffixes from the filename. For example, `docker-compose-linux-x86_64` becomes `docker-compose` automatically. Use the `bin` option only when you need a specific custom name.
:::

### `rename_exe`

Rename the executable after extraction from an archive. This is useful when the archive contains a binary with a platform-specific name that you want to rename:

```toml
[tools."github:yt-dlp/yt-dlp"]
version = "latest"
asset_pattern = "yt-dlp_linux.zip"
rename_exe = "yt-dlp"  # Rename the extracted binary to yt-dlp
```

::: tip
Use `rename_exe` for archives where the binary inside has a different name than desired. Use `bin` for single binary downloads (non-archives).
:::

### `no_app`

Skip macOS .app bundle assets during autodetection and prefer standalone CLI binaries instead. This is useful when a repository provides both a macOS .app bundle (often an Xcode extension or GUI application) and a standalone command-line tool:

```toml
[tools."github:nicklockwood/SwiftFormat"]
version = "latest"
rename_exe = "swiftformat"
no_app = true  # Skip SwiftFormat.for.Xcode.app.zip, use swiftformat.zip instead
```

When `no_app = true`:

* Assets containing `.app.` (e.g., `Tool.app.zip`, `Tool.for.Xcode.app.zip`) are penalized during autodetection
* Standalone archives (e.g., `tool.zip`, `tool-macos.tar.gz`) are preferred
* Only affects macOS; has no effect on Linux/Windows

::: info
Without this option, mise's autodetection might select .app bundles on macOS, which can be problematic if the bundle contains a GUI application or Xcode extension rather than a standalone CLI tool.
:::

### `bin_path`

Specify the directory containing binaries within the extracted archive, or where to place the downloaded file. This supports Tera templating with variables like `{{ version }}`, `{{ os }}`, `{{ arch }}`, and arch aliases (`{{ darwin_os }}`, `{{ amd64_arch }}`, `{{ x86_64_arch }}`, `{{ gnu_arch }}`):

```toml
[tools."github:cli/cli"]
version = "latest"
bin_path = "cli-{{ version }}/bin" # expands to cli-1.0.0/bin
```

**Binary path lookup order:**

1. If `bin_path` is specified, use that directory
2. If `bin_path` is not set, look for a `bin/` directory in the install path
3. If the install path root contains an executable file, use the install path root
4. If no `bin/` directory exists, search subdirectories for `bin/` directories
5. If no `bin/` directories are found, searches immediate subdirectories for any executable files. If an executable is found directly within a subdirectory, that entire subdirectory is considered a binary path.
6. If no executables are found, use the root of the extracted directory

### `filter_bins`

Comma-separated list of binaries to symlink into a filtered `.mise-bins` directory. This is useful when the tool comes with extra binaries that you do not want to expose on PATH.

```toml
[tools]
"github:jgm/pandoc" = { version = "latest", filter_bins = "pandoc" }
```

When enabled:

* A `.mise-bins` subdirectory is created with symlinks only to the specified binaries
* Other binaries (like `pandoc-lua` or `pandoc-server`) are not exposed on PATH

### `api_url`

For GitHub Enterprise or self-hosted GitHub instances, specify the API URL:

```toml
[tools]
"github:myorg/mytool" = { version = "latest", api_url = "https://github.mycompany.com/api/v3" }
```

## Self-hosted GitHub

If you are using a self-hosted GitHub instance, set the `api_url` tool option and optionally the `MISE_GITHUB_ENTERPRISE_TOKEN` environment variable for authentication:

```sh
export MISE_GITHUB_ENTERPRISE_TOKEN="your-token"
```

## Supported GitHub Syntax

* **GitHub shorthand for latest release version:** `github:cli/cli`
* **GitHub shorthand for specific release version:** `github:cli/cli@2.40.1`

## Settings

---

---
url: /dev-tools/backends/gitlab.md
---
# GitLab Backend

You may install GitLab release assets directly using the `gitlab` backend. This backend downloads release assets from GitLab repositories and is ideal for tools that distribute pre-built binaries through GitLab releases.

The code for this is inside of the mise repository at [`./src/backend/github.rs`](https://github.com/jdx/mise/blob/main/src/backend/github.rs).

## Usage

The following installs the latest version of gitlab-runner from GitLab releases
and sets it as the active version on PATH:

```sh
$ mise use -g gitlab:gitlab-org/gitlab-runner
$ gitlab-runner --version
gitlab-runner 16.8.0
```

The version will be set in `~/.config/mise/config.toml` with the following format:

```toml
[tools]
"gitlab:gitlab-org/gitlab-runner" = { version = "latest", asset_pattern = "gitlab-runner-linux-x64" }
```

## Tool Options

The following [tool-options](/dev-tools/#tool-options) are available for the `gitlab` backend—these
go in `[tools]` in `mise.toml`.

### Asset Autodetection

When no `asset_pattern` is specified, mise automatically selects the best asset for your platform. The system scores assets based on:

* **OS compatibility** (linux, macos, windows)
* **Architecture compatibility** (x64, arm64, x86, arm)
* **Libc variant** (gnu or musl for Linux, msvc for Windows)
* **Archive format preference** (tar.gz, zip, etc.)
* **Build type** (avoids debug/test builds)

For most tools, you can simply install without specifying patterns:

```sh
mise install gitlab:user/repo
```

::: tip
The autodetection logic is implemented in [`src/backend/asset_matcher.rs`](https://github.com/jdx/mise/blob/main/src/backend/asset_matcher.rs), which is shared by both the GitHub and GitLab backends.
:::

### `asset_pattern`

Specifies the pattern to match against release asset names. This is useful when there are multiple assets for your OS/arch combination or when you need to override autodetection.

```toml
[tools."gitlab:gitlab-org/gitlab-runner"]
version = "latest"
asset_pattern = "gitlab-runner-linux-x64"
```

### `version_prefix`

Specifies a custom version prefix for release tags. By default, mise handles the common `v` prefix (e.g., `v1.0.0`), but some repositories use different prefixes like `release-`, `version-`, or no prefix at all.

When `version_prefix` is configured, mise will:

* Filter available versions with the prefix and strip it
* Add the prefix when searching for releases
* Try both prefixed and non-prefixed versions during installation

```toml
[tools]
"gitlab:user/repo" = { version = "latest", version_prefix = "release-" }
```

**Examples:**

* With `version_prefix = "release-"`:
  * User specifies `1.0.0` → mise searches for `release-1.0.0` tag
  * Available versions show as `1.0.0` (prefix stripped)
* With `version_prefix = ""` (empty string):
  * User specifies `1.0.0` → mise searches for `1.0.0` tag (no prefix)
  * Useful for repositories that don't use any prefix

### Platform-specific Asset Patterns

For different asset patterns per platform:

```toml
[tools."gitlab:gitlab-org/gitlab-runner"]
version = "latest"

[tools."gitlab:gitlab-org/gitlab-runner".platforms]
linux-x64 = { asset_pattern = "gitlab-runner-linux-x64" }
macos-arm64 = { asset_pattern = "gitlab-runner-macos-arm64" }
```

### `checksum`

Verify the downloaded file with a checksum:

```toml
[tools."gitlab:owner/repo"]
version = "1.0.0"
asset_pattern = "tool-1.0.0-x64.tar.gz"
checksum = "sha256:a1b2c3d4e5f6789..."
```

*Instead of specifying the checksum here, you can use [mise.lock](/dev-tools/mise-lock) to manage checksums.*

### Platform-specific Checksums

```toml
[tools."gitlab:gitlab-org/gitlab-runner"]
version = "latest"

[tools."gitlab:gitlab-org/gitlab-runner".platforms]
linux-x64 = {
  asset_pattern = "gitlab-runner-linux-x64",
  checksum = "sha256:a1b2c3d4e5f6789...",
}
macos-arm64 = {
  asset_pattern = "gitlab-runner-macos-arm64",
  checksum = "sha256:b2c3d4e5f6789...",
}
```

### `size`

Verify the downloaded asset size:

```toml
[tools]
"gitlab:gitlab-org/gitlab-runner" = { version = "latest", size = "12345678" }
```

### Platform-specific Size

You can specify different sizes for different platforms:

```toml
[tools."gitlab:gitlab-org/gitlab-runner"]
version = "latest"

[tools."gitlab:gitlab-org/gitlab-runner".platforms]
linux-x64 = { size = "12345678" }
macos-arm64 = { size = "9876543" }
```

### `strip_components`

Number of directory components to strip when extracting archives:

```toml
[tools]
"gitlab:gitlab-org/gitlab-runner" = { version = "latest", strip_components = 1 }
```

::: info
If `strip_components` is not explicitly set, mise will automatically detect when to apply `strip_components = 1`. This happens when the extracted archive contains exactly one directory at the root level and no files. This is common with tools like ripgrep that package their binaries in a versioned directory (e.g., `ripgrep-14.1.0-x86_64-unknown-linux-musl/rg`). The auto-detection ensures the binary is placed directly in the install path where mise expects it.
:::

### `bin`

Rename the downloaded binary to a specific name. This is useful when downloading single binaries that have platform-specific names:

```toml
[tools."gitlab:myorg/mytool"]
version = "1.0.0"
asset_pattern = "mytool-linux-x86_64"
bin = "mytool"  # Rename from mytool-linux-x86_64 to mytool
```

::: info
When downloading single binaries (not archives), mise automatically removes OS/arch suffixes from the filename. For example, `mytool-linux-x86_64` becomes `mytool` automatically. Use the `bin` option only when you need a specific custom name.
:::

### `rename_exe`

Rename the executable after extraction from an archive. This is useful when the archive contains a binary with a platform-specific name that you want to rename:

```toml
[tools."gitlab:myorg/mytool"]
version = "latest"
asset_pattern = "mytool_linux.zip"
rename_exe = "mytool"  # Rename the extracted binary to mytool
```

::: tip
Use `rename_exe` for archives where the binary inside has a different name than desired. Use `bin` for single binary downloads (non-archives).
:::

### `bin_path`

Specify the directory containing binaries within the extracted archive, or where to place the downloaded file. This supports Tera templating with variables like `{{ version }}`, `{{ os }}`, `{{ arch }}`, and arch aliases (`{{ darwin_os }}`, `{{ amd64_arch }}`, `{{ x86_64_arch }}`, `{{ gnu_arch }}`):

```toml
[tools."gitlab:gitlab-org/gitlab-runner"]
version = "latest"
bin_path = "gitlab-runner-{{ version }}/bin" # expands to gitlab-runner-1.0.0/bin
```

**Binary path lookup order:**

1. If `bin_path` is specified, use that directory
2. If `bin_path` is not set, look for a `bin/` directory in the install path
3. If the install path root contains an executable file, use the install path root
4. If no `bin/` directory exists, search subdirectories for `bin/` directories
5. If no `bin/` directories are found, searches immediate subdirectories for any executable files. If an executable is found directly within a subdirectory, that entire subdirectory is considered a binary path.
6. If no executables are found, use the root of the extracted directory

### `filter_bins`

Comma-separated list of binaries to symlink into a filtered `.mise-bins` directory. This is useful when the tool comes with extra binaries that you do not want to expose on PATH.

```toml
[tools]
"gitlab:myorg/mytool" = { version = "1.0.0", filter_bins = "mybin" }
```

When enabled:

* A `.mise-bins` subdirectory is created with symlinks only to the specified binaries
* Other binaries are not exposed on PATH

### `api_url`

For self-hosted GitLab instances, specify the API URL:

```toml
[tools]
"gitlab:myorg/mytool" = { version = "latest", api_url = "https://gitlab.mycompany.com/api/v4" }
```

## Private GitLab repositories

If you want to install a tool from a private repository on `gitlab.com`, set the `MISE_GITLAB_TOKEN` environment variable for authentication:

```sh
export MISE_GITLAB_TOKEN="your-token"
```

## Self-hosted GitLab

If you are using a self-hosted GitLab instance, set the `api_url` tool option and optionally the `MISE_GITLAB_ENTERPRISE_TOKEN` environment variable for authentication:

```sh
export MISE_GITLAB_ENTERPRISE_TOKEN="your-token"
```

## Supported GitLab Syntax

* **GitLab shorthand for latest release version:** `gitlab:gitlab-org/gitlab-runner`
* **GitLab shorthand for specific release version:** `gitlab:gitlab-org/gitlab-runner@16.8.0`

## Settings

---

---
url: /glossary.md
---
# Glossary

This glossary defines key terms and concepts used throughout the mise documentation.

## Core Concepts

**Activation**
: The process of loading mise's context (tools, environment variables, PATH modifications) into your shell session. Typically done via `eval "$(mise activate bash)"` in your shell rc file. See [Installing mise](/installing-mise) for setup instructions.

**Backend**
: A package manager or ecosystem that mise uses to install and manage tools. Each backend knows how to fetch, install, and manage tools from its respective source. See [Backends](#backends) below and [Backend Architecture](/dev-tools/backend_architecture) for details.

**Core Tools**
: Built-in tool implementations written in Rust that ship with mise. These provide first-class support for popular languages like Node.js, Python, Ruby, Go, and others. See [Core tools](/core-tools) for the full list.

**mise.toml**
: The primary configuration file for mise projects. Contains tool versions, environment variables, tasks, and hooks. See [Configuration](/configuration) for the full specification.

**mise.local.toml**
: A user-local configuration file that overrides `mise.toml`. Typically added to `.gitignore` for personal settings that shouldn't be shared with the team.

**Plugin**
: An extension that adds functionality to mise, such as managing additional tools or setting up environment variables. See [Plugins](/plugins) for an overview.

**Registry**
: The collection of tool aliases that map user-friendly short names to their full backend specifications. For example, `aws-cli` maps to `aqua:aws/aws-cli`. See [Registry](/registry).

**Tool**
: A development tool or runtime that mise can install and manage, such as `node`, `python`, `terraform`, or `jq`.

**Tool Request**
: A user's specification for a tool version, which may be fuzzy or use aliases. Examples: `node@18`, `python@latest`, `go@1.21`. These get resolved to concrete Tool Versions.

**Tool Version**
: A concrete, resolved version of a tool. For example, `node@18` (tool request) might resolve to `node@18.19.0` (tool version).

**Toolset**
: An immutable collection of resolved tools for a specific context, containing all the Tool Versions that should be active for a directory or project.

## Backends

mise supports multiple backends for installing tools from different sources:

**aqua**
: Backend using the [aqua-proj](https://aquaproj.github.io/) registry. Supports SLSA provenance verification and provides access to thousands of tools. See [aqua backend](/dev-tools/backends/aqua).

**asdf**
: Legacy backend compatible with [asdf](https://asdf-vm.com/) shell-script plugins. Linux and macOS only. Slower than native backends but provides access to the asdf plugin ecosystem. See [asdf backend](/dev-tools/backends/asdf).

**cargo**
: Installs Rust tools by compiling them with `cargo install`. See [cargo backend](/dev-tools/backends/cargo).

**conda**
: Installs packages from Conda repositories. See [conda backend](/dev-tools/backends/conda).

**dotnet**
: Installs .NET tools. See [dotnet backend](/dev-tools/backends/dotnet).

**gem**
: Installs Ruby gems as tools. See [gem backend](/dev-tools/backends/gem).

**github**
: Installs tools directly from GitHub releases. See [github backend](/dev-tools/backends/github).

**gitlab**
: Installs tools directly from GitLab releases. See [gitlab backend](/dev-tools/backends/gitlab).

**go**
: Installs Go tools using `go install`. See [go backend](/dev-tools/backends/go).

**http**
: Installs tools from arbitrary HTTP/HTTPS URLs. See [http backend](/dev-tools/backends/http).

**npm**
: Installs Node.js packages and CLI tools from the npm registry. See [npm backend](/dev-tools/backends/npm).

**pipx**
: Installs Python CLI tools in isolated environments using pipx. See [pipx backend](/dev-tools/backends/pipx).

**spm**
: Installs tools via Swift Package Manager. See [spm backend](/dev-tools/backends/spm).

**ubi**
: Universal Binary Installer for tools distributed as single binaries. See [ubi backend](/dev-tools/backends/ubi).

**vfox**
: Backend compatible with [VersionFox](https://vfox.lhan.me/) plugins. See [vfox backend](/dev-tools/backends/vfox).

## Shell Integration

**hook-env**
: The `mise hook-env` command that exports environment changes for shell integration. Called automatically by the shell hook installed via `mise activate`.

**PATH Activation**
: The default method of shell integration where mise updates the `PATH` environment variable at each prompt to include the appropriate tool binaries.

**Reshim**
: The process of updating the shims directory after tools are installed or removed. Run `mise reshim` if shims get out of sync.

**Shims**
: Small executable scripts that intercept tool commands and delegate to mise, which loads the appropriate tool context before execution. An alternative to PATH activation. See [Shims](/dev-tools/shims).

## Configuration

**config\_root**
: The canonical project root directory that mise uses when resolving relative paths in configuration files. Set via the `MISE_PROJECT_ROOT` environment variable or detected automatically.

**Configuration Environments**
: Environment-specific configuration files like `mise.dev.toml` or `mise.prod.toml`, activated via the `MISE_ENV` environment variable. See [Configuration Environments](/configuration/environments).

**Configuration Hierarchy**
: The system where mise.toml files at different levels (system, global, project) are merged together, with files closer to the current directory taking precedence over parent directories.

**Settings**
: Global mise configuration options stored in `~/.config/mise/settings.toml` that define behavior across all projects. See [Settings](/configuration/settings).

**Templates**
: Dynamic values in configuration using Tera template syntax, like `{{env.HOME}}` or `{{arch()}}`. See [Templates](/templates).

## Environment Variables

**env.\_ directives**
: Special environment configuration directives for advanced setup:

* `env._.file` - Load variables from a file (e.g., `.env`)
* `env._.path` - Prepend directories to PATH
* `env._.source` - Source a shell script

**Lazy Evaluation**
: Environment variables configured with `tools = true` that can access tool-provided environment variables. These are evaluated after tools are loaded.

**Redaction**
: Marking sensitive environment variables with `redact = true` to hide their values from mise output and logs.

## Hooks

**Hooks**
: Scripts that automatically execute during mise activation at specific events. An experimental feature. See [Hooks](/hooks).

**cd hook**
: Runs whenever you change directories while mise is active.

**enter hook**
: Runs when entering a directory where a mise.toml becomes active.

**leave hook**
: Runs when leaving a directory where a mise.toml was active.

**postinstall hook**
: Runs after a tool is successfully installed.

**preinstall hook**
: Runs before a tool installation begins.

**watch\_files hook**
: Runs when specified files change. Requires `mise activate` for file watching.

## Tasks

**Dependency Graph**
: A Directed Acyclic Graph (DAG) used internally to resolve task execution order based on dependencies.

**File Tasks**
: Tasks defined as standalone executable scripts in directories like `mise-tasks/` or `.mise/tasks/`. See [File Tasks](/tasks/file-tasks).

**Task**
: A reusable command defined in mise.toml or as a standalone script that executes within the mise environment. See [Tasks](/tasks/).

**Task Dependencies**
: Relationships between tasks defined via `depends` (run before), `depends_post` (run after), or `wait_for` (wait but don't trigger). See [Task Configuration](/tasks/task-configuration).

**TOML Tasks**
: Tasks defined directly in the `[tasks]` section of mise.toml files. See [TOML Tasks](/tasks/toml-tasks).

## Directories & Environment

**MISE\_CACHE\_DIR**
: Directory where mise caches downloaded files and metadata. Defaults to `~/.cache/mise` on Linux, `~/Library/Caches/mise` on macOS.

**MISE\_DATA\_DIR**
: Directory where mise stores installed tools and other persistent data. Defaults to `~/.local/share/mise`.

**MISE\_PROJECT\_ROOT**
: Environment variable automatically set to the root directory of the current project (where the mise.toml is located).

## Other Terms

**Aliases**
: Alternative names for tool versions, allowing shortcuts like `lts` for Node.js LTS versions. See [Tool Aliases](/dev-tools/aliases).

**direnv**
: An external tool for environment management that mise can work alongside. See [direnv integration](/direnv).

**mise-en-place**
: French culinary phrase meaning "everything in its place" - the philosophy behind mise. Chefs prepare all ingredients before cooking; developers should have all tools ready before coding.

**mise.lock**
: A lockfile that records exact resolved versions for reproducible environments across machines and CI. See [mise.lock](/dev-tools/mise-lock).

**Tool Options**
: Configuration in mise.toml that changes tool behavior, such as setting a Python `virtualenv` path or Node.js `corepack` preferences.

---

---
url: /lang/go.md
---
# Go

`mise` can be used to install and manage multiple versions of [go](https://golang.org/) on the same system.

> The following are instructions for using the go mise core plugin. This is used when there isn't a
> git plugin installed named "go". If you want to use [asdf-golang](https://github.com/kennyp/asdf-golang)
> then use `mise plugins install go GIT_URL`.

The code for this is inside the mise repository at
[`./src/plugins/core/go.rs`](https://github.com/jdx/mise/blob/main/src/plugins/core/go.rs).

## Usage

The following installs the latest version of go-1.21.x (if some version of 1.21.x is not already
installed) and makes it the global default:

```sh
mise use -g go@1.21
```

Minor go versions 1.20 and below require specifying `prefix` before the version number because the
first version of each series was released without a `.0` suffix, making 1.20 an exact version match:

```sh
mise use -g go@prefix:1.20
```

## `.go-version` file support

mise uses a `mise.toml` or `.tool-versions` file for auto-switching between software versions.
However, it can also read go-specific version files named `.go-version`.

See [idiomatic version files](/configuration.html#idiomatic-version-files)

## Default packages

mise can automatically install a default set of packages right after installing a new go version.
To enable this feature, provide a `$HOME/.default-go-packages` file that lists one packages per
line, for example:

```text
github.com/daixiang0/gci # allows comments
github.com/jesseduffield/lazygit
```

## Settings

---

---
url: /dev-tools/backends/go.md
---
# Go Backend

You may install packages directly via [go install](https://go.dev/doc/install) even if there
isn't an asdf plugin for it.

The code for this is inside of the mise repository at [`./src/backend/go.rs`](https://github.com/jdx/mise/blob/main/src/backend/go.rs).

## Dependencies

This relies on having `go` installed. Which you can install via mise:

```sh
mise use -g go
```

::: tip
Any method of installing `go` is fine if you want to install go some other way.
mise will use whatever `go` is on PATH.
:::

## Usage

The following installs the latest version of [hivemind](https://github.com/DarthSim/hivemind) and
sets it as the active version on PATH:

```sh
$ mise use -g go:github.com/DarthSim/hivemind
$ hivemind --help
Hivemind version 1.1.0
```

## Tool Options

The following [tool-options](/dev-tools/#tool-options) are available for the `go` backend—these
go in `[tools]` in `mise.toml`.

### `tags`

Specify go build tags (passed as `go install --tags`):

```toml
[tools]
"go:github.com/golang-migrate/migrate/v4/cmd/migrate" = { version = "latest", tags = "postgres" }
```

---

---
url: /hooks.md
---
# Hooks&#x20;

You can have mise automatically execute scripts during a `mise activate` session. You cannot use these
without the `mise activate` shell hook installed in your shell—except the `preinstall` and `postinstall` hooks.
The configuration goes into `mise.toml`.

## CD hook

This hook is run anytimes the directory is changed.

```toml
[hooks]
cd = "echo 'I changed directories'"
```

## Enter hook

This hook is run when the project is entered. Changing directories while in the project will not trigger this hook again.

```toml
[hooks]
enter = "echo 'I entered the project'"
```

## Leave hook

This hook is run when the project is left. Changing directories while in the project will not trigger this hook.

```toml
[hooks]
leave = "echo 'I left the project'"
```

## Preinstall/postinstall hook

These hooks are run before and after tools are installed (respectively). Unlike other hooks, these hooks do not require `mise activate`.

```toml
[hooks]
preinstall = "echo 'I am about to install tools'"
postinstall = "echo 'I just installed tools'"
```

The `postinstall` hook receives a `MISE_INSTALLED_TOOLS` environment variable containing a JSON array of the tools that were just installed:

```toml
[hooks]
postinstall = '''
echo "Installed: $MISE_INSTALLED_TOOLS"
# Example output: [{"name":"node","version":"20.10.0"},{"name":"python","version":"3.12.0"}]
'''
```

## Tool-level postinstall

Individual tools can define their own postinstall scripts using the `postinstall` option. These run immediately after each tool is installed (before other tools in the same session are installed):

```toml
[tools]
node = { version = "20", postinstall = "npm install -g pnpm" }
python = { version = "3.12", postinstall = "pip install pipx" }
```

Tool-level postinstall scripts receive the following environment variables:

* `MISE_TOOL_NAME`: The short name of the tool (e.g., "node", "python")
* `MISE_TOOL_VERSION`: The version that was installed (e.g., "20.10.0", "3.12.0")
* `MISE_TOOL_INSTALL_PATH`: The path where the tool was installed

## Task hooks

Instead of inline scripts, hooks can reference mise tasks. The task is executed as a subprocess
via `mise run`, so it reuses the full task system including dependencies, environment variables,
and file-based task definitions.

```toml
[tasks.setup]
run = "echo 'setting up project'"
depends = ["install-deps"]

[hooks]
enter = { task = "setup" }
```

You can mix task references with inline scripts in arrays:

```toml
[hooks]
enter = ["echo 'entering project'", { task = "setup" }]
```

Task hooks work with all hook types (`enter`, `leave`, `cd`, `preinstall`, `postinstall`).

## Watch files hook

While using `mise activate` you can have mise watch files for changes and execute a script or task when a file changes.

```toml
[[watch_files]]
patterns = ["src/**/*.rs"]
run = "cargo fmt"
```

You can also reference a mise task instead of an inline script:

```toml
[[watch_files]]
patterns = ["uv.lock"]
task = "sync-deps"
```

Each `[[watch_files]]` entry should have either `run` or `task`, but not both.

This hook will have the following environment variables set:

* `MISE_WATCH_FILES_MODIFIED`: A colon-separated list of the files that have been modified. Colons are escaped with a backslash.

## Hook execution

Hooks are executed with the following environment variables set:

* `MISE_ORIGINAL_CWD`: The directory that the user is in.
* `MISE_PROJECT_ROOT`: The root directory of the project.
* `MISE_PREVIOUS_DIR`: The directory that the user was in before the directory change (only if a directory change occurred).
* `MISE_INSTALLED_TOOLS`: A JSON array of tools that were installed (only for `postinstall` hooks).

## Shell hooks

Hooks can be executed in the current shell, for example if you'd like to add bash completions when entering a directory:

```toml
[hooks.enter]
shell = "bash"
script = "source completions.sh"
```

::: warning
I feel this should be obvious but in case it's not, this isn't going to do any sort of cleanup
when you *leave* the directory like using `[env]` does in `mise.toml`. You're literally just
executing shell code when you enter the directory which mise has no way to track at all.
I don't think there is a solution to this problem and it's likely the reason direnv has never
implemented something similar.

I think in most situations this is probably fine, though worth keeping in mind.

:::

## Multiple hooks syntax

You can use arrays to define multiple hooks in the same file:

```toml
[hooks]
enter = [
  "echo 'I entered the project'",
  "echo 'I am in the project'"
]

[[hooks.cd]]
script = "echo 'I changed directories'"
[[hooks.cd]]
script = "echo 'I also directories'"
```

---

---
url: /how-i-use-mise.md
---
# How I use mise

This is a very different doc than the rest of the site. It's not my
intention to make this valuable to anyone. In fact it may end up being
useful to 0 people.

I'm probably the strangest user of mise out there. My use case is the
most atypical for a number of reasons I'll get to. That said, I often
find myself saying to friends "you know the way I use mise..." and thought
it might be useful to actually write down the way I use it in case
anyone is interested.

This is an advanced article. I'm not going to take the time to explain
the tools and techniques here. If you're curious, open a discussion or ask
me in the Discord.

## My setup

I use a mac with fish shell and am a heavy homebrew user. I've been using
both for over a decade.

My main editor(s) are JetBrains products (IntelliJ, RustRover, Webstorm).
I also use nvim as a secondary editor (Astronvim with some minimal config).
I probably spend 70% of my time in JetBrains.

I tend to keep a terminal open (kitty) while working in JetBrains. I do not
often run tests or builds with in the IDE. Not sure why, just never been
in the habit of that. (Because of that these docs and possibly mise support in
IDEs may not be what it should be-it's just not how I work personally).

## `mise activate`

Unlike most mise users, I don't use `mise activate` or
shims at all unless I'm explicitly testing them-and that's rarely the
case. It certainly doesn't go into my `~/.config/fish/config.fish`.

Because I work on mise itself, I often need to rebuild it and run the code from my repo. For this, I have the following bash shim located in
`~/bin/@mise`:

```fish
#!/usr/bin/env bash
set -euo pipefail

exec cargo run -q --all-features --manifest-path ~/src/mise/Cargo.toml -- "$@"
```

:::info
The "@" prefix I use for things that will perform a rebuild-i.e.: they're slow.
:::

This way I can easily test mise in any directory with `@mise`. I probably
run this more often than without just out of habit. For example, if I want to test `mise activate` in zsh:

```sh
zsh
eval "$(@mise activate zsh)"
```

## Minimal tools

Might be surprising to folks but I don't use too many mise plugins. Well
I have a lot in my config, but I don't actually use them. They're for
testing.

I tend to basically just use core plugins. I like mise for managing
things where I really care about the major version (like node). If it's
something like `shfmt` or `jq` I don't really care about the version.
I just want the latest and for me, I find `brew` to be better suited to
that purpose.

I recognize that some people really like locking down their versions
across a team to keep things consistent. I think that's great too.
Part of this is that I'm currently at Amazon where the tooling story
is complicated let's just say-not in a bad way, just one where
integrating mise into the setup isn't as straightforward as a smaller
company would be.

Outside of Amazon I have a handful of open source projects, mostly
mise-related and mostly fairly simple. Also mostly rust where I don't
use mise anyways.

The one big exception here is node which I quite like mise for. I assume
others do to because it's by far the most popular language. You'd
probably guess that since it's my example in nearly all of the docs.

That said, part of the reason for doing that in the docs is that it's 4
characters and everyone knows what it is.

## `.mise.local.toml`

I'm a heavy user of this concept. I rarely like to actually commit `mise.toml`
files into projects. I tend to see my mise config as my personal config that
I use within other projects that I don't particularly want to share with others.

Of course, this goes into my global gitconfig so I can easily add this to
shared projects without submitting a PR.

One day when tasks is out of experimental, I may do this a lot less since I
think tasks are one thing I really want to share. For me, the `[tools]`
section is just so easy to write I don't mind doing it and don't like
imposing the way that **I** setup my machine on others.

There is a social aspect of this as well that I'm conscious of. I'm
the author of `mise`. To me it's a little self-serving to go into a project
and add a config for my own project. I'd love if *someone else* did that
instead.

## `~/.mise`

I often need to access mise's internals so I do the following:

```sh
ln -s ~/.mise ~/.config/mise
ln -s ~/.mise ~/.local/share/mise
ln -s ~/.mise ~/.local/state/mise
ln -s ~/.mise/cache ~/.cache/mise
```

It is good that mise generally follows XDG spec, but for tools that I interact
with a lot I like to put them at the top level like this. Obviously,
mise doesn't mind if all of these point to the same place or else it would
not work for me.

---

---
url: /dev-tools/backends/http.md
---
# HTTP Backend

You may install tools directly from HTTP URLs using the `http` backend. This backend downloads files from any HTTP/HTTPS URL and is ideal for tools that distribute pre-built binaries or archives through direct download links.

The code for this is inside of the mise repository at [`./src/backend/http.rs`](https://github.com/jdx/mise/blob/main/src/backend/http.rs).

## Usage

The following installs a tool from a direct HTTP URL:

```sh
mise use -g http:my-tool[url=https://example.com/releases/my-tool-v1.0.0.tar.gz]@1.0.0
```

The version will be set in `~/.config/mise/config.toml` with the following format:

```toml
[tools]
"http:my-tool" = { version = "1.0.0", url = "https://example.com/releases/my-tool-v1.0.0.tar.gz" }
```

## Supported HTTP Syntax

* **HTTP with URL parameter:** `http:my-tool[url=https://example.com/releases/my-tool-v1.0.0.tar.gz]@1.0.0`

## Tool Options

The following [tool-options](/dev-tools/#tool-options) are available for the `http` backend—these
go in `[tools]` in `mise.toml`.

### `url` (Required)

Specifies the HTTP URL to download the tool from. The URL supports templating with variables like `version`, `os()`, and `arch()`:

```toml
[tools]
"http:my-tool" = { version = "1.0.0", url = "https://example.com/releases/my-tool-v{{version}}.tar.gz" }
```

You can also use static URLs without templating:

```toml
[tools]
"http:my-tool" = { version = "1.0.0", url = "https://example.com/releases/my-tool-v1.0.0.tar.gz" }
```

#### Template Variables

The following template functions are available in URLs (use double curly braces, e.g., `version` becomes {{version}}):

* `version` - The tool version
* `os()` - Operating system: `macos`, `linux`, or `windows`
* `arch()` - Architecture: `x64` or `arm64`
* `os_family()` - OS family: `unix` or `windows`

The `os()` and `arch()` functions support remapping for tools that use different naming conventions:

```toml
[tools]
# HashiCorp tools use "darwin" instead of "macos" and "amd64" instead of "x64"
"http:sentinel" = {
  version = "latest",
  url = 'https://releases.hashicorp.com/sentinel/{{version}}/sentinel_{{version}}_{{os(macos="darwin")}}_{{arch(x64="amd64")}}.zip',
}
```

This produces URLs like:

* macOS arm64: `sentinel_0.26.3_darwin_arm64.zip`
* macOS x64: `sentinel_0.26.3_darwin_amd64.zip`
* Linux x64: `sentinel_0.26.3_linux_amd64.zip`

### Platform-specific URLs

For tools that need different downloads per platform, use the table format:

```toml
[tools."http:my-tool"]
version = "1.0.0"

[tools."http:my-tool".platforms]
macos-x64 = { url = "https://example.com/releases/my-tool-v1.0.0-macos-x64.tar.gz" }
macos-arm64 = { url = "https://example.com/releases/my-tool-v1.0.0-macos-arm64.tar.gz" }
linux-x64 = { url = "https://example.com/releases/my-tool-v1.0.0-linux-x64.tar.gz" }
```

::: tip
You can use either `macos` or `darwin`, and `x64` or `amd64` for platform keys. `macos` and `x64` are preferred in documentation and examples, but all variants are accepted.

OS/architecture values use mise's conventions: `linux`, `macos`, `windows` for operating systems and `x64`, `arm64` for architectures. For platform-specific URLs, use the appropriate platform key (e.g., `macos-x64`, `linux-arm64`) and specify the full URL for each platform.

If you mess up and use something like `darwin-aarch64` mise will try to figure out what
you meant and do the right thing anyhow.
:::

### `checksum`

Verify the downloaded file with a checksum:

```toml
[tools."http:my-tool"]
version = "1.0.0"
url = "https://example.com/releases/my-tool-v1.0.0.tar.gz"
checksum = "sha256:a1b2c3d4e5f6789..."
```

*Instead of specifying the checksum here, you can use [mise.lock](/dev-tools/mise-lock) to manage checksums.*

### Platform-specific Checksums

```toml
[tools."http:my-tool"]
version = "1.0.0"

[tools."http:my-tool".platforms]
macos-x64 = {
  url = "https://example.com/releases/my-tool-v1.0.0-macos-x64.tar.gz",
  checksum = "sha256:a1b2c3d4e5f6789...",
}
macos-arm64 = {
  url = "https://example.com/releases/my-tool-v1.0.0-macos-arm64.tar.gz",
  checksum = "sha256:b2c3d4e5f6789...",
}
linux-x64 = {
  url = "https://example.com/releases/my-tool-v1.0.0-linux-x64.tar.gz",
  checksum = "sha256:c3d4e5f6789...",
}
```

### `size`

Verify the downloaded file size:

```toml
[tools."http:my-tool"]
version = "1.0.0"
url = "https://example.com/releases/my-tool-v1.0.0.tar.gz"
size = "12345678"
```

### Platform-specific Size

You can specify different sizes for different platforms:

```toml
[tools."http:my-tool"]
version = "1.0.0"

[tools."http:my-tool".platforms]
macos-x64 = {
  url = "https://example.com/releases/my-tool-v1.0.0-macos-x64.tar.gz",
  size = "12345678",
}
macos-arm64 = {
  url = "https://example.com/releases/my-tool-v1.0.0-macos-arm64.tar.gz",
  size = "9876543",
}
linux-x64 = {
  url = "https://example.com/releases/my-tool-v1.0.0-linux-x64.tar.gz",
  size = "11111111",
}
```

### `strip_components`

Number of directory components to strip when extracting archives:

```toml
[tools."http:my-tool"]
version = "1.0.0"
url = "https://example.com/releases/my-tool-v1.0.0.tar.gz"
strip_components = 1
```

::: info
If `strip_components` is not explicitly set, mise will automatically detect when to apply `strip_components = 1`. This happens when the extracted archive contains exactly one directory at the root level and no files. This is common with tools like ripgrep that package their binaries in a versioned directory (e.g., `ripgrep-14.1.0-x86_64-unknown-linux-musl/rg`). The auto-detection ensures the binary is placed directly in the install path where mise expects it.
:::

### `bin`

Rename the downloaded binary to a specific name. This is useful when downloading single binaries that have platform-specific names:

```toml
[tools."http:docker-compose"]
version = "2.29.1"
url = "https://github.com/docker/compose/releases/download/v{{ version }}/docker-compose-linux-x86_64"
bin = "docker-compose"  # Rename from docker-compose-linux-x86_64 to docker-compose
```

::: info
When downloading single binaries (not archives), mise automatically removes OS/arch suffixes from the filename. For example, `docker-compose-linux-x86_64` becomes `docker-compose` automatically. Use the `bin` option only when you need a specific custom name.
:::

### `rename_exe`

Rename the executable inside an extracted archive to a specific name. This is useful when archives contain binaries with platform-specific names or when installing kubectl plugins that need specific naming:

```toml
[tools."http:openunison-cli"]
version = "1.0.0"
url = "https://nexus.tremolo.io/repository/openunison-cli/openunison-cli-v{{version}}-linux.zip"
rename_exe = "kubectl-openunison-cli"  # Rename extracted binary for kubectl plugin
```

This works by searching for the first executable in the extracted directory (or `bin_path` if specified) and renaming it to the specified name.

::: tip
Use `bin` for renaming single binary downloads, and `rename_exe` for renaming executables inside archives.
:::

### `format`

Explicitly specify the archive format when the URL lacks a file extension or has an incorrect extension:

```toml
[tools."http:my-tool"]
version = "1.0.0"
url = "https://example.com/releases/my-tool-v1.0.0"
format = "tar.xz"  # Explicitly specify the format
```

::: info
If `format` is not specified, mise will automatically detect the format from the file extension in the URL. Only use `format` when the URL doesn't have a proper extension or when you need to override the detected format.
:::

### Platform-specific Format

You can specify different formats for different platforms:

```toml
[tools."http:my-tool"]
version = "1.0.0"

[tools."http:my-tool".platforms]
macos-x64 = {
  url = "https://example.com/releases/my-tool-v1.0.0-macos-x64",
  format = "tar.xz",
}
linux-x64 = {
  url = "https://example.com/releases/my-tool-v1.0.0-linux-x64",
  format = "tar.gz",
}
windows-x64 = {
  url = "https://example.com/releases/my-tool-v1.0.0-windows-x64",
  format = "zip",
}
```

### `version_list_url`

Fetch available versions from a remote URL. This enables `mise ls-remote` to list available versions for HTTP-based tools:

```toml
[tools."http:my-tool"]
version = "1.0.0"
url = "https://example.com/releases/my-tool-v{{version}}.tar.gz"
version_list_url = "https://example.com/releases/versions.txt"
```

The version list URL can return data in multiple formats:

* **Plain text**: A single version number (e.g., `2.0.53`)
* **Line-separated**: One version per line
* **JSON array of strings**: `["1.0.0", "1.1.0", "2.0.0"]`
* **JSON array of objects**: `[{"version": "1.0.0"}, {"tag_name": "v2.0.0"}]`
* **JSON object with versions array**: `{"versions": ["1.0.0", "2.0.0"]}`

Version prefixes like `v` are automatically stripped.

### `version_regex`

Extract versions from the version list URL response using a regular expression:

```toml
[tools."http:my-tool"]
version = "1.0.0"
url = "https://example.com/releases/my-tool-v{{version}}.tar.gz"
version_list_url = "https://example.com/releases/"
version_regex = 'my-tool-v(\d+\.\d+\.\d+)\.tar\.gz'
```

The first capturing group is used as the version. If no capturing group is present, the entire match is used.

### `version_json_path`

Extract versions from JSON responses using a jq-like path expression:

```toml
[tools."http:my-tool"]
version = "1.0.0"
url = "https://example.com/releases/my-tool-v{{version}}.tar.gz"
version_list_url = "https://api.example.com/releases"
version_json_path = ".[].tag_name"
```

Supported path expressions:

* `.` - root value
* `.[]` - iterate over array elements
* `.[].field` - extract field from each array element
* `.field` - extract field from object
* `.field[]` - iterate over array in field
* `.field.subfield` - nested field access
* `.data.versions[]` - complex nested paths
* `.[?field=value]` - filter array elements where field equals value

Examples:

```toml
# GitHub releases API format
version_json_path = ".[].tag_name"

# Nested versions array
version_json_path = ".data.versions[]"

# Release info objects
version_json_path = ".releases[].info.version"

# Filter for stable releases only (e.g., Flutter)
version_json_path = ".releases[?channel=stable].version"
```

The filter syntax `[?field=value]` allows filtering JSON arrays before extraction. This is useful for APIs that return multiple release channels (stable, beta, dev) and you only want specific ones.

### `version_expr`

Extract versions using an [expr-lang](https://expr-lang.org/) expression. This provides the most flexibility for complex version extraction logic:

```toml
[tools."http:my-tool"]
version = "latest"
url = "https://example.com/releases/my-tool-v{{ version }}.tar.gz"
version_list_url = "https://example.com/versions.txt"
version_expr = 'split(body, "\n")'
```

The expression receives the HTTP response body as the `body` variable and should return an array of version strings.

Example expressions:

```toml
# Split newline-separated versions
version_expr = 'split(body, "\n")'

# Split and filter empty lines
version_expr = 'filter(split(body, "\n"), # != "")'

# Parse JSON and extract object keys (useful for HashiCorp-style JSON)
# e.g., {"versions": {"1.0.0": {}, "2.0.0": {}}}
version_expr = 'keys(fromJSON(body).versions)'
```

The [expr-lang](https://expr-lang.org/) library provides built-in functions including:

* **`fromJSON(string)`**: Parse a JSON string into a value
* **`toJSON(value)`**: Convert a value to a JSON string
* **`keys(map)`**: Get the keys of an object/map as an array
* **`values(map)`**: Get the values of an object/map as an array
* **`len(value)`**: Get the length of a string, array, or map

::: tip
`version_expr` takes precedence over `version_regex` and `version_json_path` if multiple are specified. Use it when the other options aren't flexible enough for your use case.
:::

### `bin_path`

Specify the directory containing binaries within the extracted archive, or where to place the downloaded file. This supports templating with `{{version}}`:

```toml
[tools."http:my-tool"]
version = "1.0.0"
url = "https://example.com/releases/my-tool-v1.0.0.tar.gz"
bin_path = "my-tool-{{version}}/bin" # expands to my-tool-1.0.0/bin
```

**Binary path lookup order:**

1. If `bin_path` is specified, use that directory
2. If `bin_path` is not set, look for a `bin/` directory in the install path
3. If no `bin/` directory exists, search subdirectories for `bin/` directories
4. If no `bin/` directories are found, use the root of the extracted directory

## Caching Behavior

The HTTP backend implements an intelligent caching system to optimize disk usage and installation speed:

### Cache Location

Downloaded and extracted files are cached in `$MISE_CACHE_DIR/http-tarballs/` instead of being stored separately for each tool installation. By default:

* **Linux**: `~/.cache/mise/http-tarballs/`
* **macOS**: `~/Library/Caches/mise/http-tarballs/`

### Cache Key Generation

Cache keys are generated based on the file content to ensure identical downloads are shared across tools:

1. **Blake3 hash of file content**: When no checksum is provided, mise calculates a Blake3 hash of the downloaded file
2. **Extraction options**: `strip_components` is included in the cache key since it affects the extracted structure

Example cache directory structure:

```
~/.cache/mise/http-tarballs/
├── 71f774faa03daf1a58cc3339f8c73e6557348c8e0a2f3fb8148cc26e26bad83f/
│   ├── extracted/
│   │   └── bin/my-tool
│   └── metadata.json
└── 1c2af379bdf1fed266bc44b49271e2df5b0dafae09f1cc744b3505ec50c84719_strip_1/
    ├── extracted/
    │   └── my-tool
    └── metadata.json
```

### Symlinked Installations

Tool installations are symlinks to the cached extracted content:

```bash
~/.local/share/mise/installs/http-my-tool/1.0.0 → ~/.cache/mise/http-tarballs/71f774.../extracted
```

This approach provides several benefits:

* **Space efficiency**: Multiple tools using the same tarball share a single cached copy
* **Faster installations**: Cache hits avoid re-downloading and re-extracting files
* **Consistency**: Identical file content always uses the same cache entry

### Cache Metadata

Each cache entry includes a `metadata.json` file with information about the cached content:

```json
{
  "url": "https://example.com/releases/my-tool-v1.0.0.tar.gz",
  "checksum": "sha256:a1b2c3d4e5f6789...",
  "size": 1024000,
  "extracted_at": 1703001234,
  "platform": "macos-arm64"
}
```

### Cache Management

The HTTP backend cache follows mise's standard cache management:

* Cache entries can be cleared with `mise cache clear`
* The cache directory respects the `MISE_CACHE_DIR` environment variable
* **Autopruner**: mise automatically cleans up unused cache entries after 30 days of inactivity
* Manual cleanup is available with `mise cache clear` if needed

---

---
url: /ide-integration.md
---
# IDE Integration

Code editors and IDEs work differently than interactive shells.

Usually, they will either inherit the environment from your current shell (this is the case if you start it from a terminal like `nvim .` or `code .`) or will have [their own way](https://github.com/microsoft/vscode-docs/blob/906acccd6180d8425577f8297ed29e221ad3daca/docs/supporting/faq.md?plain=1#L238) to set up the environment.

Once you have launched the IDE, it won't reload the environment variables or the `PATH` provided by `mise` if you update your mise configuration files. Therefore, we cannot rely on the default `mise activate` method to automatically set up the editor.

There are a few ways to make `mise` work with your editor:

* Some editors or IDE plugins have direct support for `mise` and can let you select the tools/sdk path from the IDE settings. This will let you access to the tool binaries but won't load the environment variables.
* Most editors (and language plugins) will look for tools on the `PATH` and run them in the context of your project. Therefore, adding the `mise` shims to the `PATH` might be enough (see [below](#adding-shims-to-path-default-shell)). This will run the tool provided by mise and load the environment variables.
* In other cases, you may need to manually indicate the path to the tools provided by `mise` in the IDE settings. This can be done by using [`mise which <tool>`](./cli/which.md) or [`mise where`](./cli/where). You can also provide the path to the tool shim (e.g. `~/.local/share/mise/shims/node`) if the plugin supports it as this will also load the environment variables when the tool is run.
* Finally, some custom plugins have been developed to work with `mise`. You can find them in the [IDE Plugins](#ide-plugins) section.

## Adding shims to PATH in your default shell profile {#adding-shims-to-path-default-shell}

IDEs work better with [shims](./dev-tools/shims) than they do environment variable modifications. The simplest way is
to add the mise shim directory to `PATH`.

For IntelliJ and VSCode—and likely others, you can modify your default shell's login (aka "profile")
script. Your default shell can be found with:

::: code-group

```shell [macos]
dscl . -read /Users/$USER UserShell
```

```shell [linux]
getent passwd $USER | cut -d: -f7
```

:::

You can change your default shell with `chsh -s /path/to/shell` but you may need
to first add it to `/etc/shells`. Once you know the right one, modify the appropriate file:

::: code-group

```zsh
# ~/.zprofile
eval "$(mise activate zsh --shims)"
```

```bash
# ~/.bash_profile or ~/.bash_login or ~/.profile
eval "$(mise activate bash --shims)"
```

```fish
# ~/.config/fish/config.fish
if status is-interactive
  mise activate fish | source
else
  mise activate fish --shims | source
end
```

:::

::: warning
Do not use /bin/bash or /usr/bin/bash on macOS. bash is complicated, decades old, and mise isn't able to use as many features.
Unless you consider yourself an expert on bash and know why I (and Apple for that matter) admonish using bash, just use zsh on macOS.
:::

On Linux this is read when logging into the machine, so changing it requires logging out and back in for it to work. See #vscode below
for how to get VSCode to read the login file.

This assumes that `mise` is on `PATH`. If it is not, you'll need to use the absolute path (
e.g.: `eval "$($HOME/.local/bin/mise activate zsh --shims)"`).

Here is an example showing that VSCode will use `node` provided by `mise`:

::: tabs
\=== VSCode

![vscode using shims](./shims-vscode.png)

\=== IntelliJ
![intellij using shims](./shims-intellij.png)
:::

As mentioned above, using `shims` doesn't work with all mise features. For example, arbitrary [env vars](./environments/) in `[env]` will
only be set if a shim is executed. For this we need tighter integration with the IDE and/or a custom plugin.

## IDE Plugins

Here are some community plugins that have been developed to work with `mise`:

* Emacs: [mise.el](https://github.com/liuyinz/mise.el)
* IntelliJ: [intellij-mise](https://github.com/134130/intellij-mise)
* VSCode: [mise-vscode](https://github.com/hverlin/mise-vscode)

## Vim

```vim
" Prepend mise shims to PATH
let $PATH = $HOME . '/.local/share/mise/shims:' . $PATH
```

## Neovim

```lua
-- Prepend mise shims to PATH
vim.env.PATH = vim.env.HOME .. "/.local/share/mise/shims:" .. vim.env.PATH
```

For a better Treesitter and LSP integration, check out the [neovim cookbook](./mise-cookbook/neovim.md).

## emacs

### Traditional shims way

```lisp
;; CLI tools installed by Mise
;; See: https://www.emacswiki.org/emacs/ExecPath
(setenv "PATH" (concat (getenv "PATH") ":/home/user/.local/share/mise/shims"))
(setq exec-path (append exec-path '("/home/user/.local/share/mise/shims")))
```

### Use with package [mise.el](https://github.com/eki3z/mise.el)

<https://github.com/eki3z/mise.el>

> A GNU Emacs library which uses the mise tool to determine per-directory/project environment variables and then set those environment variables on a per-buffer basis.

```lisp
(require 'mise)
(add-hook 'after-init-hook #'global-mise-mode)
```

## JetBrains Editors (IntelliJ, RustRover, PyCharm, WebStorm, RubyMine, GoLand, etc)

### IntelliJ Plugin

<https://github.com/134130/intellij-mise>

This plugin can automatically configure the IDE to use the tools provided by mise. It has also some support for running mise tasks and loading environment variables in the run configurations.

### Direct SDK selection

Some JetBrains IDEs (or language plugins) have direct support for `mise`. This allows you to select the SDK version from the IDE settings.
Example for Java:

![SDK settings](./intellij-sdk-selection.png)

### SDK selection using asdf layout

Some plugins cannot find SDK installed by `mise` yet but might have support for asdf.
In that case, a workaround is to symlink the mise tool directory which has same layout as asdf:

```sh
ln -s ~/.local/share/mise ~/.asdf
```

Then they should show up on in Project Settings:

![project settings](https://github.com/jdx/mise-docs/assets/216188/b34a0e3f-7af8-45c9-85b8-2c72bd1dc226)

Or in the case of node (possibly other languages), it's under "Languages & Frameworks":

![languages & frameworks](https://github.com/jdx/mise-docs/assets/216188/9926be1c-ab88-451a-8ace-edf2dac564b5)

## VSCode

### VSCode Automation Profile for macOS

Unlike Linux, macOS does not read the login shell profile (`~/.profile`, or `~/.zprofile`) when logging into the machine. You'll likely
want to add this setting to VSCode config in order to have it load your shims:

```json
    "terminal.integrated.automationProfile.osx": {
        "path": "/usr/bin/zsh",
        "args": ["--login"]
    }
```

:::tip
You can also use `["--login", "--interactive"]` if you want to include `~/.zshrc`.
:::

### VSCode Plugin

There is a [VSCode plugin](https://marketplace.visualstudio.com/items?itemName=hverlin.mise-vscode) which can configure other extensions for you, without having to modify your shell profile to add the shims to `PATH`.

In addition, it provides additional features such as:

* Automatic configuration of other extensions to use tools provided by `mise`
* Manage `mise` tasks, tools, and environment variables directly from VSCode
* Load environment variables from `mise.toml` files in VSCode
* Support for autocompletion and snippets for `mise.toml` file
* Integration with VSCode tasks

<https://github.com/hverlin/mise-vscode/> ([Documentation](https://hverlin.github.io/mise-vscode/))

### Use [`mise exec`](./cli/exec) in launch Configuration

While modifying your default shell profile is likely the easiest solution, you can also set
the tools in `launch.json`:

::: details mise exec launch.json example

```json
{
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "program": "${file}",
      "args": [],
      "osx": {
        "runtimeExecutable": "mise"
      },
      "linux": {
        "runtimeExecutable": "mise"
      },
      "runtimeArgs": ["exec", "--", "node"]
    }
  ]
}
```

:::

## Xcode

Xcode projects can run system commands from script build phases and schemes. Since Xcode sandboxes
the execution of the script using the tool `/usr/bin/sandbox-exec`, don't expect Mise and the
automatically-activated tools to work out of the box. First, you'll need to
add `$(SRCROOT)/mise.toml` to the list of **Input files**. This is necessary for Xcode to allow
reads to that file. Then, you can use `mise activate` to activate the tools you need:

```bash
# -C ensures that Mise loads the configuration from the Mise configuration
# file in the project's root directory.
eval "$($HOME/.local/bin/mise activate -C $SRCROOT bash --shims)"

swiftlint
```

---

---
url: /installing-mise.md
---
# Installing Mise

If you are new to `mise`, follow the [Getting Started](/getting-started) guide first.

## Installation Methods

This page lists various ways to install `mise` on your system.

| Platform              | Recommended    | Alternative     |
| --------------------- | -------------- | --------------- |
| macOS                 | Homebrew       | mise.run        |
| Linux (Debian/Ubuntu) | apt            | mise.run        |
| Linux (Fedora/RHEL)   | dnf            | mise.run        |
| Linux (Arch)          | pacman         | mise.run        |
| Linux (Alpine)        | apk            | mise.run        |
| Windows               | Scoop          | winget          |
| Any (Rust users)      | cargo binstall | cargo install   |
| CI/Docker             | mise.run       | GitHub Releases |

::: tip Which methods auto-update?
Package managers (apt, dnf, brew, pacman, etc.) update mise when you update system packages. Other methods can be updated with `mise self-update`.
:::

### <https://mise.run>

Note that it isn't necessary for `mise` to be on `PATH`. If you run the activate script in your
shell's rc
file, mise will automatically add itself to `PATH`.

```sh
curl https://mise.run | sh
```

or with options

```sh
curl https://mise.run | MISE_INSTALL_PATH=/usr/local/bin/mise sh
```

#### Shell-specific installation + activation

For a more streamlined setup, you can use shell-specific endpoints that will install mise and automatically configure activation in your shell's configuration file:

::: code-group

```sh [zsh]
curl https://mise.run/zsh | sh
# Installs mise and adds activation to ~/.zshrc
```

```sh [bash]
curl https://mise.run/bash | sh
# Installs mise and adds activation to ~/.bashrc
```

```sh [fish]
curl https://mise.run/fish | sh
# Installs mise and adds activation to ~/.config/fish/config.fish
```

:::

These shell-specific installers will:

* Install mise using the same logic as the main installer
* Automatically detect your shell's configuration file
* Add the activation line if it's not already present
* Skip adding activation if it's already configured (safe to run multiple times)

Options:

* `MISE_DEBUG=1` – enable debug logging
* `MISE_QUIET=1` – disable non-error output
* `MISE_INSTALL_PATH=/some/path` – change the binary path (default: `~/.local/bin/mise`)
* `MISE_VERSION=v2025.12.0` – install a specific version

If you want to verify the install script hasn't been tampered with:

```sh
gpg --keyserver hkps://keys.openpgp.org --recv-keys 24853EC9F655CE80B48E6C3A8B81C9D17413A06D
curl https://mise.jdx.dev/install.sh.sig | gpg --decrypt > install.sh
# ensure the above is signed with the mise release key
sh ./install.sh
```

::: tip
As long as you don't change the version with `MISE_VERSION`, the install script will be pinned to whatever the latest
version was when it was downloaded with checksums inside the file. This makes downloading the file and putting it into
a project a great way to ensure that anyone installing with that script fetches the exact same mise bin.
:::

Supported os/arch:

* `macos-x64`
* `macos-arm64`
* `linux-x64`
* `linux-x64-musl`
* `linux-arm64`
* `linux-arm64-musl`
* `linux-armv6`
* `linux-armv6-musl`
* `linux-armv7`
* `linux-armv7-musl`

If you need something else, compile it with `cargo install mise` (see below).

### apk

For Alpine Linux:

```sh
apk add mise
```

*mise lives in
the [community repository](https://gitlab.alpinelinux.org/alpine/aports/-/blob/master/community/mise/APKBUILD).*

### apt

On Ubuntu 26.04+, mise is available via a PPA:

```sh
sudo add-apt-repository -y ppa:jdxcode/mise
sudo apt update -y
sudo apt install -y mise
```

For older Ubuntu/Debian versions:

```sh
sudo apt update -y && sudo apt install -y curl
sudo install -dm 755 /etc/apt/keyrings
curl -fSs https://mise.jdx.dev/gpg-key.pub | sudo tee /etc/apt/keyrings/mise-archive-keyring.asc 1> /dev/null
echo "deb [signed-by=/etc/apt/keyrings/mise-archive-keyring.asc] https://mise.jdx.dev/deb stable main" | sudo tee /etc/apt/sources.list.d/mise.list
sudo apt update -y
sudo apt install -y mise
```

### pacman

For Arch Linux:

```sh
sudo pacman -S mise
```

[Arch package](https://archlinux.org/packages/extra/x86_64/mise/)

### Cargo

Build from source with Cargo:

```sh
cargo install mise
```

Do it faster with [cargo-binstall](https://github.com/cargo-bins/cargo-binstall):

```sh
cargo install cargo-binstall
cargo binstall mise
```

Build from the latest commit in main:

```sh
cargo install mise --git https://github.com/jdx/mise --branch main
```

### dnf

#### Fedora 41+, RHEL 9+, CentOS Stream 9+

```sh
dnf copr enable jdxcode/mise
dnf install mise
```

[COPR package page](https://copr.fedorainfracloud.org/coprs/jdxcode/mise/)

### Snap (Linux, currently in beta)

```sh
sudo snap install mise --classic --beta
```

[snapcraft.io page](https://snapcraft.io/mise)

### Docker

```sh
docker run jdxcode/mise x node@20 -- node -v
```

[Docker Hub](https://hub.docker.com/r/jdxcode/mise)

::: details Example Dockerfile

```dockerfile
FROM jdxcode/mise:latest AS mise

FROM debian:bookworm-slim
COPY --from=mise /usr/local/bin/mise /usr/local/bin/mise
RUN mise trust -a && mise install
```

:::

### Homebrew

```sh
brew install mise
```

[Homebrew formula](https://formulae.brew.sh/formula/mise)

### npm

mise is available on npm as a precompiled binary. This isn't a Node.js package—just distributed
via npm. This is useful for JS projects that want to setup mise via `package.json` or `npx`.

```sh
npm install -g @jdxcode/mise
```

Use npx if you just want to test it out for a single command without fully installing:

```sh
npx @jdxcode/mise exec python@3.11 -- python some_script.py
```

[npm package](https://www.npmjs.com/package/@jdxcode/mise)

### GitHub Releases

Download the latest release from [GitHub](https://github.com/jdx/mise/releases).

```sh
curl -L https://github.com/jdx/mise/releases/download/v2025.12.0/mise-v2025.12.0-linux-x64 > /usr/local/bin/mise
chmod +x /usr/local/bin/mise
```

### MacPorts

```sh
sudo port install mise
```

[MacPorts port](https://ports.macports.org/port/mise/)

### nix

For the Nix package manager, at release 24.05 or later:

```sh
nix-env -iA mise
```

You can also import the package directly using
`mise-flake.packages.${system}.mise`. It supports all default Nix
systems.

::: tip NixOS compiles from source by default
For precompiled binaries, enable [nix-ld](https://github.com/Mic92/nix-ld) and disable [`all_compile`](/configuration/settings.html#all_compile).
:::

### yum (RHEL 8, CentOS Stream 8, Amazon Linux 2)

```sh
yum install -y yum-utils
yum-config-manager --add-repo https://mise.jdx.dev/rpm/mise.repo
yum install -y mise
```

### zypper

```sh
sudo wget https://mise.jdx.dev/rpm/mise.repo -O /etc/zypp/repos.d/mise.repo
sudo zypper refresh
sudo zypper install mise
```

### Windows - Scoop

This is the recommended way to install mise on Windows. It will automatically add your shims to PATH.

```sh
scoop install mise
```

[Scoop manifest](https://github.com/ScoopInstaller/Main/blob/master/bucket/mise.json)

### Windows - winget

```sh
winget install jdx.mise
```

[winget manifest](https://github.com/microsoft/winget-pkgs/tree/master/manifests/j/jdx/mise)

### Windows - Chocolatey

::: info
chocolatey version is currently outdated.
:::

```sh
choco install mise
```

### Windows - manual

Download the latest release from [GitHub](https://github.com/jdx/mise/releases) and add the binary
to your PATH.

If your shell does not support `mise activate`, you would want to edit PATH to include the shims directory (by default: `%LOCALAPPDATA%\mise\shims`).

## Shells

### Bash

```sh
echo 'eval "$(mise activate bash)"' >> ~/.bashrc
```

### Zsh

```sh
echo 'eval "$(mise activate zsh)"' >> "${ZDOTDIR-$HOME}/.zshrc"
```

### Fish

```sh
echo 'mise activate fish | source' >> ~/.config/fish/config.fish
```

::: tip
For homebrew and possibly other installs mise is automatically activated so
this is not necessary.

See [`MISE_FISH_AUTO_ACTIVATE=1`](/configuration#mise-fish-auto-activate-1) for more information.
:::

### PowerShell

::: warning
See [about\_Profiles](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles) docs to find your actual profile location.
You will need to first create the parent directory if it does not exist.
:::

```powershell
echo '(&mise activate pwsh) | Out-String | Invoke-Expression' >> $HOME\Documents\PowerShell\Microsoft.PowerShell_profile.ps1
```

### Nushell

Nu
does [not support `eval`](https://www.nushell.sh/book/how_nushell_code_gets_run.html#eval-function)
Install Mise by appending `env.nu` and `config.nu`:

```nushell
'
let mise_path = $nu.default-config-dir | path join mise.nu
^mise activate nu | save $mise_path --force
' | save $nu.env-path --append
"\nuse ($nu.default-config-dir | path join mise.nu)" | save $nu.config-path --append
```

If you prefer to keep your dotfiles clean you can save it to a different directory then
update `$env.NU_LIB_DIRS`:

```nushell
"\n$env.NU_LIB_DIRS ++= ($mise_path | path dirname | to nuon)" | save $nu.env-path --append
```

### Xonsh

Since `.xsh` files are [not compiled](https://github.com/xonsh/xonsh/issues/3953) you may shave a
bit off startup time by using a pure Python import: add the code below to, for
example, `~/.config/xonsh/mise.py` config file and `import mise` it in `~/.config/xonsh/rc.xsh`:

```python
from pathlib import Path
from xonsh.built_ins import XSH

ctx = XSH.ctx
mise_init = subprocess.run([Path('~/bin/mise').expanduser(),'activate','xonsh'],capture_output=True,encoding="UTF-8").stdout
XSH.builtins.execx(mise_init,'exec',ctx,filename='mise')
```

Or continue to use `rc.xsh`/`.xonshrc`:

```sh
echo 'execx($(~/bin/mise activate xonsh))' >> ~/.config/xonsh/rc.xsh # or ~/.xonshrc
```

Given that `mise` replaces both shell env `$PATH` and OS environ `PATH`, watch out that your configs
don't have these two set differently (might
throw `os.environ['PATH'] = xonsh.built_ins.XSH.env.get_detyped('PATH')` at the end of a config to
make sure they match)

### Elvish

Add following to your `rc.elv`:

```shell
var mise: = (ns [&])
eval (mise activate elvish | slurp) &ns=$mise: &on-end={|ns| set mise: = $ns }
mise:activate
```

Optionally alias `mise` to `mise:mise` for seamless integration of `mise {activate,deactivate,shell}`:

```shell
edit:add-var mise~ {|@args| mise:mise $@args }
```

### Something else?

Adding a new shell is not hard at all since very little shell code is
in this project.
[See here](https://github.com/jdx/mise/tree/main/src/shell) for how
the others are implemented. If your shell isn't currently supported
I'd be happy to help you get yours integrated.

## Autocompletion

::: tip
Some installation methods automatically install autocompletion scripts.
:::

The [`mise completion`](/cli/completion.html) command can generate autocompletion scripts for your shell.
This requires `usage` to be installed. If you don't have it, install it with:

```shell
mise use -g usage
```

Then, run the following commands to install the completion script for your shell:

::: code-group

```sh [bash]
# This requires bash-completion to be installed
mkdir -p ~/.local/share/bash-completion/completions/
mise completion bash --include-bash-completion-lib > ~/.local/share/bash-completion/completions/mise
```

```sh [zsh]
# If you use oh-my-zsh, there is a `mise` plugin. Update your .zshrc file with:
# plugins=(... mise)

# Otherwise, look where zsh search for completions with
echo $fpath | tr ' ' '\n'

# if you installed zsh with `apt-get` for example, this will work:
mkdir -p /usr/local/share/zsh/site-functions
mise completion zsh  > /usr/local/share/zsh/site-functions/_mise
```

```sh [fish]
mise completion fish > ~/.config/fish/completions/mise.fish
```

:::

Then source your shell's rc file or restart your shell.

## Troubleshooting

If you encounter issues after installation, run:

```sh
mise doctor
```

This will diagnose common problems with your mise setup. See [mise doctor](/cli/doctor) for more information.

## Uninstalling

Use `mise implode` to uninstall mise. This will remove the mise binary and all of its data. Use
`mise implode --help` for more information.

Alternatively, manually remove the following directories to fully clean up:

* `~/.local/share/mise` (can also be `MISE_DATA_DIR` or `XDG_DATA_HOME/mise`)
* `~/.local/state/mise` (can also be `MISE_STATE_DIR` or `XDG_STATE_HOME/mise`)
* `~/.config/mise` (can also be `MISE_CONFIG_DIR` or `XDG_CONFIG_HOME/mise`)
* on Linux: `~/.cache/mise` (can also be `MISE_CACHE_DIR` or `XDG_CACHE_HOME/mise`)
* on macOS: `~/Library/Caches/mise` (can also be `MISE_CACHE_DIR`)

---

---
url: /lang/java.md
---
# Java

Like `sdkman`, `mise` can manage multiple versions of Java on the same system.

> The following are instructions for using the java mise core plugin. This is used when there isn't a
> git plugin installed named "java". If you want to use [asdf-java](https://github.com/halcyon/asdf-java)
> then use `mise plugins install java GIT_URL`.

The code for this is inside the mise repository at
[`./src/plugins/core/java.rs`](https://github.com/jdx/mise/blob/main/src/plugins/core/java.rs).

## Usage

The following installs the latest version of openjdk-21.x (if some version of openjdk-21.x is
not already installed) and makes it the global default:

```sh
mise use -g java@openjdk-21
mise use -g java@21         # alternate shorthands for openjdk
```

You can also install a jdk from a different vendor. To get the latest version from a vendor just use the
vendor prefix.

```sh
mise use -g java@temurin        # latest version from Temurin
mise use -g java@temurin-21
mise use -g java@zulu-21
mise use -g java@corretto-21
```

See available versions with `mise ls-remote java`.

::: warning
Note that shorthand versions (like `21` in the example) use [`OpenJDK`](https://openjdk.org/) as the default vendor. The default vendor can be changed with the setting [`java.shorthand_vendor`](../configuration/settings.md#java.shorthand_vendor). The OpenJDK versions will only be updated for a 6-month period. Updates and security patches will not be available after this short period. This also applies for LTS versions.

For more information on which JDK to choose, see <https://whichjdk.com>.
:::

## macOS JAVA\_HOME Integration

Some applications in macOS rely on `/usr/libexec/java_home` to find installed Java runtimes.

To integrate an installed Java runtime with macOS run the following commands for the proper
version (e.g. openjdk-21).

```sh
sudo mkdir /Library/Java/JavaVirtualMachines/openjdk-21.jdk
sudo ln -s ~/.local/share/mise/installs/java/openjdk-21/Contents /Library/Java/JavaVirtualMachines/openjdk-21.jdk/Contents
```

> Note: Not all distributions of the Java SDK support this integration (e.g liberica).

## `.java-version` and `.sdkmanrc` files support

The Java core plugin supports the idiomatic version files `.java-version` and `.sdkmanrc`. See [idiomatic version files](/configuration.html#idiomatic-version-files).

For `.sdkmanrc` files, mise will try to map the vendor and version to the appropriate version
string. For example, the version `20.0.2-tem` will be mapped to `temurin-20.0.2`. Due to Azul's Zulu
versioning, the version `11.0.12-zulu` will be mapped to the major version `zulu-11`.

Not all vendors available in [sdkman](https://sdkman.io/jdks) are supported by mise.
The following vendors are NOT supported: `bsg` (Bisheng), `graal` (GraalVM), `nik` (Liberica NIK).

### Using unsupported versions

In case an unsupported version of java is needed, some manual work is required:

1. Download the unsupported version to a directory (e.g `~/.sdkman/candidates/java/21.0.1-open`)
2. symlink the new version:

```sh
ln -s ~/.sdkman/candidates/java/21.0.1-open ~/.local/share/mise/installs/java/21.0.1-open
```

3. If on Mac:

```sh
mkdir ~/.local/share/mise/installs/java/21.0.1-open/Contents
mkdir ~/.local/share/mise/installs/java/21.0.1-open/Contents/MacOS

ln -s ~/.sdkman/candidates/java/21.0.1-open ~/.local/share/mise/installs/java/21.0.1-open/Contents/Home
cp ~/.local/share/mise/installs/java/21.0.1-open/lib/libjli.dylib ~/.local/share/mise/installs/java/21.0.1-open/Contents/MacOS/libjli.dylib
```

4. Don't forget to make sure the cache is blocked and valid, by making sure an **empty** directory **exists** for your version in the [mise cache](https://mise.jdx.dev/directories.html#cache-mise):
   e.g.

```sh
$ ls -R $MISE_CACHE_DIR/java
21.0.1-open

mise/java/21.0.1-open:
```

## Tool Options

The following [tool-options](/dev-tools/#tool-options) are available for the `java` backend.
These options go in the `[tools]` section in `mise.toml`.

### `release_type`

The `release_type` option allows you to specify the type of release to install. The following values
are supported:

* `ga` (default): General Availability release
* `ea`: Early Access release

```toml
[tools]
"java" = { version = "openjdk-21", release_type = "ea" }
```

## Gradle toolchains detection

Gradle can automatically detect toolchains installed by some tools (see [toolchain | auto-detection](https://docs.gradle.org/current/userguide/toolchains.html#sec:auto_detection)).

At the moment, `Gradle` does not support auto-detecting Java installations by `mise` (see [gradle/issues/29508](https://github.com/gradle/gradle/issues/29508) and [gradle/issues/29355](https://github.com/gradle/gradle/issues/29355)). A workaround is to leverage the fact that `mise` install layout is [similar to the one used by `asdf`](/ide-integration.html#sdk-selection-using-asdf-layout).

```shell
mkdir -p ~/.asdf/installs/ && ln -s ~/.local/share/mise/installs/java ~/.asdf/installs/
```

Otherwise, you can always use the [foojay-resolver-convention](https://plugins.gradle.org/plugin/org.gradle.toolchains.foojay-resolver-convention) plugin to let Gradle automatically install JDKs required by your project.

---

---
url: /mise-cookbook/cpp.md
---
# Mise + C++ Cookbook

Here are some tips on managing C++ projects with mise.

## A C++ Project with CMake

```toml [mise.toml]
min_version = "2024.9.5"

[env]
# Project information
PROJECT_NAME = "{{ config_root | basename }}"

# Build directory
BUILD_DIR = "{{ config_root }}/build"

[tools]
# Install CMake and make
cmake = "latest"
make = "latest"

[tasks.configure]
description = "Configure the project"
run = "mkdir -p $BUILD_DIR && cd $BUILD_DIR && cmake .."

[tasks.build]
description = "Build the project"
alias = "b"
run = "cd $BUILD_DIR && make"

[tasks.clean]
description = "Clean the build directory"
alias = "c"
run = "rm -rf $BUILD_DIR"

[tasks.run]
alias = "r"
description = "Run the application"
run = "$BUILD_DIR/bin/$PROJECT_NAME"

[tasks.info]
description = "Print project information"
run = '''
echo "Project: $PROJECT_NAME"
echo "Build Directory: $BUILD_DIR"
'''
```

---

---
url: /mise-cookbook/docker.md
---
# Mise + Docker Cookbook

Here are some tips on using Docker with mise.

## Docker image with mise

Here is an example Dockerfile showing how to install mise in a Docker image.

```Dockerfile [Dockerfile]
FROM debian:12-slim

RUN apt-get update  \
    && apt-get -y --no-install-recommends install  \
        # install any other dependencies you might need
        sudo curl git ca-certificates build-essential \
    && rm -rf /var/lib/apt/lists/*

SHELL ["/bin/bash", "-o", "pipefail", "-c"]
ENV MISE_DATA_DIR="/mise"
ENV MISE_CONFIG_DIR="/mise"
ENV MISE_CACHE_DIR="/mise/cache"
ENV MISE_INSTALL_PATH="/usr/local/bin/mise"
ENV PATH="/mise/shims:$PATH"
# ENV MISE_VERSION="..."

RUN curl https://mise.run | sh
```

Build and run the Docker image:

```shell
docker build -t debian-mise .
docker run -it --rm debian-mise
```

## Task to run mise in a Docker container

This can be useful use if you need to reproduce an issue you're having with mise in a clean environment.

```toml [mise.toml]
[tasks.docker]
run = "docker run --pull=always -it --rm --entrypoint bash jdxcode/mise:latest"
```

Example usage:

```shell
❯ mise docker
[docker] $ docker run --pull=always -it --rm --entrypoint bash jdxcode/mise:latest
# latest: Pulling from jdxcode/mise
# Digest: sha256:eecc479b6259479ffca5a4f9c68dbfe8631ca62dc59aa60c9ab5e4f6e9982701
# Status: Image is up to date for jdxcode/mise:latest
root@75f179a190a1:/mise# eval "$(mise activate bash)"
# overwrite configuration and prune to give us a clean state
root@75f179a190a1:/mise# echo "" >/mise/config.toml
root@75f179a190a1:/mise# mise prune --yes
# mise pruned configuration links
# mise python@3.13.1 ✓ remove /mise/cache/python/3.13.1
# ...
```

---

---
url: /mise-cookbook/neovim.md
---
# Mise + Neovim Cookbook

Here are some tips for an improved mise workflow with [Neovim](https://github.com/neovim/neovim).

## Syntax highlighting

### Run commands

Use [Treesitter](https://github.com/nvim-treesitter/nvim-treesitter) to enable syntax highlighting for the code in the run commands of your mise files.
See the example here on the left side of the image:

![run cmd syntax highlighting demo](./run-cmd-syntax-hl.png)

In your neovim config, create a `after/queries/toml/injections.scm` file with these queries:

```query
; extends

(pair
  (bare_key) @key (#eq? @key "run")
  (string) @injection.content @injection.language

  (#is-mise?)
  (#match? @injection.language "^['\"]{3}\n*#!(/\\w+)+/env\\s+\\w+") ; multiline shebang using env
  (#gsub! @injection.language "^.*#!/.*/env%s+([^%s]+).*" "%1") ; extract lang
  (#offset! @injection.content 0 3 0 -3) ; rm quotes
)

(pair
  (bare_key) @key (#eq? @key "run")
  (string) @injection.content @injection.language

  (#is-mise?)
  (#match? @injection.language "^['\"]{3}\n*#!(/\\w+)+\s*\n") ; multiline shebang
  (#gsub! @injection.language "^.*#!/.*/([^/%s]+).*" "%1") ; extract lang
  (#offset! @injection.content 0 3 0 -3) ; rm quotes
)

(pair
  (bare_key) @key (#eq? @key "run")
  (string) @injection.content

  (#is-mise?)
  (#match? @injection.content "^['\"]{3}\n*.*") ; multiline
  (#not-match? @injection.content "^['\"]{3}\n*#!") ; no shebang
  (#offset! @injection.content 0 3 0 -3) ; rm quotes
  (#set! injection.language "bash") ; default to bash
)

(pair
  (bare_key) @key (#eq? @key "run")
  (string) @injection.content

  (#is-mise?)
  (#not-match? @injection.content "^['\"]{3}") ; not multiline
  (#offset! @injection.content 0 1 0 -1) ; rm quotes
  (#set! injection.language "bash") ; default to bash
)
```

To only apply the highlighting on mise files instead of all toml files, the `is-mise?` predicate is used.
If you don't care for this distinction, the lines containing `(#is-mise?)` can be removed.
Otherwise, make sure to also create the predicate somewhere in your neovim config.

For example, using [`lazy.nvim`](https://github.com/folke/lazy.nvim):

```lua
{
  "nvim-treesitter/nvim-treesitter",
  init = function()
    require("vim.treesitter.query").add_predicate("is-mise?", function(_, _, bufnr, _)
      local filepath = vim.api.nvim_buf_get_name(tonumber(bufnr) or 0)
      local filename = vim.fn.fnamemodify(filepath, ":t")
      return string.match(filename, ".*mise.*%.toml$") ~= nil
    end, { force = true, all = false })
  end,
},
```

This will consider any `toml` file containing `mise` in its name as a mise file.

### MISE and USAGE comments in file tasks

You can also use Treesitter to enable syntax highlighting for `"#MISE` and `#USAGE` comments in file based tasks.
See the example here on the left side of the image:

![USAGE spec syntax highlighting demo](./usage-spec-syntax-hl.png)

In your neovim config, create a `after/queries/bash/injections.scm` file with these queries:

```query
; extends

; ============================================================================
; #MISE comments - TOML injection
; ============================================================================
; This injection captures comment lines starting with "#MISE " or "#[MISE]" or
; "# [MISE]" and treats them as TOML code blocks for syntax highlighting.
;
; #MISE format
; The (#offset!) directive skips the "#MISE " prefix (6 characters) from the source
((comment) @injection.content
  (#lua-match? @injection.content "^#MISE ")
  (#offset! @injection.content 0 6 0 1)
  (#set! injection.language "toml"))

; #[MISE] format
((comment) @injection.content
  (#lua-match? @injection.content "^#%[MISE%] ")
  (#offset! @injection.content 0 8 0 1)
  (#set! injection.language "toml"))

; # [MISE] format
((comment) @injection.content
  (#lua-match? @injection.content "^# %[MISE%] ")
  (#offset! @injection.content 0 9 0 1)
  (#set! injection.language "toml"))

; ============================================================================
; #USAGE comments - KDL injection
; ============================================================================
; This injection captures consecutive comment lines starting with "#USAGE " or
; "#[USAGE]" or "# [USAGE]" and treats them as a single KDL code block for
; syntax highlighting.
;
; #USAGE format
((comment) @injection.content
  (#lua-match? @injection.content "^#USAGE ")
  ; Extend the range one byte to the right, to include the trailing newline.
  ; see https://github.com/neovim/neovim/discussions/36669#discussioncomment-15054154
  (#offset! @injection.content 0 7 0 1)
  (#set! injection.combined)
  (#set! injection.language "kdl"))

; #[USAGE] format
((comment) @injection.content
  (#lua-match? @injection.content "^#%[USAGE%] ")
  (#offset! @injection.content 0 9 0 1)
  (#set! injection.combined)
  (#set! injection.language "kdl"))

; # [USAGE] format
((comment) @injection.content
  (#lua-match? @injection.content "^# %[USAGE%] ")
  (#offset! @injection.content 0 10 0 1)
  (#set! injection.combined)
  (#set! injection.language "kdl"))

; NOTE: on neovim >= 0.12, you can use the multi node pattern instead of
; combining injections:
;
; ((comment)+ @injection.content
;   (#lua-match? @injection.content "^#USAGE ")
;   (#offset! @injection.content 0 7 0 1)
;   (#set! injection.language "kdl"))
;
; this is the preferred way as combined injections have multiple
; limitations:
; https://github.com/neovim/neovim/issues/32635

```

The same queries work as is for all languages that use `#` as a comment delimiter.
Due to TS injections being per language, you need to put the same queries to the language specific query files.
For example, put them to `after/queries/python/injections.scm` to enable them for `Python` in addition to `bash`.

For languages that use `//` as a comment delimiter, you need to modify the queries a bit:

```query
((comment) @injection.content
  (#lua-match? @injection.content "^//MISE ")
  (#offset! @injection.content 0 7 0 1)
  (#set! injection.language "toml"))
((comment) @injection.content
  (#lua-match? @injection.content "^//%[MISE%] ")
  (#offset! @injection.content 0 9 0 1)
  (#set! injection.language "toml"))
((comment) @injection.content
  (#lua-match? @injection.content "^// %[MISE%] ")
  (#offset! @injection.content 0 10 0 1)
  (#set! injection.language "toml"))
((comment) @injection.content
  (#lua-match? @injection.content "^//USAGE ")
  (#offset! @injection.content 0 8 0 1)
  (#set! injection.combined)
  (#set! injection.language "kdl"))
((comment) @injection.content
  (#lua-match? @injection.content "^//%[USAGE%] ")
  (#offset! @injection.content 0 10 0 1)
  (#set! injection.combined)
  (#set! injection.language "kdl"))
((comment) @injection.content
  (#lua-match? @injection.content "^// %[USAGE%] ")
  (#offset! @injection.content 0 11 0 1)
  (#set! injection.combined)
  (#set! injection.language "kdl"))
```

## Enable LSP for embedded lang in run commands

Use [`otter.nvim`](https://github.com/jmbuhr/otter.nvim) to enable LSP features and code completion for code embedded in your mise files.

Again using [`lazy.nvim`](https://github.com/folke/lazy.nvim):

```lua
{
  "jmbuhr/otter.nvim",
  dependencies = {
    "nvim-treesitter/nvim-treesitter",
  },
  config = function()
    vim.api.nvim_create_autocmd({ "FileType" }, {
      pattern = { "toml" },
      group = vim.api.nvim_create_augroup("EmbedToml", {}),
      callback = function()
        require("otter").activate()
      end,
    })
  end,
},
```

This will only work if the [TS injection queries](#run-commands) are also set up.

---

---
url: /mise-cookbook/nodejs.md
---
# Mise + Node.js Cookbook

Here are some tips on managing [Node.js](/lang/node.html) projects with mise.

## Getting started with Node.js

To install Node.JS, in a directory, you can use the following command:

```shell
mise use node
```

This will install the latest version of Node.js and create a `mise.toml` file with the following content:

```toml
node = "latest"
```

If you want to install Node.JS globally instead (for example, node v24), you can use the following command:

```shell
mise use -g node@24
```

## Add node modules binaries to the PATH

When installing Node.js packages specified in `package.json`, you typically need to use `npx` or the full path to the binary. For example:

```shell
npm install --save eslint
eslint --version # doesn't work
npx eslint --version # works
```

Thanks to `mise`, you can add the node modules binaries to the `PATH`. This will make CLIs installed with npm available without `npx`.

```toml [mise.toml]
[env]
_.path = ['{{config_root}}/node_modules/.bin']
```

Example:

```shell
npm install --save eslint
eslint --version # works
```

## Example Node.js Project

```toml [mise.toml]
min_version = "2024.9.5"

[env]
_.path = ['{{config_root}}/node_modules/.bin']

# Use the project name derived from the current directory
PROJECT_NAME = "{{ config_root | basename }}"

# Set up the path for node module binaries
BIN_PATH = "{{ config_root }}/node_modules/.bin"

NODE_ENV = "{{ env.NODE_ENV | default(value='development') }}"

[tools]
# Install Node.js using the specified version
node = "{{ env['NODE_VERSION'] | default(value='lts') }}"

# Install some npm packages globally if needed
"npm:typescript" = "latest"
"npm:eslint" = "latest"
"npm:jest" = "latest"

[tasks.install]
alias = "i"
description = "Install npm dependencies"
run = "npm install"

[tasks.start]
alias = "s"
description = "Start the development server"
run = "npm run start"

[tasks.lint]
alias = "l"
description = "Run ESLint"
run = "eslint src/"

[tasks.test]
description = "Run tests"
alias = "t"
run = "jest"

[tasks.build]
description = "Build the project"
alias = "b"
run = "npm run build"

[tasks.info]
description = "Print project information"
run = '''
echo "Project: $PROJECT_NAME"
echo "NODE_ENV: $NODE_ENV"
'''
```

## Example with `pnpm`

This example uses `pnpm` as the package manager. This will skip installing dependencies if the lock file hasn't changed.

```toml [mise.toml]
[tools]
node = '22'

[hooks]
# Enabling corepack will install the `pnpm` package manager specified in your package.json
# alternatively, you can also install `pnpm` with mise
postinstall = 'npx corepack enable'

[settings]
# This must be enabled to make the hooks work
experimental = true

[env]
_.path = ['{{config_root}}/node_modules/.bin']

[tasks.pnpm-install]
description = 'Installs dependencies with pnpm'
run = 'pnpm install'
sources = ['package.json', 'pnpm-lock.yaml', 'mise.toml']
outputs = ['node_modules/.pnpm/lock.yaml']

[tasks.dev]
description = 'Calls your dev script in `package.json`'
run = 'node --run dev'
depends = ['pnpm-install']
```

With this setup, getting started in a NodeJS project is as simple as running `mise dev`:

* `mise` will install the correct version of NodeJS
* `mise` will enable `corepack`
* `pnpm install` will be run before `node --run dev`

---

---
url: /mise-cookbook/python.md
---
# Mise + Python Cookbook

Here are some tips on managing [Python](/lang/python.html) projects with mise.

## A Python Project with virtualenv

Here is an example python project with a `requirements.txt` file.

```toml [mise.toml]
min_version = "2024.9.5"

[env]
# Use the project name derived from the current directory
PROJECT_NAME = "{{ config_root | basename }}"

# Automatic virtualenv activation
_.python.venv = { path = ".venv", create = true }

[tools]
python = "{{ get_env(name='PYTHON_VERSION', default='3.11') }}"
ruff = "latest"

[tasks.install]
description = "Install dependencies"
alias = "i"
run = "uv pip install -r requirements.txt"

[tasks.run]
description = "Run the application"
run = "python app.py"

[tasks.test]
description = "Run tests"
run = "pytest tests/"

[tasks.lint]
description = "Lint the code"
run = "ruff src/"

[tasks.info]
description = "Print project information"
run = '''
echo "Project: $PROJECT_NAME"
echo "Virtual Environment: $VIRTUAL_ENV"
'''
```

## mise + uv

If you are using a `uv` project initialized with `uv init .`, here is how you can use it with mise.

Here is how the `uv` project will look like:

```shell [uv-project]
.
├── .gitignore
├── .python-version
├── main.py
├── pyproject.toml
└── README.md

cat .python-version
# 3.12
```

If you run `uv run main.py` in the `uv` project, `uv` will automatically create a virtual environment for you using the python version specified in the `.python-version` file. This will also create a `uv.lock` file.

`mise` will detect the python version in `.python-version`, however, it won't use the virtual env created by `uv` by default. So, using `which python` will show a global python installation from `mise`.

```shell
mise i
which python
# ~/.local/share/mise/installs/python/3.12.4/bin/python
```

If you want `mise` to use the virtual environment created by `uv`, you can set the [`python.uv_venv_auto`](/lang/python.html#python.uv_venv_auto) setting in your `mise.toml` file.
Use `"source"` to only source an existing `.venv`, or `"create|source"` to create it if missing and then source it.
If you prefer `mise prepare` to create the venv, keep it at `"source"`, enable `[prepare.uv]`, and run `mise prepare`.

```toml [mise.toml]
[settings]
python.uv_venv_auto = "source"
# or, to create if missing
# python.uv_venv_auto = "create|source"
```

Using `which python` will now show the python version from the virtual environment created by `uv`.

```shell
which python
# ./uv-project/.venv/bin/python
```

Another option is to use `_.python.venv` in your `mise.toml` file to specify the path to the virtual environment created by `uv`.

```toml [mise.toml]
[env]
_.python.venv = { path = ".venv" }
```

### Syncing python versions installed by mise and uv

You can use [mise sync python --uv](/cli/sync/python.html#uv) to sync the python version installed by `mise` with the python version specified in the `.python-version` file in the `uv` project.

### uv scripts

You can take advantage of `uv run` in [`shebang`](/tasks/toml-tasks.html#shell-shebang) in toml or file tasks.
Note that using `--script` is required if the filename does not end in `.py`.

Here is an example toml task:

```toml [mise.toml]
[tools]
uv = 'latest'

[tasks.print_peps]
run = '''
#!/usr/bin/env -S uv run --script
# /// script
# dependencies = ["requests<3", "rich"]
# ///

import requests
from rich.pretty import pprint

resp = requests.get("https://peps.python.org/api/peps.json")
data = resp.json()
pprint([(k, v["title"]) for k, v in data.items()][:10])
'''
```

Or as a file task:

```python [mise-tasks/print_peps.py]
#!/usr/bin/env -S uv run --script
# /// script
# dependencies = ["requests<3", "rich"]
# ///

import requests
from rich.pretty import pprint

resp = requests.get("https://peps.python.org/api/peps.json")
data = resp.json()
pprint([(k, v["title"]) for k, v in data.items()][:10])
```

You can then run it with `mise run print_peps`:

```shell
❯ mise run print_peps
[print_peps] $ ~/uv-project/mise-tasks/print_peps.py
Installed 9 packages in 8ms
[
│   ('1', 'PEP Purpose and Guidelines'),
│   ('2', 'Procedure for Adding New Modules'),
    #...
]
```

---

---
url: /mise-cookbook/ruby.md
---
# Mise + Ruby Cookbook

Here are some tips on managing Ruby projects with mise.

## A Ruby on Rails Project

```toml [mise.toml]
min_version = "2024.9.5"

[env]
# Project information
PROJECT_NAME = "{{ config_root | basename }}"

[tools]
# Install Ruby with the specified version
ruby = "{{ get_env(name='RUBY_VERSION', default='3.3.3') }}"

[tasks."bundle:install"]
description = "Install gem dependencies"
run = "bundle install"

[tasks.server]
description = "Start the Rails server"
alias = "s"
run = "rails server"

[tasks.test]
description = "Run tests"
alias = "t"
run = "rails test"

[tasks.lint]
description = "Run lint using Rubocop"
alias = "l"
run = "rubocop"
```

---

---
url: /mise-cookbook/terraform.md
---
# Mise + Terraform/Opentofu Cookbook

Here are some tips on managing Terraform projects with mise.

## Managing `terraform`/`opentofu` Projects

It is often necessary to have your terraform configuration in a `terraform/` subdirectory.
This necessitates the use of syntax like `terraform -chdir=terraform plan` to use appropriate
terraform command. The following config allows you to invoke all of them from `mise`, leveraging
`mise` tasks.

```toml [mise.toml]
[tools]
terraform = "1"

[tasks."terraform:init"]
description = "Initializes a Terraform working directory"
run = "terraform -chdir=terraform init"

[tasks."terraform:plan"]
description = "Generates an execution plan for Terraform"
run = "terraform -chdir=terraform plan"

[tasks."terraform:apply"]
description = "Applies the changes required to reach the desired state of the configuration"
run = "terraform -chdir=terraform apply"

[tasks."terraform:destroy"]
description = "Destroy Terraform-managed infrastructure"
run = "terraform -chdir=terraform destroy"

[tasks."terraform:validate"]
description = "Validates the Terraform files"
run = "terraform -chdir=terraform validate"

[tasks."terraform:format"]
description = "Formats the Terraform files"
run = "terraform -chdir=terraform fmt"

[tasks."terraform:check"]
description = "Checks the Terraform files"
depends = ["terraform:format", "terraform:validate"]

[env]
_.file = ".env"

```

---

---
url: /architecture.md
---

# mise Architecture

This document provides a comprehensive overview of mise's architecture, designed primarily for contributors and those interested in understanding how mise works internally.

For practical development guidance, see the [Contributing Guide](contributing.md).

## System Overview

mise is a Rust-based tool with a modular architecture centered around three core concepts:

1. **Tool Version Management** - Installing and managing different versions of [development tools](dev-tools/)
2. **Environment Management** - Setting up [environment variables](environments/) and project contexts
3. **Task Running** - Executing [project tasks](tasks/) with dependency management

These three pillars work together to provide a unified development environment management experience.

## Core Architecture Components

### Command Layer ([`src/cli/`](https://github.com/jdx/mise/tree/main/src/cli/))

The CLI layer provides the user interface and delegates to core functionality:

* **Modular Commands**: Each command is a separate module ([`install.rs`](https://github.com/jdx/mise/blob/main/src/cli/install.rs), [`use.rs`](https://github.com/jdx/mise/blob/main/src/cli/use.rs), [`run.rs`](https://github.com/jdx/mise/blob/main/src/cli/run.rs), etc.)
* **Argument Parsing**: Leverages [`clap`](https://clap.rs) for robust CLI parsing and validation
* **Async Command Execution**: All commands support concurrent operations
* **Unified Error Handling**: Consistent error reporting across all commands

**Key Commands Architecture:**

* [`install`](cli/install.md) - Tool installation coordination
* [`use`](cli/use.md) - Tool activation and configuration management
* [`run`](cli/run.md) - Task execution with dependency resolution
* [`env`](cli/env.md) - Environment variable management
* [`shell`](cli/shell.md) - Shell integration and activation

### Backend System ([`src/backend/`](https://github.com/jdx/mise/tree/main/src/backend/))

The backend system is mise's core abstraction for tool management, implementing a trait-based architecture:

```rust
pub trait Backend: Debug + Send + Sync {
    async fn list_remote_versions(&self, config: &Arc<Config>) -> Result<Vec<String>>;
    async fn install_version(&self, ctx: &InstallContext, tv: ToolVersion) -> Result<ToolVersion>;
    async fn uninstall_version(&self, tv: &ToolVersion) -> Result<()>;
    // ... additional methods for lifecycle management
}
```

**Backend Categories:**

* **Core Backends**: Native Rust implementations for maximum performance
* **Language Package Managers**: npm, pipx, cargo, gem, go modules
* **Universal Installers**: github (GitHub releases), aqua (comprehensive package management)
* **Plugin Systems**: [backend plugins](backend-plugin-development.md) (enhanced methods), [tool plugins](tool-plugin-development.md) (hook-based), [asdf plugins](asdf-legacy-plugins.md) (legacy)

For guidance on implementing new backends, see the [Contributing Guide](contributing.md#adding-backends). For detailed backend system design, see [Backend Architecture](dev-tools/backend_architecture.md).

### Configuration System ([`src/config/`](https://github.com/jdx/mise/tree/main/src/config/))

A hierarchical configuration system that merges settings from multiple config files:

**Config Trait Architecture:**

```rust
pub trait ConfigFile: Debug + Send + Sync {
    fn get_path(&self) -> &Path;
    fn to_tool_request_set(&self) -> Result<ToolRequestSet>;
    fn env_entries(&self) -> Result<Vec<EnvDirective>>;
    fn tasks(&self) -> Vec<&Task>;
    // ... additional configuration methods
}
```

**Concrete Implementations:**

* `MiseToml` - Primary configuration format with full feature support
* `ToolVersions` - asdf compatibility layer
* `IdiomaticVersion` - Language-specific version files (`.node-version`, etc.)

**Configuration Hierarchy:** See [Configuration Documentation](configuration.md) for the complete hierarchy and precedence rules.

### Toolset Management ([`src/toolset/`](https://github.com/jdx/mise/tree/main/src/toolset/))

Coordinates tool resolution, installation, and environment setup:

**Core Components:**

* `Toolset` - Immutable collection of resolved tools for a context
* `ToolVersion` - Represents a specific, resolved tool version (e.g., `node@latest` becomes `node@18.17.0`)
* `ToolRequest` - User's tool specification (e.g., `node@18`, `python@latest`)
* `ToolsetBuilder` - Constructs toolsets from configuration with dependency resolution

**Tool Resolution Pipeline:**

1. **Configuration Parsing**: Extract tool requirements from config files
2. **Version Resolution**: Resolve version specifications (`latest`, `prefix:1.2`, `sub-1:latest`, etc.) to concrete versions
3. **Backend Selection**: Choose appropriate backend for each tool
4. **Dependency Analysis**: Resolve tool dependencies (e.g., npm requires Node.js)
5. **Installation Coordination**: Install missing tools in dependency order
6. **Environment Configuration**: Set up PATH and environment variables

### Task System ([`src/task/`](https://github.com/jdx/mise/tree/main/src/task/))

Sophisticated task execution with dependency graph management:

**Architecture Components:**

* `Task` - Task definition with metadata, dependencies, and execution configuration
* `Deps` - Dependency graph manager using `petgraph` for DAG operations
* `TaskFileProvider` - Discovers tasks from files and configuration
* Parallel execution engine with configurable concurrency

**Task Discovery:**

1. [File-based tasks](tasks/file-tasks.md) from configured directories
2. [TOML-defined tasks](tasks/toml-tasks.md) in configuration files
3. Inherited tasks from parent directories

**Dependency Resolution:**

* Uses directed acyclic graph (DAG) for dependency modeling
* Supports multiple dependency types: `depends`, `depends_post`, `wait_for`
* Parallel execution within dependency constraints
* Circular dependency detection and prevention

See the [Task Documentation](tasks/) for complete usage details and configuration options, and [Task Architecture](tasks/architecture.md) for detailed system design.

### Plugin System ([`src/plugins/`](https://github.com/jdx/mise/tree/main/src/plugins/))

Extensibility layer supporting multiple plugin architectures:

**Plugin Trait:**

```rust
pub trait Plugin: Debug + Send {
    fn name(&self) -> &str;
    fn path(&self) -> PathBuf;
    async fn install(&self, config: &Arc<Config>, pr: &dyn SingleReport) -> Result<()>;
    async fn update(&self, pr: &dyn SingleReport, gitref: Option<String>) -> Result<()>;
    // ... lifecycle management methods
}
```

**Plugin Types:**

* **Backend Plugins**: Enhanced plugins with backend methods for managing multiple tools
* **Tool Plugins**: Hook-based plugins using the traditional vfox format
* **asdf Plugins**: Legacy plugins compatible with the asdf plugin ecosystem (Linux/macOS only)

For complete plugin documentation, see [Plugin Guide](plugins.md).

### Shell Integration ([`src/shell/`](https://github.com/jdx/mise/tree/main/src/shell/))

Shell-specific code generation that abstracts commands like `mise env` and contains all shell differences in one place:

**Shell Trait:**

```rust
pub trait Shell: Display {
    fn activate(&self, opts: ActivateOptions) -> String;
    fn set_env(&self, k: &str, v: &str) -> String;
    fn unset_env(&self, k: &str) -> String;
    // ... shell-specific methods
}
```

**Supported Shells:** See [`mise activate`](cli/activate.md) documentation for the complete list
**Shell Abstractions:** Environment variable setting, PATH modification, command execution

### Environment Management ([`src/env*.rs`](https://github.com/jdx/mise/tree/main/src/))

Helpers for working with environment variables:

* `EnvDiff` - Tracks and applies environment changes
* `EnvDirective` - Configuration-based environment variable management
* `PathEnv` - Intelligent PATH manipulation with precedence rules
* Context-aware resolution with config layering

For environment setup and configuration, see [Environment Documentation](environments/).

### Caching System ([`src/cache.rs`](https://github.com/jdx/mise/blob/main/src/cache.rs))

Generic caching backed by files, using msgpack serialization with zstd compression:

* `CacheManager<T>` - Generic caching with TTL support
* Data serialized with msgpack and compressed with zstd for efficient storage
* Automatic cache invalidation based on file timestamps
* Per-backend cache isolation for data integrity

## Test Architecture

mise employs a multi-layered testing strategy that combines different testing approaches for thorough validation across its complex feature set.

**Testing Strategy Overview:**

1. **Unit Tests** - Rust `#[test]` functions embedded in source files
2. **End-to-End (E2E) Tests** - Bash-based integration tests with complete environment isolation
3. **Snapshot Tests** - Using `insta` crate for complex output validation

::: tip Testing Philosophy
**Most tests in mise are end-to-end tests, and this is generally the preferred approach** for new functionality. E2E tests provide thorough validation of real-world usage scenarios and catch integration issues that unit tests might miss. However, **E2E tests can be challenging to run locally** due to environment dependencies and setup complexity. For development and CI purposes, it's often easier to run tests on GitHub Actions where the environment is consistent and properly configured.

See the [Contributing Guide](contributing.md#testing) for detailed testing setup and guidelines.
:::

### Unit Tests ([`src/` modules](https://github.com/jdx/mise/tree/main/src/))

**Structure and Characteristics:**

* **Location**: Embedded within source files using `mod tests` blocks
* **Test Runner**: Standard Rust `cargo test`
* **Dependencies**: `pretty_assertions`, `insta`, `test-log`, `ctor`
* **Coverage**: ~50+ test modules covering all major functionality

```rust
mod tests {
    use insta::assert_snapshot;
    use pretty_assertions::assert_eq;
    use crate::config::Config;
    use super::*;

    #[tokio::test]
    async fn test_hash_to_str() {
        let _config = Config::get().await.unwrap();
        assert_eq!(hash_to_str(&"foo"), "e1b19adfb2e348a2");
    }
}
```

**Test Environment Setup:**

* **Global Setup**: Uses `ctor::ctor` in [`src/test.rs`](https://github.com/jdx/mise/blob/main/src/test.rs) for test environment initialization
* **Isolated Environment**: Each test gets a clean environment with custom `HOME`, cache, and config directories
* **Async Support**: Extensive use of `#[tokio::test]` for async testing

### End-to-End Tests ([`e2e/`](https://github.com/jdx/mise/tree/main/e2e/))

**Architecture:**

```
e2e/
├── run_test          # Single test executor with environment isolation
├── run_all_tests     # Test orchestrator with parallel execution
├── assert.sh         # Rich assertion library
├── cli/              # CLI command tests
│   ├── test_use      # Testing tool activation and configuration
│   ├── test_install  # Testing tool installation
│   ├── test_upgrade  # Testing tool upgrades
│   ├── test_uninstall # Testing tool removal
│   └── test_version  # Testing version commands
├── backend/          # Backend-specific tests
│   ├── test_aqua     # Testing aqua package manager
│   ├── test_asdf     # Testing asdf plugin compatibility
│   └── test_npm      # Testing npm backend
├── tasks/            # Task system tests
│   ├── test_task_deps # Testing task dependencies
│   ├── test_task_run_depends # Testing task execution order
│   ├── test_task_ls  # Testing task listing
│   └── test_task_info # Testing task metadata
├── config/           # Configuration tests
│   ├── test_config_ls # Testing configuration listing
│   └── test_config_set # Testing configuration updates
└── [other domains]/  # Additional test categories
```

**Environment Isolation System:**

Each test runs in complete isolation with temporary directories:

```bash
setup_isolated_env() {
  TEST_ISOLATED_DIR="$(mktemp --tmpdir --directory "$(basename "$TEST").XXXXXX")"
  TEST_HOME="$TEST_ISOLATED_DIR/home"
  MISE_DATA_DIR="$TEST_HOME/.local/share/mise"
  MISE_CACHE_DIR="$TEST_HOME/.cache/mise"
  # ... complete environment isolation
}
```

**Rich Assertion Framework:**

The [`assert.sh`](https://github.com/jdx/mise/blob/main/e2e/assert.sh) provides rich test utilities:

```bash
# Basic assertions
assert "command" "expected_output"
assert_contains "command" "substring"
assert_fail "command" "error_message"

# JSON testing
assert_json "command" '{"key": "value"}'
assert_json_partial_object "command" "field1,field2" '{"field1": "value1"}'

# File system assertions
assert_directory_exists "path"
assert_directory_empty "path"
```

**Test Categories:**

* **CLI Tests**: Validate all command-line interfaces and argument parsing
* **Backend Tests**: Test tool installation, version resolution, and backend integration
* **Task Tests**: Validate task execution, dependency resolution, and parallel execution
* **Configuration Tests**: Test configuration parsing, hierarchy, and environment variable handling

### Windows Testing

**Windows-Specific Tests ([`e2e-win/`](https://github.com/jdx/mise/tree/main/e2e-win/)):**

* **Language**: PowerShell scripts (`.ps1`)
* **Focus**: Windows-specific functionality and cross-platform compatibility
* **Coverage**: Core tools like Go, Java, Node.js, Python, Rust

```powershell
Describe "go" {
    It "installs go" {
        mise install go@latest
        go version | Should -Match "go version"
    }
}
```

### Snapshot Testing ([`src/snapshots/`](https://github.com/jdx/mise/tree/main/src/snapshots/))

**Implementation:**

* **Crate**: Uses `insta` for snapshot testing with 11 snapshot files
* **Format**: Stores expected outputs as `.snap` files
* **Coverage**: Complex outputs like directory listings, configuration parsing, environment diffs

```rust
#[tokio::test]
async fn test_parse() {
    let diff = DirenvDiff::parse(input).unwrap();
    assert_snapshot!(diff);  // Creates/validates snapshot
}
```

### Test Infrastructure Features

**Performance and Utility Tests ([`xtasks/test/`](https://github.com/jdx/mise/tree/main/xtasks/test/)):**

* **Performance Testing**: `perf` script for benchmarking
* **Coverage Testing**: `coverage` script for test coverage analysis
* **E2E Runner**: `e2e` script with filtering capabilities

**Test Data Management ([`test/`](https://github.com/jdx/mise/tree/main/test/)):**

```
test/
├── config/           # Test-specific configs
├── cwd/              # Test working directories
├── data/             # Test plugins and mock data
├── fixtures/         # Sample configuration files
├── plugins/          # Test plugin definitions
└── state/            # Test state directory
```

**Test Execution Modes:**

* **Fast Tests**: Regular tests that run in CI
* **Slow Tests**: Marked with `_slow` suffix, skipped unless `TEST_ALL=1`
* **Tranche Support**: Tests can be split across parallel runners using `TEST_TRANCHE_COUNT`

**Developer Experience Features:**

* **Environment Safety**: Complete isolation prevents tests from affecting user's actual mise installation
* **Parallel Execution**: E2E tests support parallel execution with proper isolation
* **Rich Reporting**: Detailed test timing, environment preservation on failure for debugging
* **Cross-Platform Validation**: Automated testing on multiple operating systems

**Running Tests:**

```bash
# Run all unit tests
cargo test

# Run all E2E tests
./e2e/run_all_tests

# Run specific E2E test
./e2e/run_test test_install

# Run with coverage
./xtasks/test/coverage

# Performance testing
./xtasks/test/perf
```

For complete development setup and testing procedures, see the [Contributing Guide](contributing.md).

This robust test architecture ensures mise's reliability across its complex feature set, including tool management, environment configuration, task execution, and multi-platform support.

## Related Architecture Documentation

For deeper understanding of specific subsystems:

* **[Task Architecture](tasks/architecture.md)** - Detailed design of the task dependency system, parallel execution engine, and task discovery mechanisms
* **[Backend Architecture](dev-tools/backend_architecture.md)** - In-depth guide to backend types, the trait system, and how different installation methods work

---

---
url: /README.md
---
# mise-docs

This repository contains the documentation website for the runtime executor [mise](https://github.com/jdx/mise). The website is powered by [VitePress](https://vitepress.dev/).

---

---
url: /dev-tools/mise-lock.md
---
# mise.lock Lockfile

`mise.lock` is a lockfile that pins exact versions and checksums of tools for reproducible environments. When enabled, mise will automatically maintain this file to ensure consistent tool versions across different machines and deployments.

## Overview

The lockfile serves similar purposes to `package-lock.json` in npm or `Cargo.lock` in Rust:

* **Reproducible builds**: Ensures everyone on your team uses exactly the same tool versions
* **Security**: Verifies tool integrity with checksums when supported by the backend
* **Version pinning**: Locks tools to specific versions while allowing flexibility in `mise.toml`
* **Avoids API rate limits**: By storing download URLs, future installs use the lockfile and do not need to call GitHub (or other providers), avoiding rate limits and the need for `GITHUB_TOKEN` in most cases

## Enabling Lockfiles

Lockfiles are controlled by the `lockfile` setting:

```sh
# Enable lockfiles globally
mise settings lockfile=true

# Or set in mise.toml
[settings]
lockfile = true
```

## How It Works

1. **Automatic Creation**: When you run `mise install` or `mise use`, mise updates `mise.lock` with the exact versions installed
2. **Version Resolution**: If a `mise.lock` exists, mise will prefer locked versions over version ranges in `mise.toml`
3. **Checksum Verification**: For supported backends, mise stores and verifies checksums of downloaded tools

## File Format

`mise.lock` is a TOML file with a platform-based format that organizes asset information by platform:

```toml
# Example mise.lock
[[tools.node]]
version = "20.11.0"
backend = "core:node"

[tools.node.platforms.linux-x64]
checksum = "sha256:a6c213b7a2c3b8b9c0aaf8d7f5b3a5c8d4e2f4a5b6c7d8e9f0a1b2c3d4e5f6a7"
size = 23456789
url = "https://nodejs.org/dist/v20.11.0/node-v20.11.0-linux-x64.tar.xz"

[[tools.python]]
version = "3.11.7"
backend = "core:python"

[tools.python.platforms.linux-x64]
checksum = "sha256:def456..."
size = 12345678

# Tool with backend-specific options
[[tools.ripgrep]]
version = "14.1.1"
backend = "aqua:BurntSushi/ripgrep"
options = { exe = "rg" }

[tools.ripgrep.platforms.linux-x64]
checksum = "sha256:4cf9f2741e6c465ffdb7c26f38056a59e2a2544b51f7cc128ef28337eeae4d8e"
size = 1234567

# Environment-specific version (only used when MISE_ENV=test)
[[tools.tiny]]
version = "2.1.0"
env = ["test"]
```

### Platform Information

Each platform in a tool's `[tools.name.platforms]` section uses a key format like `"os-arch"` (e.g., `"linux-x64"`, `"macos-arm64"`) and can contain:

* **`checksum`** (optional): SHA256 or Blake3 hash for integrity verification
* **`size`** (optional): File size in bytes for download validation
* **`url`** (optional): Original download URL for reference or re-downloading

### Tool Entry Fields

Each tool entry (`[[tools.name]]`) can contain:

* **`version`** (required): The exact version of the tool
* **`backend`** (optional): The backend used to install the tool (e.g., `core:node`, `aqua:BurntSushi/ripgrep`)
* **`options`** (optional): Backend-specific options that identify the artifact (e.g., `{exe = "rg", matching = "musl"}`)
* **`env`** (optional): List of environment names this version applies to (e.g., `["test", "staging"]`)
* **`platforms`** (optional): Platform-specific metadata (checksums, URLs, sizes)

### Platform Keys

The platform key format is generally `os-arch` but can be customized by backends:

* **Standard format**: `linux-x64`, `macos-arm64`, `windows-x64`
* **Backend-specific**: Some backends like Java may use more specific platform identifiers
* **Tool-specific**: Backends like `ubi` may include additional tool-specific information in the platform key

## Environment-Specific Versions

When using [environment-specific configuration files](/configuration/environments) (e.g., `mise.test.toml`), tools from those files are tagged with an `env` field in the lockfile:

```toml
# mise.test.toml
[tools]
tiny = "2"
```

When you run `MISE_ENV=test mise use tiny@2`, the lockfile will include:

```toml
[[tools.tiny]]
version = "2.1.0"
env = ["test"]
```

**Resolution priority**: When resolving versions, mise checks in order:

1. Entry with matching `env` for the current `MISE_ENV`
2. Base entry (no `env` field)
3. First available entry

This allows different environments to use different tool versions while sharing the same lockfile.

## Local Lockfiles

Tools defined in `mise.local.toml` (which is typically gitignored) use a separate `mise.local.lock` file. This keeps local tool configurations separate from the committed lockfile.

```sh
# mise.local.toml tools go to mise.local.lock
mise use --path mise.local.toml node@22

# Regular mise.toml tools go to mise.lock
mise use --path mise.toml node@20
```

Use `mise lock --local` to update the local lockfile for all platforms:

```sh
mise lock --local              # update mise.local.lock
mise lock --local node python  # update specific tools in mise.local.lock
```

## Strict Lockfile Mode

The `locked` setting enforces that all tools have pre-resolved URLs in the lockfile before installation. This prevents API calls to GitHub, aqua registry, etc., ensuring fully reproducible installations.

```sh
# Enable strict mode
mise settings locked=true

# Or via environment variable
MISE_LOCKED=1 mise install
```

When enabled, `mise install` will fail if a tool doesn't have a URL for the current platform in the lockfile. To fix this, first populate the lockfile with URLs:

```sh
mise lock                    # generate URLs for all platforms
mise lock --platform linux-x64,macos-arm64  # or specific platforms
```

This is useful for CI environments where you want to guarantee reproducible builds without any external API dependencies.

## Workflow

### Initial Setup

```sh
# Create the lockfile
touch mise.lock

# Install tools (this will populate the lockfile)
mise install
```

### Daily Usage

```sh
# Install exact versions from lockfile
mise install

# Update tools and lockfile
mise upgrade
```

### Updating Versions

When you want to update tool versions:

```sh
# Update tool version in mise.toml
mise use node@24

# This will update both the installation and mise.lock
```

## Backend Support

Backend support for lockfile features varies:

* ✅ **Full support** (version + checksum + size + URL): `aqua`, `http`, `github`, `gitlab`
* ⚠️ **Partial support** (version + checksum + size): `ubi`
* 📝 **Basic support** (version + checksum): `core` (some tools)
* 📝 **Version only**: `asdf`, `npm`, `cargo`, `pipx`
* 📝 **Planned**: More backends will add full asset tracking support over time

## Best Practices

### Version Control

```sh
# Always commit the lockfile
git add mise.lock
git commit -m "Update tool versions"
```

### Team Workflow

1. **Team Lead**: Updates `mise.toml` with new version ranges
2. **Team Lead**: Runs `mise install` to update `mise.lock`
3. **Team Lead**: Commits both files
4. **Team Members**: Pull changes and run `mise install` to get exact versions

### CI/CD

```yaml
# Example GitHub Actions
- name: Install tools
  run: |
    mise install  # Uses exact versions from mise.lock

- name: Cache lockfile
  uses: actions/cache@v5
  with:
    key: mise-lock-${{ hashFiles('mise.lock') }}
```

## Troubleshooting

### Regenerating Checksums

If checksums become invalid or you need to regenerate them:

```sh
# Remove all tools and reinstall
mise uninstall --all
mise install
```

### Lockfile Conflicts

When merging branches with different lockfiles:

1. Resolve conflicts in `mise.lock`
2. Run `mise install` to verify everything works
3. Commit the resolved lockfile

### Disabling for Specific Projects

```toml
# In project's mise.toml
[settings]
lockfile = false
```

## Migration from Other Tools

### From asdf

```sh
# Convert .tool-versions to mise.toml
mise config generate

# Enable lockfiles and populate
mise settings lockfile=true
mise install
```

### From package.json engines

```sh
# Set versions based on package.json
mise use node@$(jq -r '.engines.node' package.json)
```

## See Also

* [Configuration Settings](/configuration/settings) - All available settings
* [Tool Version Management](/dev-tools/) - How tool versions work
* [Backends](/dev-tools/backends/) - Backend-specific checksum support

---

---
url: /mcp.md
---
# Model Context Protocol (MCP)

The Model Context Protocol (MCP) is a standard protocol that enables AI assistants to interact with development tools and access project context. Mise provides an MCP server that allows AI assistants to query information about your development environment.

## Overview

When you run `mise mcp`, it starts a server that AI assistants can connect to and query information about your mise-managed development environment. The server communicates over stdin/stdout using JSON-RPC protocol.

::: warning
The MCP feature is experimental and requires enabling experimental features with `MISE_EXPERIMENTAL=1`.
:::

## Usage

The MCP server is typically launched by AI assistants automatically, but you can also run it manually for testing:

```bash
# Enable experimental features
export MISE_EXPERIMENTAL=1

# Start the MCP server (it will wait for JSON-RPC input on stdin)
mise mcp
```

## Available Resources

The MCP server exposes the following read-only resources that AI assistants can query:

### `mise://tools`

Lists all tools managed by mise in your project, including:

* Tool names and versions
* Installation status
* Configuration source

### `mise://tasks`

Shows all available mise tasks with:

* Task names and descriptions
* Task dependencies
* Command definitions

### `mise://env`

Displays environment variables defined in your mise configuration:

* Variable names and values
* Environment-specific overrides

### `mise://config`

Provides information about mise configuration:

* Active configuration files
* Project root directory
* Settings and preferences

## Available Tools

The following tools are available for AI assistants to call:

### `install_tool`

Install a specific tool version (not yet implemented)

### `run_task`

Execute a mise task with optional arguments.

**Parameters:**

* `task` (required, string): Name of the task to run
* `args` (optional, array of strings): Arguments to pass to the task

**Example:**

```json
{
  "task": "build",
  "args": ["--verbose"]
}
```

When the AI assistant calls this tool, it will execute the specified task and return the output, including stdout, stderr, and the exit status.

## Integration with AI Assistants

### Claude Desktop

To use mise with Claude Desktop, add the following to your Claude configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**Linux**: `~/.config/claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "mise": {
      "command": "mise",
      "args": ["mcp"],
      "env": {
        "MISE_EXPERIMENTAL": "1"
      }
    }
  }
}
```

After adding this configuration and restarting Claude Desktop, the assistant will be able to:

* Query your installed tools and versions
* List available tasks in your project
* Execute tasks directly (e.g., "run the build task")
* Access environment variables from your mise configuration
* View your mise configuration structure

### Other AI Assistants

The MCP server uses standard JSON-RPC 2.0 over stdio, making it compatible with any AI assistant that supports the Model Context Protocol. Consult your AI assistant's documentation for specific integration instructions.

## Examples

When integrated with an AI assistant, you can ask questions like:

* "What version of Node.js is this project using?"
* "List all the tasks available in this project"
* "Run the build task"
* "Execute the test task with verbose output"
* "What environment variables are set by mise?"
* "Show me the mise configuration for this project"

The AI assistant will query the MCP server to provide accurate, up-to-date information about your development environment and can execute tasks on your behalf.

## Technical Details

The MCP server implementation can be found in [`src/cli/mcp.rs`](https://github.com/jdx/mise/blob/main/src/cli/mcp.rs). It implements the ServerHandler trait from the rmcp crate to handle:

* Resource listing and reading
* Tool invocation (task execution)
* JSON-RPC communication over stdio

For more information about the Model Context Protocol, visit the [official MCP documentation](https://modelcontextprotocol.io/).

---

---
url: /tasks/monorepo.md
---
# Monorepo Tasks&#x20;

mise supports monorepo-style task organization with target path syntax. This feature allows you to manage tasks across multiple projects in a single repository, where each project can have its own `mise.toml` configuration with tools, environment variables, and tasks that may be different from where the task is called from.

## Overview

When `experimental_monorepo_root` is enabled in your root `mise.toml`, mise will automatically discover tasks in subdirectories and prefix them with their relative path from the monorepo root. This creates a unified task namespace across your entire repository.

::: tip
The directory containing a `mise.toml` file is called the **config\_root**. In monorepo mode, each project can have its own config\_root with its own configuration, separate from the monorepo root. Note that if you use one of the alternate paths in a subdirectory like `./projects/frontend/.mise/config.toml`, the config\_root will be `./projects/frontend`–not `./projects/frontend/.mise`.
:::

### Benefits

* **Consistent execution**: Run tasks from any location in the monorepo using the mise config that would be set if called from the task's directory
* **Clear task namespacing**: Tasks are prefixed with their location from the monorepo root
* **Pattern-based execution**: Use wildcards to run tasks across multiple projects
* **Tool and environment layering**: Subdirectory tasks use tools and environment variables from parent configs, but can also define their own in their config\_root
* **Automatic trust propagation**: When the monorepo root is trusted, all descendant configs are automatically trusted

## Configuration

### Enabling Monorepo Mode

Add `experimental_monorepo_root = true` to your root `mise.toml`:

```toml
# /myproject/mise.toml
experimental_monorepo_root = true

[tools]
# Tools defined here apply to all subdirectories
node = "20"
```

::: warning
This feature requires `MISE_EXPERIMENTAL=1` environment variable.
:::

### Example Structure

```
myproject/
├── mise.toml (with experimental_monorepo_root = true)
├── projects/
│   ├── frontend/
│   │   └── mise.toml (with tasks: build, test)
│   └── backend/
│       └── mise.toml (with tasks: build, test)
```

With this structure, tasks will be automatically namespaced:

* `//projects/frontend:build`
* `//projects/frontend:test`
* `//projects/backend:build`
* `//projects/backend:test`

## Task Path Syntax

Monorepo tasks use special path syntax with `//` and `:` prefixes. You can run these tasks directly with `mise` or with `mise run`. With non-monorepo tasks, the guidance is to avoid using the direct syntax for scripts because it could conflict with future core mise commands. However, mise will never define commands with a `//` or `:` prefix, so this guidance does not apply to monorepo tasks.

```bash
# Direct syntax (preferred for monorepo tasks)
mise //projects/frontend:build

# Also works with 'run'
mise run //projects/frontend:build

# Need quotes for wildcards
mise '//projects/frontend:*'
```

### Absolute Paths

Use `//` prefix to specify the absolute path from the monorepo root:

```bash
# Run build task in frontend project
mise //projects/frontend:build

# Run test task in backend project
mise //projects/backend:test
```

### Current config\_root Tasks

Use `:` prefix to run tasks in the current config\_root:

```bash
cd projects/frontend
mise :build  # Runs the build task from frontend's config_root
```

::: tip Optional Colon Syntax
The leading `:` is optional when running tasks from subdirectories or defining task dependencies. While both syntaxes work, **we encourage using the `:` prefix to be explicit** about monorepo task references.

**Running from subdirectory:**

```bash
cd projects/frontend
mise :build      # Recommended: Explicit monorepo task reference
mise build       # Also works (for migration compatibility)
```

**Task dependencies:**

```toml
# projects/frontend/mise.toml
[tasks.lint]
run = "eslint ."

[tasks.build]
depends = [":lint"]  # Recommended: Explicit and clear
# OR
depends = ["lint"]   # Also works (for migration compatibility)
run = "webpack build"
```

The bare name syntax (without `:`) is supported primarily to ease migration from non-monorepo to monorepo configurations. When migrating, you won't need to update all your task dependencies immediately - they'll continue to work. However, using the `:` prefix makes it clear you're referencing a task in the current config\_root.
:::

### Wildcard Patterns

mise supports two types of wildcards for flexible task execution:

#### Path Wildcards (`...`)

Use ellipsis (`...`) to match any directory depth:

```bash
# Run 'test' task in ALL projects (any depth)
mise //...:test

# Run 'build' in all subdirs under projects/
mise //projects/...:build

# Match paths with wildcards in the middle
mise //projects/.../api:build  # Matches projects/*/api and projects/*/*/api
```

::: info
Additional glob patterns may be added in a future version so `mise //projects/*:build`
and `mise '//projects/**:build'` will likely be supported. We're using `...` because it matches
how bazel and buck2 do it.
:::

#### Task Name Wildcards (`*`)

Use asterisk (`*`) to match task names:

```bash
# Run ALL tasks in frontend project
mise '//projects/frontend:*'

# Run all tasks starting with 'test:'
mise '//projects/frontend:test:*'

# Run 'lint' task across all projects
mise //...:lint
```

### Combining Wildcards

You can combine both types of wildcards for powerful patterns:

```bash
# Run all tasks in all projects (idk why you'd ever want to do this, but you can)
mise '//...:*'

# Run all test tasks in all projects
mise '//...:test*'

# Run build tasks in all frontend-related projects
mise //.../frontend:build
```

## Tool, Environment, and Vars Layering

Subdirectory tasks automatically use tools and environment variables from parent config files in the hierarchy. However, each subdirectory can also define its own tools and environment variables in its config\_root. This allows you to:

1. Define common tools and environment at the monorepo root
2. Override tools or environment in specific subdirectories
3. Add additional tools or environment in subdirectories

`vars` follow the same hierarchy for task templating, so child config vars are available when
running subdirectory tasks from the monorepo root.

### Layering Example

```toml
# /myproject/mise.toml
experimental_monorepo_root = true

[tools]
node = "20"      # Available to all subdirectories
python = "3.12"  # Available to all subdirectories

[env]
LOG_LEVEL = "info"  # Available to all subdirectories
```

```toml
# /myproject/projects/frontend/mise.toml
[tools]
node = "18"  # Overrides the root's node 20

[env]
LOG_LEVEL = "debug"  # Overrides the root's LOG_LEVEL
PORT = "3000"        # Adds new environment variable

[tasks.build]
run = "npm run build"  # Uses node 18 and LOG_LEVEL=debug
```

```toml
# /myproject/projects/backend/mise.toml
# No tools or env section - uses node 20, python 3.12, and LOG_LEVEL=info from root

[tasks.build]
run = "npm run build"  # Uses node 20 and LOG_LEVEL=info from root
```

### Layering Rules

1. **Base toolset and environment**: Tasks start with tools and environment from all global config files (including parent configs in the hierarchy)
2. **Subdirectory override**: Tools and environment defined in the subdirectory's config file are merged on top, allowing overrides
3. **Task-specific tools and environment**: Values defined in the task's `tools` and `env` properties take highest precedence

## Config Roots

You must explicitly list your config roots using the `[monorepo]` section:

```toml
# /myproject/mise.toml
experimental_monorepo_root = true

[monorepo]
config_roots = [
    "packages/frontend",
    "packages/backend",
    "services/*",          # Single-level glob pattern
]
```

This tells mise exactly which directories contain project configurations. Benefits:

* **Fast discovery**: No filesystem walking needed
* **Explicit control**: Only the projects you list are included
* **Glob support**: Use `*` for single-level patterns (e.g., `services/*` matches `services/api`, `services/worker`)

::: tip
Single-level globs (`*`) are supported, but recursive globs (`**`) are not. This ensures predictable performance while still allowing flexible patterns.
:::

::: warning Automatic Discovery Deprecated
Automatic filesystem walking to discover monorepo subdirectories is deprecated. If you don't define `[monorepo].config_roots`, mise will still walk the filesystem but will emit a deprecation warning. Please migrate to explicit config roots.
:::

## Listing Tasks

The difference between `mise tasks` and `mise tasks --all`:

* **`mise tasks`**: Lists tasks from the current config\_root hierarchy (current config\_root and its parents)
* **`mise tasks --all`**: Lists tasks from the entire monorepo, including sibling and descendant directories

### Listing Example

Given this structure:

```
myproject/
├── mise.toml (task: deploy)
├── projects/
│   ├── frontend/
│   │   └── mise.toml (tasks: build, test)
│   └── backend/
│       └── mise.toml (tasks: build, serve)
```

When in `projects/frontend/`:

```bash
# Lists: //:deploy, //projects/frontend:build, //projects/frontend:test
mise tasks

# Lists: //:deploy, //projects/frontend:build, //projects/frontend:test,
#        //projects/backend:build, //projects/backend:serve
mise tasks --all
```

### View Specific Project Tasks

```bash
# List all tasks in frontend project
mise tasks '//projects/frontend:*'
```

## Best Practices

### 1. Define Shared Tools and Environment at Root

Place commonly-used tools and environment in the root `mise.toml` to avoid repetition:

```toml
# /myproject/mise.toml
experimental_monorepo_root = true

[tools]
node = "20"
python = "3.12"
go = "1.21"

[env]
NODE_ENV = "development"
```

### 2. Override Only When Necessary

Only override tools in subdirectories when they genuinely need different versions:

```toml
# /myproject/legacy-app/mise.toml
[tools]
node = "14"  # Override only for legacy app
# python and go from root
```

### 3. Use Descriptive Task Names

Prefix related tasks with common names to enable pattern matching:

```toml
[tasks.test]
run = "npm test"

[tasks."test:unit"]
run = "npm run test:unit"

[tasks."test:e2e"]
run = "npm run test:e2e"
```

Then run all test tasks: `mise '//...:test*'`

### 4. Group Related Projects

Organize projects in subdirectories to enable targeted execution:

```
myproject/
├── services/
│   ├── api/
│   ├── worker/
│   └── scheduler/
└── apps/
    ├── web/
    └── mobile/
```

Then run tasks by group:

```bash
mise //services/...:build  # Build all services
mise //apps/...:test       # Test all apps
```

## Comparison to Other Tools

The monorepo ecosystem offers many excellent tools, each with different strengths. Here's how mise's Monorepo Tasks compares:

### Simple Task Runners

**Taskfile** and **Just** are fantastic for single-project task automation. They're lightweight and easy to set up, but they weren't designed with monorepos in mind. While you can have multiple Taskfiles/Justfiles in a repo, they don't provide unified task discovery, cross-project wildcards, or automatic tool/environment layering across projects.

**mise's advantage:** Automatic task discovery across the entire monorepo with a unified namespace and powerful wildcard patterns.

### JavaScript-Focused Tools

**Nx**, **Turborepo**, and **Lerna** are powerful tools specifically designed for JavaScript/TypeScript monorepos.

* **Nx** offers incredible features like dependency graph visualization, affected project detection, code generation, and computation caching. It has a massive plugin ecosystem and excels at frontend monorepos.
* **Turborepo** focuses on blazing-fast task caching and parallel execution with minimal configuration.
* **Lerna** pioneered JavaScript monorepo management with package versioning and publishing workflows.

**mise's advantage:** Language-agnostic support. While these tools excel in JS/TS ecosystems, mise works equally well with Rust, Go, Python, Ruby, or any mix of languages. You also get unified tool version management (not just tasks) and environment variables across your entire stack.

### Large-Scale Build Systems

**Bazel** (Google) and **Buck2** (Meta) are industrial-strength build systems designed for massive, multi-language monorepos at companies with thousands of engineers.

* **Bazel** offers incredible features like distributed caching, remote execution, and hermetic builds with fine-grained dependency tracking.
* **Buck2** is a modern rewrite with a clean architecture and impressive performance optimizations.

Both are extremely powerful but come with significant complexity:

* Hermetic builds require strict isolation and complete dependency control
* Steep learning curve with specialized DSLs (Starlark, etc.)
* Complex configuration requiring dedicated build engineers
* Heavy investment in infrastructure for remote caching
* Stricter constraints on how you structure your code

**mise's advantage:** Simplicity through non-hermetic builds. mise doesn't try to control your entire build environment in isolation - instead, it manages tools and tasks in a flexible, practical way. This "non-hermetic" approach means you can use mise without restructuring your entire codebase or learning a new language. You get powerful monorepo task management with simple TOML configuration - enough power for most teams without the enterprise-level complexity that hermetic builds require.

### Other Notable Tools

**Rush** (Microsoft) offers strict dependency management and build orchestration for JavaScript monorepos, with a focus on safety and convention adherence.

**Moon** is a newer Rust-based build system that aims to be developer-friendly while supporting multiple languages.

### The mise Sweet Spot

mise's Monorepo Tasks aims to hit the sweet spot between simplicity and power:

| Feature                 | Simple Runners | JS-Focused | Build Systems | mise |
| ----------------------- | -------------- | ---------- | ------------- | ---- |
| Multi-language support  | ✅             | ❌         | ✅            | ✅   |
| Easy to learn           | ✅             | ⚠️         | ❌            | ✅   |
| Unified task discovery  | ❌             | ✅         | ✅            | ✅   |
| Wildcard patterns       | ❌             | ⚠️         | ✅            | ✅   |
| Tool version management | ❌             | ❌         | ⚠️            | ✅   |
| Environment layering    | ❌             | ⚠️         | ❌            | ✅   |
| Minimal setup           | ✅             | ⚠️         | ❌            | ✅   |
| Task caching            | ❌             | ✅         | ✅            | ❌   |

**When to choose mise:**

* ✅ Polyglot monorepos (multiple languages)
* ✅ You want unified tool + task management
* ✅ You prefer simplicity over maximum performance
* ✅ You're already using mise for tool management

**When to consider alternatives:**

* You're exclusively JavaScript/TypeScript → Nx or Turborepo might offer more JS-specific features
* You're at Google/Meta scale with thousands of engineers → Bazel or Buck2 offer distributed build infrastructure
* You need advanced task caching → Nx, Turborepo, or Bazel offer sophisticated caching systems

The best tool is the one that fits your team's needs. mise's Monorepo Tasks is designed for teams who want powerful monorepo management without the complexity overhead, especially when working across multiple languages.

## Task Templates

For monorepos with similar task patterns across projects, [task templates](/tasks/templates) allow you to define reusable task definitions at the monorepo root:

```toml
# Root mise.toml
[settings]
experimental = true
experimental_monorepo_root = true

[task_templates."python:build"]
run = "uv build"
tools = { python = "3.12", uv = "latest" }

[task_templates."python:test"]
run = "pytest"
tools = { python = "3.12" }
depends = ["build"]
```

Projects can then extend these templates:

```toml
# packages/api/mise.toml
[tasks.build]
extends = "python:build"

[tasks.test]
extends = "python:test"
run = "pytest --cov"  # Override with coverage
```

See [Task Templates](/tasks/templates) for complete documentation.

## Related

* [Task Templates](/tasks/templates) - Reusable task definitions
* [Task Configuration](/tasks/task-configuration) - All task configuration options
* [Running Tasks](/tasks/running-tasks) - How to execute tasks
* [Configuration](/configuration) - General mise configuration

---

---
url: /lang/node.md
---
# Node

Like `nvm`, (or `volta`, `fnm` or `asdf`...), `mise` can manage multiple versions of Node.js on the same system.

> The following are instructions for using the node mise core plugin. This is used when there isn't a
> git plugin installed named "node".
> If you want to use [asdf-nodejs](https://github.com/asdf-vm/asdf-nodejs)
> then run `mise plugins install node https://github.com/asdf-vm/asdf-nodejs`

The code for this is inside the mise repository at [`./src/plugins/core/node.rs`](https://github.com/jdx/mise/blob/main/src/plugins/core/node.rs).

## Usage

The following installs the latest version of node-20.x and makes it the global
default:

```sh
mise use -g node@20
```

See the [Node.JS Cookbook](/mise-cookbook/nodejs.html) for common tasks and examples.

## `.nvmrc` and `.node-version` support

By default, mise uses a `mise.toml` file for auto-switching between software versions.

It also supports `.tool-versions`, `.nvmrc` or `.node-version` file to find out what version of Node.js should be used. This will be used if `node` isn't defined in `mise.toml`.

This makes it a drop-in replacement for `nvm`. See [idiomatic version files](/configuration.html#idiomatic-version-files) for more information.

## Default node packages

mise-node can automatically install a default set of npm packages right after installing a node version. To enable this feature, provide a `$HOME/.default-npm-packages` file that lists one package per line, for example:

```text
lodash
request
express
```

You can specify a non-default location of this file by setting a `MISE_NODE_DEFAULT_PACKAGES_FILE` variable.

## "nodejs" -> "node" Alias

You cannot install/use a plugin named "nodejs". If you attempt this, mise will just rename it to
"node". See the [FAQ](/faq.html#what-is-the-difference-between-nodejs-and-node-or-golang-and-go)
for an explanation.

## Building from source

If compiling from source, see [BUILDING.md](https://github.com/nodejs/node/blob/main/BUILDING.md#building-nodejs-on-supported-platforms) in node's documentation for
required system dependencies.

```shell
mise settings node.compile=1
mise use node@latest
```

## Unofficial Builds

Nodejs.org offers a set of [unofficial builds](https://unofficial-builds.nodejs.org/) which are
compatible with some platforms that are not supported by the official binaries. These are a nice alternative to
compiling from source for these platforms.

To use, first set the mirror url to point to the unofficial builds:

```sh
mise settings node.mirror_url=https://unofficial-builds.nodejs.org/download/release/
```

If your goal is to simply support an alternative arch/os like linux-loong64 or linux-armv6l, this is
all that is required. Node also provides flavors such as musl or glibc-217 (an older glibc version
than what the official binaries are built with).

To use these, set `node.flavor`:

```sh
mise settings node.flavor=musl
mise settings node.flavor=glibc-217
```

## Settings

---

---
url: /dev-tools/backends/npm.md
---
# npm Backend

You may install packages directly from [npmjs.org](https://npmjs.org/) even if there
isn't an asdf plugin for it.

The code for this is inside of the mise repository at [`./src/backend/npm.rs`](https://github.com/jdx/mise/blob/main/src/backend/npm.rs).

## Dependencies

This relies on having `npm` installed for resolving package versions.
If you use `bun` or `pnpm` as the package manager, they must also be installed.

Here is how to install `npm` with mise:

```sh
mise use -g node
```

To install `bun` or `pnpm`:

```sh
mise use -g bun
# or
mise use -g pnpm
```

## Usage

The following installs the latest version of [prettier](https://www.npmjs.com/package/prettier)
and sets it as the active version on PATH:

```sh
$ mise use -g npm:prettier
$ prettier --version
3.1.0
```

The version will be set in `~/.config/mise/config.toml` with the following format:

```toml
[tools]
"npm:prettier" = "latest"
```

## Settings

Set these with `mise settings set [VARIABLE] [VALUE]` or by setting the environment variable listed.

---

---
url: /paranoid.md
---
# Paranoid

Paranoid is an optional behavior that locks mise down more to make it harder
for a bad actor to compromise your system. These are settings that I
personally do not use on my own system because I find the behavior too
restrictive for the benefits.

Paranoid mode can be enabled with either `MISE_PARANOID=1` or a setting:

```sh
mise settings paranoid=1
```

## Config files

Normally `mise` will make sure some config files are "trusted" before loading
them. This will prompt you to confirm that you want to load the file, e.g.:

```sh
$ mise install
mise ~/src/mise/.tool-versions is not trusted. Trust it [y/n]?
```

Generally only potentially dangerous config files are checked such as files
that use templates (which can execute arbitrary code) or that set env vars.
Under paranoid, however, all config files must be trusted first.

Also, in normal mode, a config file only needs to be trusted a single time.
In paranoid, the contents of the file are hashed to check if the file changes.
If you change your config file, you'll need to trust it again.

Note that global and system config files (e.g., `~/.config/mise/config.toml`) are implicitly trusted and exempt from this check. This allows paranoid mode to be enabled in a global config without requiring a trust prompt for that file itself.

## Community plugins

Community plugins can not be directly installed via short-name under paranoid.
You can install plugins that are either core, maintained by the mise team,
or plugins that mise has marked as "first-party"—meaning plugins developed by
the same team that builds the tool the plugin installs.

Other than that, say for "shfmt", you'll need to specify the full git repo
to install:

```sh
mise plugin install shfmt https://github.com/luizm/asdf-shfmt
```

Unlike in normal mode where `mise plugin install shfmt` would be sufficient.

## Always uses HTTPS

Some endpoints in mise are fetched over HTTP such as checking for the latest mise
version and pulling version lists of tools. These are not security risks and a
malicious actor injecting false data would not introduce a security risk.
Normally mise uses HTTP because loading the TLS module takes about 10ms and this
affects commonly used commands so it is a noticeably delay.
In paranoid mode, all endpoints will be fetched over HTTPS.

## More?

If you have suggestions for more that could be added to paranoid, please let
me know.

---

---
url: /dev-tools/backends/pipx.md
---
# pipx Backend

pipx is a tool for running Python CLIs in isolated virtualenvs. This is necessary for Python CLIs
because it prevents conflicting dependencies between CLIs or between a CLI and Python projects. In essence,
this backend lets you add Python CLIs to mise.

To be clear, pipx is not pip and it's not used to manage Python dependencies generally.
mise is a tool manager, not a dependency manager like pip, uv, or poetry. You can, however, use mise to install said package
managers. You'd want to use the pipx backend to install a CLI like "black", not a library like "NumPy" or "requests".

Somewhat confusingly, the pipx backend will actually default to using [`uvx`](https://docs.astral.sh/uv/guides/tools/) (the equivalent of pipx for uv)
if uv is installed. This should just mean that it installs much faster, but see below to disable or configure
since occasionally tools don't work with uvx.

The pipx backend supports the following sources:

* PyPI
* Git
* GitHub
* Http

The code for this is inside of the mise repository at [`./src/backend/pipx.rs`](https://github.com/jdx/mise/blob/main/src/backend/pipx.rs).

## Dependencies

This relies on having `uv` (recommended) or `pipx` installed.

If you have `uv` installed, mise will use `uv tool install` under the hood and you don't need to install `pipx` to run the commands containing "pipx:".

In case you need `pipx` for other reasons, you can install it with or without mise.
Here is how to install `pipx` with mise:

```sh
mise use -g python
pip install --user pipx
```

[Other installation instructions](https://pipx.pypa.io/latest/installation/)

## Usage

The following installs the latest version of [black](https://github.com/psf/black)
and sets it as the active version on PATH:

```sh
$ mise use -g pipx:psf/black
$ black --version
black, 24.3.0
```

The version will be set in `~/.config/mise/config.toml` with the following format:

```toml
[tools]
"pipx:psf/black" = "latest"
```

## Python upgrades

If the python version used by a pipx package changes, (by mise or system python), you may need to
reinstall the package. This can be done with:

```sh
mise install -f pipx:psf/black
```

Or you can reinstall all pipx packages with:

```sh
mise install -f "pipx:*"
```

mise *should* do this automatically when using `mise up python`.

### Supported Pipx Syntax

| Description                           | Usage                                                  |
| ------------------------------------- | ------------------------------------------------------ |
| PyPI shorthand latest version         | `pipx:black`                                           |
| PyPI shorthand for specific version   | `pipx:black@24.3.0`                                    |
| GitHub shorthand for latest version   | `pipx:psf/black`                                       |
| GitHub shorthand for specific version | `pipx:psf/black@24.3.0`                                |
| Git syntax for latest version         | `pipx:git+https://github.com/psf/black.git`            |
| Git syntax for a branch               | `pipx:git+https://github.com/psf/black.git@main`       |
| Https with zipfile                    | `pipx:https://github.com/psf/black/archive/18.9b0.zip` |

Other syntax may work but is unsupported and untested.

## Settings

Set these with `mise settings set [VARIABLE] [VALUE]` or by setting the environment variable listed.

## Tool Options

The following [tool-options](/dev-tools/#tool-options) are available for the `pipx` backend—these
go in `[tools]` in `mise.toml`.

### `extras`

Install additional components.

```toml
[tools]
"pipx:harlequin" = { version = "latest", extras = "postgres,s3" }
```

### `pipx_args`

Additional arguments to pass to `pipx` when installing the package.

```toml
[tools]
"pipx:black" = { version = "latest", pipx_args = "--preinstall" }
```

### `uvx`

Set to `false` to always disable uv for this tool.

```toml
[tools]
"pipx:ansible" = { version = "latest", uvx = "false", pipx_args = "--include-deps" }
```

### `uvx_args`

Additional arguments to pass to `uvx` when installing the package.

```toml
[tools]
"pipx:ansible-core" = { version = "latest", uvx_args = "--with ansible" }
```

---

---
url: /plugin-lua-modules.md
---
# Plugin Lua Modules

mise plugins have access to a comprehensive set of built-in Lua modules that provide common functionality. These modules are available in both backend plugins and tool plugins, making it easy to perform common operations like HTTP requests, JSON parsing, file operations, and more.

## Available Modules

### Core Modules

* **`cmd`** - Execute shell commands
* **`json`** - Parse and generate JSON
* **`http`** - Make HTTP requests and downloads
* **`file`** - File system operations
* **`env`** - Environment variable operations
* **`strings`** - String manipulation utilities
* **`semver`** - Semantic version comparison and sorting
* **`html`** - HTML parsing and manipulation
* **`archiver`** - Archive extraction
* **`log`** - Structured logging

## HTTP Module

The HTTP module provides functionality for making web requests and downloading files.

### Basic HTTP Requests

```lua
local http = require("http")

-- GET request
local resp, err = http.get({
    url = "https://api.github.com/repos/owner/repo/releases",
    headers = {
        ['User-Agent'] = "mise-plugin",
        ['Accept'] = "application/json"
    }
})

if err ~= nil then
    error("Request failed: " .. err)
end

if resp.status_code ~= 200 then
    error("HTTP error: " .. resp.status_code)
end

local body = resp.body
```

### HEAD Requests

```lua
local http = require("http")

-- HEAD request to check file info
local resp, err = http.head({
    url = "https://example.com/file.tar.gz"
})

if err ~= nil then
    error("HEAD request failed: " .. err)
end

local content_length = resp.headers['content-length']
local content_type = resp.headers['content-type']
```

### File Downloads

```lua
local http = require("http")

-- Download file
local err = http.download_file({
    url = "https://github.com/owner/repo/archive/v1.0.0.tar.gz",
    headers = {
        ['User-Agent'] = "mise-plugin"
    }
}, "/path/to/download.tar.gz")

if err ~= nil then
    error("Download failed: " .. err)
end
```

### Response Object

HTTP responses contain the following fields:

```lua
{
    status_code = 200,
    headers = {
        ['content-type'] = "application/json",
        ['content-length'] = "1234"
    },
    body = "response content"
}
```

## JSON Module

The JSON module provides encoding and decoding functionality.

### Basic Usage

```lua
local json = require("json")

-- Encode table to JSON string
local obj = {
    name = "mise-plugin",
    version = "1.0.0",
    tools = {"prettier", "eslint"}
}
local jsonStr = json.encode(obj)
-- Result: '{"name":"mise-plugin","version":"1.0.0","tools":["prettier","eslint"]}'

-- Decode JSON string to table
local decoded = json.decode(jsonStr)
print(decoded.name)  -- "mise-plugin"
print(decoded.tools[1])  -- "prettier"
```

### Error Handling (Lua)

```lua
local json = require("json")

-- Safe JSON parsing
local success, result = pcall(json.decode, response_body)
if not success then
    error("Failed to parse JSON: " .. result)
end

-- Use the parsed data
for _, item in ipairs(result) do
    print(item.version)
end
```

## Strings Module

The strings module provides various string manipulation utilities.

### String Operations

```lua
local strings = require("strings")

-- Split string into parts
local parts = strings.split("hello,world,test", ",")
print(parts[1])  -- "hello"
print(parts[2])  -- "world"
print(parts[3])  -- "test"

-- Join strings
local joined = strings.join({"hello", "world", "test"}, " - ")
print(joined)  -- "hello - world - test"

-- Trim whitespace
local trimmed = strings.trim_space("  hello world  ")
print(trimmed)  -- "hello world"
```

### String Checks

```lua
local strings = require("strings")

-- Check prefixes and suffixes
local text = "hello world"
print(strings.has_prefix(text, "hello"))  -- true
print(strings.has_suffix(text, "world"))  -- true
print(strings.contains(text, "lo wo"))    -- true

-- Trim specific characters
local trimmed = strings.trim("hello world", "world")
print(trimmed)  -- "hello "
```

### Version String Utilities

```lua
local strings = require("strings")

-- Common version string operations
local function normalize_version(version)
    -- Remove 'v' prefix if present
    version = strings.trim_prefix(version, "v")

    -- Remove pre-release suffixes
    local parts = strings.split(version, "-")
    return parts[1]
end

local version = normalize_version("v1.2.3-beta.1")  -- "1.2.3"
```

## Semver Module

The semver module provides semantic version comparison and sorting functionality. This is useful for sorting version lists returned by `Available()` hooks.

### Version Comparison

```lua
local semver = require("semver")

-- Compare two versions
-- Returns: -1 if v1 < v2, 0 if equal, 1 if v1 > v2
local result = semver.compare("1.2.3", "1.2.4")  -- -1
local result = semver.compare("2.0.0", "1.9.9")  -- 1
local result = semver.compare("1.0.0", "1.0.0")  -- 0

-- Handles numeric comparison correctly
local result = semver.compare("9.6.9", "9.6.24")   -- -1 (not lexicographic!)
local result = semver.compare("10.0.0", "9.6.24") -- 1
```

### Parse Version

```lua
local semver = require("semver")

-- Parse version string into numeric parts
local parts = semver.parse("1.2.3")
print(parts[1])  -- 1
print(parts[2])  -- 2
print(parts[3])  -- 3

-- Works with prefixes and suffixes
local parts = semver.parse("v1.2.3-beta")  -- {1, 2, 3}
```

### Sort Version Strings

```lua
local semver = require("semver")

-- Sort array of version strings (ascending order)
local versions = {"1.10.0", "1.2.0", "1.9.0", "2.0.0"}
local sorted = semver.sort(versions)
-- Result: {"1.2.0", "1.9.0", "1.10.0", "2.0.0"}
```

### Sort Tables by Version Field

```lua
local semver = require("semver")

-- Sort array of tables by a version field (ascending order)
local releases = {
    {version = "1.10.0", url = "..."},
    {version = "1.2.0", url = "..."},
    {version = "1.9.0", url = "..."},
}
local sorted = semver.sort_by(releases, "version")
-- Result: sorted by version ascending
```

### Real-World Example: Available Hook

```lua
local http = require("http")
local semver = require("semver")

function PLUGIN:Available(ctx)
    local resp, err = http.get({
        url = "https://example.com/releases/"
    })

    if err ~= nil then
        error("Failed to fetch versions: " .. err)
    end

    local result = {}
    -- Parse versions from response...
    for version in string.gmatch(resp.body, 'v([0-9]+%.[0-9]+%.[0-9]+)') do
        table.insert(result, {version = version})
    end

    -- Sort versions semantically (ascending order - oldest first)
    return semver.sort_by(result, "version")
end
```

### Using Compare in Custom Sort

```lua
local semver = require("semver")

-- Sort with custom comparator (descending order - newest first)
table.sort(versions, function(a, b)
    return semver.compare(a.version, b.version) > 0
end)

-- Sort ascending (oldest first) - default for Available()
table.sort(versions, function(a, b)
    return semver.compare(a.version, b.version) < 0
end)
```

## HTML Module

The HTML module provides HTML parsing capabilities.

### Basic HTML Parsing

```lua
local html = require("html")

-- Parse HTML document
local doc = html.parse([[
    <html>
        <body>
            <div id="version" class="info">1.2.3</div>
            <ul class="downloads">
                <li><a href="/download/v1.2.3.tar.gz">Source</a></li>
                <li><a href="/download/v1.2.3.zip">Windows</a></li>
            </ul>
        </body>
    </html>
]])

-- Extract text content
local version = doc:find("#version"):text()  -- "1.2.3"

-- Extract attributes
local links = doc:find("a")
for _, link in ipairs(links) do
    local href = link:attr("href")
    local text = link:text()
    print(text .. ": " .. href)
end
```

### CSS Selectors

```lua
local html = require("html")

local doc = html.parse(html_content)

-- Find by ID
local element = doc:find("#version")

-- Find by class
local elements = doc:find(".download-link")

-- Find by tag
local links = doc:find("a")

-- Complex selectors
local specific_links = doc:find("ul.downloads a[href$='.tar.gz']")
```

### Real-World Example: Scraping Releases

```lua
local html = require("html")
local http = require("http")

function get_github_releases(owner, repo)
    local resp, err = http.get({
        url = "https://github.com/" .. owner .. "/" .. repo .. "/releases"
    })

    if err ~= nil then
        error("Failed to fetch releases: " .. err)
    end

    local doc = html.parse(resp.body)
    local releases = {}

    -- Find all release tags
    local release_elements = doc:find("a[href*='/releases/tag/']")
    for _, element in ipairs(release_elements) do
        local href = element:attr("href")
        local version = href:match("/releases/tag/(.+)")
        if version then
            table.insert(releases, {
                version = version,
                url = "https://github.com" .. href
            })
        end
    end

    return releases
end
```

## Archiver Module

The archiver module provides functionality for extracting compressed archives.

### Supported Formats

* **tar.gz** - Gzipped tar archives
* **tar.xz** - XZ compressed tar archives
* **tar.bz2** - Bzip2 compressed tar archives
* **zip** - ZIP archives

### Basic Extraction

```lua
local archiver = require("archiver")

-- Extract archive to directory
local err = archiver.decompress("archive.tar.gz", "extracted/")
if err ~= nil then
    error("Extraction failed: " .. err)
end

-- Extract ZIP file
local err = archiver.decompress("package.zip", "destination/")
if err ~= nil then
    error("ZIP extraction failed: " .. err)
end
```

### Real-World Example: Plugin Installation

```lua
local archiver = require("archiver")
local http = require("http")

function install_from_archive(download_url, install_path)
    -- Download the archive
    local archive_path = install_path .. "/download.tar.gz"
    local err = http.download_file({
        url = download_url
    }, archive_path)

    if err ~= nil then
        error("Download failed: " .. err)
    end

    -- Extract to installation directory
    local err = archiver.decompress(archive_path, install_path)
    if err ~= nil then
        error("Extraction failed: " .. err)
    end

    -- Clean up archive
    os.remove(archive_path)
end
```

## File Module

The file module provides file system operations.

### Path Joining

```lua
local file = require("file")

-- Join path segments using the OS-specific separator
local full_path = file.join_path("/foo", "bar", "baz.txt")
print(full_path)  -- On Unix: /foo/bar/baz.txt, on Windows: \foo\bar\baz.txt
```

The `file.join_path(...)` function joins any number of path segments using the correct separator for the current operating system. This is the recommended way to construct file paths in cross-platform plugins.

### Read File Contents

```lua
local file = require("file")
print(file.read("/path/to/file"))
```

### Create Symbolic Links

```lua
local file = require("file")
file.symlink("/path/to/source", "/path/to/new-symlink")
```

### Check if file exists

```lua
local file = require("file")
if file.exists("important_file.txt") then
    print("File exists")
else
    print("File does not exist")
end
```

## Environment Module

The env module provides environment variable operations.

### Set Environment Variable

```lua
local env = require("env")

-- Set environment variable
env.setenv("MY_VAR", "my_value")
```

### Get Environment Variable

> To read variables in Lua, use `os.getenv("MY_VAR")`.

### Path Operations

```lua
local env = require("env")

-- Get current PATH
local current_path = os.getenv("PATH")

-- Add to PATH
local new_path = "/usr/local/bin:" .. current_path
env.setenv("PATH", new_path)

-- Platform-specific PATH separator
local separator = package.config:sub(1,1) == '\\' and ";" or ":"
local paths = {"/usr/local/bin", "/opt/bin", current_path}
env.setenv("PATH", table.concat(paths, separator))
```

## Command Module

The cmd module provides shell command execution.

### Basic Command Execution

```lua
local cmd = require("cmd")

-- Execute command and get output
local output = cmd.exec("ls -la")
print("Directory listing:", output)

-- Execute command with error handling
local success, output = pcall(cmd.exec, "some-command")
if not success then
    error("Command failed: " .. output)
end
```

### Command Execution with Options

```lua
local cmd = require("cmd")

-- Execute command in a specific directory
local output = cmd.exec("pwd", {cwd = "/tmp"})
print("Current directory:", output)

-- Execute command with custom environment variables
local result = cmd.exec("echo $TEST_VAR", {
    cwd = "/path/to/project",
    env = {TEST_VAR = "hello", NODE_ENV = "production"}
})

-- Install package in specific directory
local result = cmd.exec("npm install package-name", {cwd = "/path/to/project"})
```

### Available Options

The options table supports the following keys:

* **`cwd`** (string): Set the working directory for the command
* **`env`** (table): Set environment variables for the command execution. These are merged on top of the inherited environment (see below).
* **`timeout`** (number): Set a timeout for command execution (future feature)

### Environment Inheritance in Env Module Hooks

When `cmd.exec()` is called from environment module hooks (`MiseEnv`, `MisePath`), the command automatically inherits the mise-constructed environment instead of the process environment. This includes environment variables set by preceding directives and `_.path` entries accumulated so far.

When the module directive has `tools = true`, the inherited environment also includes tool installation bin paths. This means mise-managed tools are directly callable:

```toml
[env]
_.my-plugin = { tools = true }
```

```lua
function PLUGIN:MiseEnv(ctx)
    -- With tools=true, mise-managed tools are on PATH
    local version = cmd.exec("node --version")
    return {
        {key = "NODE_VERSION", value = version:gsub("%s+", "")}
    }
end
```

Without `tools = true`, only `_.path` directive entries and the original system PATH are available to `cmd.exec()`.

Any explicit `env` options passed to `cmd.exec()` are merged on top of the inherited environment, allowing selective overrides.

### Platform-Specific Commands

```lua
local cmd = require("cmd")

-- Cross-platform command execution
local function is_windows()
    return package.config:sub(1,1) == '\\'
end

local function get_os_info()
    if is_windows() then
        return cmd.exec("systeminfo")
    else
        return cmd.exec("uname -a")
    end
end

local os_info = get_os_info()
print("OS Info:", os_info)
```

## Practical Examples

### Version Fetching from API

```lua
local http = require("http")
local json = require("json")

function fetch_npm_versions(package_name)
    local resp, err = http.get({
        url = "https://registry.npmjs.org/" .. package_name,
        headers = {
            ['User-Agent'] = "mise-plugin"
        }
    })

    if err ~= nil then
        error("Failed to fetch package info: " .. err)
    end

    local package_info = json.decode(resp.body)
    local versions = {}

    for version, _ in pairs(package_info.versions) do
        table.insert(versions, version)
    end

    -- Sort versions (simple string sort)
    table.sort(versions)

    return versions
end
```

### File Download with Progress

```lua
local http = require("http")
local file = require("file")

function download_with_verification(url, dest_path, expected_sha256)
    -- Download file
    local err = http.download_file({
        url = url,
        headers = {
            ['User-Agent'] = "mise-plugin"
        }
    }, dest_path)

    if err ~= nil then
        error("Download failed: " .. err)
    end

    -- Verify file exists
    if not file.exists(dest_path) then
        error("Downloaded file not found")
    end

    -- Note: SHA256 verification would need additional implementation
    -- This is a simplified example
    print("Downloaded successfully to: " .. dest_path)
end
```

### Configuration File Parsing

```lua
local file = require("file")
local json = require("json")
local strings = require("strings")

function parse_config_file(config_path)
    if not file.exists(config_path) then
        return {}  -- Return empty config
    end

    local content = file.read(config_path)
    if not content then
        error("Failed to read config file: " .. config_path)
    end

    -- Trim whitespace
    content = strings.trim_space(content)

    -- Parse JSON
    local success, config = pcall(json.decode, content)
    if not success then
        error("Invalid JSON in config file: " .. config_path)
    end

    return config
end
```

### Web Scraping for Versions

```lua
local http = require("http")
local html = require("html")
local strings = require("strings")

function scrape_versions_from_releases(base_url)
    local resp, err = http.get({
        url = base_url .. "/releases"
    })

    if err ~= nil then
        error("Failed to fetch releases page: " .. err)
    end

    local doc = html.parse(resp.body)
    local versions = {}

    -- Find version tags
    local version_elements = doc:find("h2 a[href*='/releases/tag/']")
    for _, element in ipairs(version_elements) do
        local version_text = element:text()
        local version = strings.trim_space(version_text)

        -- Remove 'v' prefix if present
        version = strings.trim_prefix(version, "v")

        if version and version ~= "" then
            table.insert(versions, {
                version = version,
                url = base_url .. element:attr("href")
            })
        end
    end

    return versions
end
```

## Log Module

The log module provides structured logging that routes through Rust's `log` crate, respecting `MISE_DEBUG` and `MISE_TRACE` environment variables.

### Log Levels

```lua
local log = require("log")

log.trace("detailed tracing info")   -- only visible with MISE_TRACE=1
log.debug("debugging info")          -- visible with MISE_DEBUG=1
log.info("status message")           -- visible by default
log.warn("warning message")          -- visible by default
log.error("error message")           -- visible by default
```

### Variadic Arguments

All log functions accept multiple arguments of any type. Arguments are converted to strings via `tostring()` and joined with tab characters (`\t`), matching Lua's `print()` behavior:

```lua
log.info("version", version, "installed to", path)
-- Output: [plugin-name] version<TAB>1.0.0<TAB>installed to<TAB>/path
```

### Plugin Name Prefix

All log messages are automatically prefixed with `[plugin_name]`:

```
mise [INFO] [my-plugin] Installing version 1.0.0
```

### Print Override

`print()` is overridden to route through `info!()` level logging. This means:

* `print()` output goes to stderr instead of stdout
* Messages are prefixed with `[plugin_name]`
* Output respects log level filtering

```lua
-- These are equivalent:
print("hello", "world")
log.info("hello", "world")
```

### Accessing via vfox Namespace

The log module is also available as `vfox.log`:

```lua
local log = require("vfox").log
log.info("message")
```

## Best Practices

### Error Handling

Always handle errors gracefully:

```lua
local http = require("http")
local json = require("json")

function safe_api_call(url)
    local resp, err = http.get({url = url})

    if err ~= nil then
        error("HTTP request failed: " .. err)
    end

    if resp.status_code ~= 200 then
        error("API returned error: " .. resp.status_code .. " " .. resp.body)
    end

    local success, data = pcall(json.decode, resp.body)
    if not success then
        error("Failed to parse JSON response: " .. data)
    end

    return data
end
```

### Caching

Implement caching for expensive operations:

```lua
local cache = {}
local cache_ttl = 3600  -- 1 hour

function cached_http_get(url)
    local now = os.time()
    local cache_key = url

    -- Check cache
    if cache[cache_key] and (now - cache[cache_key].timestamp) < cache_ttl then
        return cache[cache_key].data
    end

    -- Fetch fresh data
    local http = require("http")
    local resp, err = http.get({url = url})

    if err ~= nil then
        error("HTTP request failed: " .. err)
    end

    -- Cache the result
    cache[cache_key] = {
        data = resp,
        timestamp = now
    }

    return resp
end
```

### Platform Detection

Handle cross-platform differences:

```lua
local function get_platform_info()
    local is_windows = package.config:sub(1,1) == '\\'
    local cmd = require("cmd")

    if is_windows then
        return {
            os = "windows",
            arch = os.getenv("PROCESSOR_ARCHITECTURE") or "x64",
            path_sep = "\\",
            env_sep = ";"
        }
    else
        local uname = cmd.exec("uname -s"):lower()
        local arch = cmd.exec("uname -m")

        return {
            os = uname,
            arch = arch,
            path_sep = "/",
            env_sep = ":"
        }
    end
end
```

## Next Steps

* [Backend Plugin Development](backend-plugin-development.md)
* [Tool Plugin Development](tool-plugin-development.md)
* [Publishing your plugin](plugin-publishing.md)

---

---
url: /plugin-publishing.md
---
# Plugin Publishing

This guide shows how to publish and distribute your plugins, whether they are backend plugins or tool plugins. Publishing makes your plugins available to other users and ensures they can be easily installed and maintained.

## Publishing Checklist

Before publishing your plugin, ensure you have:

### Essential Files

* **`metadata.lua`** - Plugin metadata with name, version, description, and author
* **Plugin implementation** - Either backend methods or hook functions
* **Test coverage** - Automated tests to verify functionality

### Optional but Recommended

* **`README.md`** - Basic usage instructions and examples
* **`test/`** directory - Test scripts for verification
* **Version control** - Git repository with proper versioning

## Repository Setup

### 1. Initialize Repository

The easiest way to start is with the [mise-tool-plugin-template](https://github.com/jdx/mise-tool-plugin-template):

```bash
# Clone the template
git clone https://github.com/jdx/mise-tool-plugin-template my-plugin
cd my-plugin

# Remove template history and set up your own repository
rm -rf .git
git init
git remote add origin https://github.com/username/my-plugin.git

# Customize for your plugin
# Edit metadata.lua, hooks/*.lua, README.md, etc.
```

Alternatively, create a repository from scratch:

```bash
# Create plugin directory
mkdir my-plugin
cd my-plugin

# Initialize git repository
git init
git remote add origin https://github.com/username/my-plugin.git

# Create initial structure
touch metadata.lua
mkdir -p test
echo "# My Plugin" > README.md
```

### 2. Basic Directory Structure

Organize your plugin with this structure:

```
my-plugin/
├── metadata.lua          # Plugin metadata
├── README.md            # Basic documentation
├── test/                # Test scripts
│   └── test.sh
├── .gitignore           # Git ignore rules
└── [implementation files]
```

For backend plugins:

```
backend-plugin/
├── metadata.lua          # Backend methods implementation
├── README.md
└── test/
    └── test.sh
```

For tool plugins:

```
tool-plugin/
├── metadata.lua          # Plugin metadata
├── hooks/               # Hook implementations
│   ├── available.lua
│   ├── pre_install.lua
│   └── env_keys.lua
├── lib/                 # Helper libraries
│   └── helper.lua
├── README.md
└── test/
    └── test.sh
```

### 3. Git Ignore Configuration

Create a `.gitignore` file:

```gitignore
# Temporary files
*.tmp
*.temp
.DS_Store
Thumbs.db

# Test artifacts
test/tmp/
test/output/

# IDE files
.vscode/
.idea/
*.swp
*.swo

# OS files
*.log
```

## Versioning Strategy

### Semantic Versioning

Use semantic versioning (SemVer) for your plugin releases:

* **Major version** (1.0.0 → 2.0.0): Breaking changes
* **Minor version** (1.0.0 → 1.1.0): New features, backward compatible
* **Patch version** (1.0.0 → 1.0.1): Bug fixes, backward compatible

### Version Management

Update version in `metadata.lua`:

```lua
PLUGIN = {
    name = "my-plugin",
    version = "1.2.3",  -- Update this for each release
    description = "My awesome plugin",
    author = "Your Name"
}
```

Create git tags for releases:

```bash
# Tag the current commit
git tag -a v1.2.3 -m "Release version 1.2.3"

# Push tags to repository
git push origin --tags
```

## Testing Before Publication

### Automated Testing

Create comprehensive test scripts:

```bash
#!/bin/bash
# test/test.sh
set -e

echo "Testing plugin functionality..."

# Install plugin locally
mise plugin install my-plugin .

# Test basic functionality
if [[ "$(mise ls-remote my-plugin)" == "" ]]; then
    echo "ERROR: No versions available"
    exit 1
fi

# Test installation
mise install my-plugin@latest

# Test execution
mise exec my-plugin:tool -- --version

# Clean up
mise plugin remove my-plugin

echo "All tests passed!"
```

### Manual Testing

Test your plugin manually:

```bash
# Link for development
mise plugin link my-plugin /path/to/plugin

# Test all functionality
mise ls-remote my-plugin
mise install my-plugin@latest
mise use my-plugin@latest

# Test in different environments
docker run --rm -it ubuntu:latest bash -c "
    curl -fsSL https://mise.jdx.dev/install.sh | sh
    mise plugin install my-plugin https://github.com/username/my-plugin
    mise install my-plugin@latest
"
```

## Publishing Process

### 1. Prepare for Release

Before publishing, ensure everything is ready:

```bash
# Run tests
./test/test.sh

# Check git status
git status

# Update version in metadata.lua
vim metadata.lua

# Commit changes
git add .
git commit -m "Prepare release v1.2.3"
```

### 2. Create Release

Create a tagged release:

```bash
# Create and push tag
git tag -a v1.2.3 -m "Release version 1.2.3"
git push origin v1.2.3
git push origin main
```

### 3. GitHub Releases (Recommended)

Create a GitHub release for better discoverability:

1. Go to your repository on GitHub
2. Click "Releases" → "Create a new release"
3. Choose your tag (v1.2.3)
4. Write release notes describing changes
5. Publish the release

### 4. Release Notes Template

````markdown
## Changes in v1.2.3

### Added

- New feature X
- Support for Y

### Changed

- Improved performance of Z
- Updated dependencies

### Fixed

- Fixed issue with A
- Resolved bug in B

### Installation

```bash
mise plugin install my-plugin https://github.com/username/my-plugin
````

````

## Distribution Methods

### 1. Direct Git Installation

Users can install directly from your repository:

```bash
# Install from GitHub
mise plugin install my-plugin https://github.com/username/my-plugin

# Install specific version
mise plugin install my-plugin https://github.com/username/my-plugin@v1.2.3

# Install from other Git providers
mise plugin install my-plugin https://gitlab.com/username/my-plugin
````

### 2. Private Repository Access

For private repositories, users need access:

```bash
# SSH access (recommended)
mise plugin install my-plugin git@github.com:username/private-plugin.git

# HTTPS with token
mise plugin install my-plugin https://username:token@github.com/username/private-plugin.git
```

### 3. Archive Distribution

You can also distribute as archives:

```bash
# Create release archive
git archive --format=zip --output=my-plugin-v1.2.3.zip v1.2.3

# Users can install from archive
mise plugin install my-plugin https://github.com/username/my-plugin/releases/download/v1.2.3/my-plugin-v1.2.3.zip
```

## Maintenance and Updates

### 1. Update Workflow

Establish a regular update process:

```bash
# Development workflow
git checkout -b feature/new-feature
# ... make changes ...
git commit -m "Add new feature"
git push origin feature/new-feature

# After review and merge
git checkout main
git pull origin main
git tag -a v1.3.0 -m "Release v1.3.0"
git push origin v1.3.0
```

### 2. Backward Compatibility

Maintain backward compatibility when possible:

* Keep existing plugin interface unchanged
* Add new features as optional
* Deprecate old features gradually
* Document breaking changes clearly

### 3. User Communication

Keep users informed about updates:

* Use clear release notes
* Announce major changes
* Provide migration guides for breaking changes
* Maintain documentation

## Security Considerations

### 1. Code Review

* Review all code changes before publishing
* Check for security vulnerabilities
* Validate external dependencies
* Test with untrusted inputs

### 2. Dependency Management

* Pin dependency versions where possible
* Regularly update dependencies
* Monitor for security advisories
* Use trusted sources only

### 3. Access Control

* Limit repository access appropriately
* Use strong authentication
* Regularly audit access permissions
* Consider signed releases for sensitive plugins

## Best Practices

### 1. Documentation

* Keep README.md concise but complete
* Include usage examples
* Document configuration options
* Provide troubleshooting guide

### 2. Testing

* Test on multiple platforms
* Include edge cases
* Test upgrade scenarios
* Automate testing where possible

### 3. Community

* Respond to issues promptly
* Accept contributions gracefully
* Maintain consistent code style
* Be helpful and respectful

### 4. Release Management

* Follow semantic versioning
* Create clear release notes
* Test releases thoroughly
* Maintain stable branches

## Troubleshooting

### Common Issues

**Plugin not installing:**

```bash
# Check repository URL
git clone https://github.com/username/my-plugin.git

# Verify metadata.lua exists
ls -la my-plugin/metadata.lua

# Test locally
mise plugin link my-plugin ./my-plugin
```

**Version conflicts:**

```bash
# Check version in metadata.lua
grep version my-plugin/metadata.lua

# Verify git tags
git tag -l
```

**Permission issues:**

```bash
# Check repository permissions
git ls-remote https://github.com/username/my-plugin.git

# For private repos, verify access
ssh -T git@github.com
```

## Next Steps

* [Backend Plugin Development](backend-plugin-development.md)
* [Tool Plugin Development](tool-plugin-development.md)
* [Plugin Lua Modules](plugin-lua-modules.md)

## Examples

### Simple Backend Plugin Release

```bash
# 1. Prepare plugin
cd my-backend-plugin
echo "Updated backend methods" > metadata.lua

# 2. Test locally
mise plugin link my-plugin .
mise ls-remote my-plugin:tool

# 3. Release
git add .
git commit -m "v1.0.0: Initial release"
git tag -a v1.0.0 -m "Initial release"
git push origin v1.0.0
```

### Tool Plugin with Hooks

```bash
# 1. Prepare plugin
cd my-tool-plugin
./test/test.sh  # Run tests

# 2. Update version
sed -i 's/version = "1.0.0"/version = "1.1.0"/' metadata.lua

# 3. Release
git add .
git commit -m "v1.1.0: Add new hook functionality"
git tag -a v1.1.0 -m "Add new hook functionality"
git push origin v1.1.0
```

---

---
url: /plugins.md
---
# Plugins

Plugins in mise are a way to extend `mise` with new functionality like extra tools or environment variable management.

Historically it was the only way to add new tools (as the only backend was [asdf](/dev-tools/backends/asdf.html)).

The way that backend works is every tool has its own plugin which needs to be manually installed. However, now with [core tools](/core-tools.html)
and backends like [aqua](/dev-tools/backends/aqua.html)/[github](/dev-tools/backends/github.html), plugins are no longer necessary to run most tools in mise.

Tool plugins should be avoided for security reasons. New tools will not be accepted into mise built with asdf/plugins unless they are very popular and
aqua/github is not an option for some reason.

The only exception is if the tool needs to set env vars or has a complex installation process, as plugins can provide functionality like [setting env vars globally](/environments/#plugin-provided-env-directives) without relying on a tool being installed. They can also provide [aliases for versions](/dev-tools/aliases.html#aliased-versions).

If you want to integrate a new tool into mise, you should either try to get it into the [aqua registry](https://mise.jdx.dev/dev-tools/backends/aqua.html)
or see if it can be installed with [github](https://mise.jdx.dev/dev-tools/backends/github.html). Then add it to the [registry](https://github.com/jdx/mise/blob/main/registry/).
Aqua is definitely preferred to github as it has better UX and more features like slsa verification and the ability to use different logic for older versions.

You can manage all installed plugins in `mise` with [`mise plugins`](/cli/plugins.html).

```shell
mise plugins ls --urls
# Plugin                          Url                                                     Ref  Sha
# 1password                       https://github.com/mise-plugins/mise-1password-cli.git  HEAD f5d5aab
# vfox-mise-plugins-vfox-dart     https://github.com/mise-plugins/vfox-dart               HEAD 1424253
# ...
```

## Backend Plugins

Backend plugins provide enhanced functionality with modern backend methods. These plugins use the `plugin:tool` format and offer advantages over traditional plugins:

* **Multiple Tools**: A single plugin can manage multiple tools
* **Enhanced Methods**: Backend methods for listing versions, installing, and setting environment variables
* **Cross-platform**: Work on Windows, macOS, and Linux
* **Performance**: Faster execution than shell-based plugins

Example usage:

```bash
# Install a backend plugin
mise plugin install my-plugin https://github.com/username/my-plugin

# Use the plugin:tool format
mise install my-plugin:some-tool@1.0.0
mise use my-plugin:some-tool@latest
```

See [Backend Plugin Development](backend-plugin-development.md) for creating backend plugins. You can start quickly with the [mise-backend-plugin-template](https://github.com/jdx/mise-backend-plugin-template).

## Tool Plugins

Tool plugins use the traditional hook-based approach with Lua scripts. These plugins provide:

* **Hook-based**: Use hooks like `PreInstall`, `PostInstall`, `Available`, etc.
* **Single Tool**: Each plugin manages one tool
* **Cross-platform**: Work on Windows, macOS, and Linux
* **Flexible**: Full control over installation and environment setup

Example usage:

```bash
# Install a tool plugin
mise plugin install my-tool https://github.com/username/my-tool-plugin

# Use the tool directly
mise install my-tool@1.0.0
mise use my-tool@latest
```

See [Tool Plugin Development](tool-plugin-development.md) for creating tool plugins. The [mise-tool-plugin-template](https://github.com/jdx/mise-tool-plugin-template) provides a ready-to-use starting point.

## Environment Plugins

Environment plugins provide environment variables and PATH modifications without managing tool versions. They're ideal for integrating with secret managers, setting dynamic configurations, and standardizing team environments.

Example usage:

```bash
# Install an environment plugin
mise plugin install my-env-plugin https://github.com/username/my-env-plugin
```

```toml
# Configure in mise.toml
[env]
_.my-env-plugin = { api_url = "https://api.example.com", debug = true }
```

Unlike tool plugins, environment plugins:

* Only implement environment hooks (`MiseEnv`, `MisePath`)
* Are activated via `env._.<plugin-name>` syntax
* Don't manage tool versions or installations

See [Environment Plugin Development](env-plugin-development.md) for creating environment plugins. The [mise-env-plugin-template](https://github.com/jdx/mise-env-plugin-template) repository provides a ready-to-use starting point.

## General Plugin Usage

For end-user documentation on installing and using both backend and tool plugins, see [Using Plugins](plugin-usage.md).

## asdf (Legacy) Plugins

mise can use asdf's plugin ecosystem under the hood for backward compatibility. These plugins contain shell scripts like
`bin/install` (for installing) and `bin/list-all` (for listing all of the available versions).

asdf plugins have limitations compared to modern backends and should only be used when necessary. They only work on Linux/macOS and are slower than native backends.

See [asdf (Legacy) Plugins](asdf-legacy-plugins.md) for comprehensive documentation on using and creating these plugins.

## Plugin Authors

<https://github.com/mise-plugins> is a GitHub organization for community-developed plugins.
See [SECURITY.md](https://github.com/jdx/mise/blob/main/SECURITY.md) for more details on how plugins here are treated differently.

If you'd like your plugin to be hosted here please let me know (GH discussion or discord is fine)
and I'd be happy to host it for you.

## Tool Options

mise has support for "tool options" which is configuration specified in `mise.toml` to change behavior
of tools. One example of this is virtualenv on python runtimes:

```toml
[tools]
python = { version='3.11', virtualenv='.venv' }
```

This will be passed to all plugin scripts as `MISE_TOOL_OPTS__VIRTUALENV=.venv`. The user can specify
any option, and it will be passed to the plugin in that format.

Currently, this only supports simple strings, but we can make it compatible with more complex types
(arrays, tables) fairly easily if there is a need for it.

## Templates

Plugin custom repository values can be templates, see [Templates](/templates) for details.

```toml
[plugins]
"vfox-backend:my-plugin" = "https://{{ get_env(name='GIT_USR', default='empty') }}:{{ get_env(name='GIT_PWD', default='empty') }}@github.com/foo/my-plugin.git"
```

---

---
url: /dev-tools/prepare.md
---
# Prepare&#x20;

The `mise prepare` command ensures project dependencies are ready by checking if lockfiles
are newer than installed outputs (e.g., `package-lock.json` vs `node_modules/`) and running
install commands if needed.

## Quick Start

```bash
# Enable experimental features
export MISE_EXPERIMENTAL=1

# Run all applicable prepare steps
mise prepare

# Or use the alias
mise prep
```

## Configuration

Configure prepare providers in `mise.toml`:

```toml
# Built-in npm provider (auto-detects lockfile)
[prepare.npm]
auto = true  # Auto-run before mise x/run

# Built-in providers for other package managers
[prepare.yarn]
[prepare.pnpm]
[prepare.bun]
[prepare.go]
[prepare.pip]
[prepare.poetry]
[prepare.uv]
[prepare.bundler]
[prepare.composer]

# Custom provider
[prepare.codegen]
auto = true
sources = ["schema/*.graphql"]
outputs = ["src/generated/"]
run = "npm run codegen"

# Disable specific providers
[prepare]
disable = ["npm"]
```

## Built-in Providers

mise includes built-in providers for common package managers:

| Provider   | Sources                                 | Outputs               | Command                              |
| ---------- | --------------------------------------- | --------------------- | ------------------------------------ |
| `npm`      | `package.json`, `package-lock.json`     | `node_modules/`       | `npm install`                        |
| `yarn`     | `package.json`, `yarn.lock`             | `node_modules/`       | `yarn install`                       |
| `pnpm`     | `package.json`, `pnpm-lock.yaml`        | `node_modules/`       | `pnpm install`                       |
| `bun`      | `package.json`, `bun.lock`, `bun.lockb` | `node_modules/`       | `bun install`                        |
| `go`       | `go.mod`                                | `vendor/` or `go.sum` | `go mod vendor` or `go mod download` |
| `pip`      | `requirements.txt`                      | `.venv/`              | `pip install -r requirements.txt`    |
| `poetry`   | `pyproject.toml`, `poetry.lock`         | `.venv/`              | `poetry install`                     |
| `uv`       | `pyproject.toml`, `uv.lock`             | `.venv/`              | `uv sync`                            |
| `bundler`  | `Gemfile`, `Gemfile.lock`               | `vendor/bundle/`      | `bundle install`                     |
| `composer` | `composer.json`, `composer.lock`        | `vendor/`             | `composer install`                   |

Built-in providers are only active when explicitly configured in `mise.toml` and their lockfile exists.

## Custom Providers

Create custom providers for project-specific build steps:

```toml
[prepare.codegen]
sources = ["schema/*.graphql", "codegen.yml"]
outputs = ["src/generated/"]
run = "npm run codegen"
description = "Generate GraphQL types"

[prepare.prisma]
sources = ["prisma/schema.prisma"]
outputs = ["node_modules/.prisma/"]
run = "npx prisma generate"
```

### Provider Options

| Option          | Type     | Description                                                                     |
| --------------- | -------- | ------------------------------------------------------------------------------- |
| `auto`          | bool     | Auto-run before `mise x` and `mise run` (default: false)                        |
| `sources`       | string\[] | Files/patterns to check for changes                                             |
| `outputs`       | string\[] | Files/directories that should be newer than sources                             |
| `run`           | string   | Command to run when stale                                                       |
| `env`           | table    | Environment variables to set                                                    |
| `dir`           | string   | Working directory for the command                                               |
| `description`   | string   | Description shown in output                                                     |
| `touch_outputs` | bool     | Touch output mtimes after a successful run so they appear fresh (default: true) |
| `depends`       | string\[] | Other provider names that must complete before this one runs                    |
| `timeout`       | string   | Timeout for the run command, e.g., `"30s"`, `"5m"` (default: no timeout)        |

## Freshness Checking

mise uses modification time (mtime) comparison to determine if outputs are stale:

1. Find the most recent mtime among all source files
2. Find the most recent mtime among all output files
3. If any source is newer than all outputs, the provider is stale

This means:

* If you modify `package-lock.json`, `node_modules/` will be considered stale
* If `node_modules/` doesn't exist, the provider is always stale
* If sources don't exist, the provider is considered fresh (nothing to do)

After a successful run, mise touches the mtime of each output to now (controlled by
`touch_outputs`, default `true`). This ensures that commands which are no-ops when
dependencies are already satisfied (e.g. `uv sync` when the venv is up to date) still
mark outputs as fresh, preventing repeated stale warnings on subsequent invocations.

## Auto-Prepare

When `auto = true` is set on a provider, it will automatically run before:

* `mise run` (task execution)
* `mise x` (exec command)

This ensures dependencies are always up-to-date before running tasks or commands.

To skip auto-prepare for a single invocation:

```bash
mise run --no-prepare build
mise x --no-prepare -- npm test
```

## Staleness Warnings

When using `mise activate`, mise will warn you if any auto-enabled providers have stale dependencies:

```
mise WARN prepare: npm may need update, run `mise prep`
```

This can be disabled with:

```toml
[settings]
status.show_prepare_stale = false
```

## CLI Usage

```bash
# Run all applicable prepare steps
mise prepare

# Run only a specific provider
mise prepare npm

# Show why a provider is fresh or stale
mise prepare npm --explain

# Show what would run without executing
mise prepare --dry-run

# Force run even if outputs are fresh
mise prepare --force

# List available prepare providers
mise prepare --list

# Skip specific providers
mise prepare --skip npm
```

## Dependencies

Providers can declare dependencies on other providers using the `depends` field. A provider
will wait for all its dependencies to complete successfully before running.

```toml
[prepare.uv]
auto = true

[prepare.ansible-galaxy]
auto = true
depends = ["uv"]
run = "ansible-galaxy install -f requirements.yml"
sources = ["requirements.yml"]
outputs = [".galaxy-installed"]
```

In this example, `ansible-galaxy` will wait for `uv` to finish before starting.

Providers without `depends` run in parallel as before. If a dependency fails, all providers
that depend on it are skipped. Circular dependencies are detected and the affected providers
are skipped with a warning.

## Parallel Execution

Prepare providers run in parallel, respecting the `jobs` setting for concurrency limits.
This speeds up preparation when multiple providers need to run (e.g., both npm and pip).
Providers with `depends` will wait for their dependencies to complete before starting,
while independent providers run concurrently.

```toml
[settings]
jobs = 4  # Run up to 4 providers in parallel
```

## Example: Full-Stack Project

```toml
# mise.toml for a project with Node.js frontend and Python backend

[prepare.npm]
auto = true

[prepare.poetry]
auto = true

[prepare.prisma]
auto = true
depends = ["npm"]  # needs node_modules first
sources = ["prisma/schema.prisma"]
outputs = ["node_modules/.prisma/"]
run = "npx prisma generate"

[prepare.frontend-codegen]
depends = ["npm"]  # needs node_modules first
sources = ["schema.graphql", "codegen.ts"]
outputs = ["src/generated/"]
run = "npm run codegen"
```

Running `mise prep` will install npm and poetry dependencies in parallel, then run prisma
and frontend-codegen (also in parallel, since they only depend on npm, not each other).

---

---
url: /mise-cookbook/presets.md
---
# Presets

You can create your own presets by leveraging [mise tasks](../tasks/index.md) to reduce boilerplate and make it easier to set up new projects.

## Example python preset

Here is an example of how to create your python preset that creates a `mise.toml` file to work with `python` and `pdm`

```shell [~/.config/mise/tasks/preset/python]
#!/usr/bin/env bash
#MISE dir="{{cwd}}"

mise use pre-commit
mise config set env._.python.venv.path .venv
mise config set env._.python.venv.create true -t bool
mise tasks add lint -- pre-commit run -a
```

```shell [~/.config/mise/tasks/preset/pdm]
#!/usr/bin/env bash
#MISE dir="{{cwd}}"
#MISE depends=["preset:python"]
#USAGE arg "<version>"

mise use python@${usage_version?}
mise use pdm@latest
mise config set hooks.postinstall "pdm sync"
```

Then in any directory, you can run `mise preset:pdm 3.10` to scaffold a new project with `python` and `pdm`:

```shell
cd my-project
mise preset:pdm 3.10
# [preset:python] $ ~/.config/mise/tasks/preset/python
# mise WARN  No untrusted config files found.
# mise ~/my-project/mise.toml tools: pre-commit@4.0.1
# [preset:pdm] $ ~/.config/mise/tasks/preset/pdm 3.10
# mise WARN  No untrusted config files found.
# mise ~/my-project/mise.toml tools: python@3.10.15
# mise ~/my-project/mise.toml tools: pdm@2.21.0
# mise creating venv with uv at: ~/my-project/.venv
# Using CPython 3.10.15 interpreter at: /Users/simon/.local/share/mise/installs/python/3.10.15/bin/python
# Creating virtual environment at: .venv
# Activate with: source .venv/bin/activate.fish

~/my-project via 🐍 v3.10.15 (.venv)
# we are in the virtual environment ^
```

Here is the generated `mise.toml` file:

```toml [mise.toml]
[tools]
pdm = "latest"
pre-commit = "latest"
python = "3.10"

[hooks]
postinstall = "pdm sync"

[env]
[env._]
[env._.python]
[env._.python.venv]
path = ".venv"
create = true

[tasks.lint]
run = "pre-commit run -a"
```

---

---
url: /lang/python.md
---
# Python

Like `pyenv`, `mise` can manage multiple versions of Python on the same system. Mise can also automatically create virtual environments for your projects and integrates with `uv`.

> The following are instructions for using the python mise core plugin. The core plugin will be used
> so long as no plugin is manually
> installed named "python" using `mise plugins install python [GIT_URL]`.

The code for this is inside of the mise repository
at [`./src/plugins/core/python.rs`](https://github.com/jdx/mise/blob/main/src/plugins/core/python.rs).

## Usage

The following installs the latest version of python-3.11.x and makes it the global
default:

```sh
mise use -g python@3.11
```

You can also use multiple versions of python at the same time:

```sh
$ mise use -g python@3.10 python@3.11
$ python -V
3.10.0
$ python3.11 -V
3.11.0
```

You can also install a specific python flavour. To get the latest version from a flavour just use the
flavour prefix.

```sh
mise use -g python@anaconda         # latest version of anaconda
```

See the [Python Cookbook](/mise-cookbook/python.html) for common tasks and examples.

## `.python-version` support

`.python-version`/`.python-versions` files are supported by mise. See [idiomatic version files](/configuration.html#idiomatic-version-files).

## Automatic virtualenv activation

Python comes with virtualenv support built in, use it with `mise.toml` configuration like
one of the following:

```toml
[tools]
python = "3.11" # [optional] will be used for the venv

[env]
_.python.venv = ".venv" # relative to this file's directory
_.python.venv = "/root/.venv" # can be absolute
_.python.venv = "{{env.HOME}}/.cache/venv/myproj" # can use templates
_.python.venv = { path = ".venv", create = true } # create the venv if it doesn't exist
_.python.venv = { path = ".venv", create = true, python = "3.10" } # use a specific python version
_.python.venv = {
  path = ".venv", create = true,
  python_create_args = ["--without-pip"], # pass args to python -m venv
}
_.python.venv = {
  path = ".venv", create = true,
  uv_create_args = ["--system-site-packages"], # pass args to uv venv
}
# Install seed packages (pip, setuptools, and wheel) into the virtual environment.
_.python.venv = { path = ".venv", create = true, uv_create_args = ['--seed'] }
```

The venv will need to be created manually with `python -m venv /path/to/venv` unless `create=true`.
See [env-directives](https://mise.jdx.dev/environments/#env-directives) for `_.python.venv`.

## mise & uv

If you have installed `uv` (for example, with `mise use -g uv@latest`), `mise` will use it to create virtual environments. Otherwise, it will use the built-in `python -m venv` command.

Note that `uv` does not include `pip` by default (as `uv` provides `uv pip` instead). If you need the `pip` package, add the `uv_create_args = ['--seed']` option.

:::warning
The `true` value for `python.uv_venv_auto` is considered legacy and will be deprecated in a
future release (planned for mise 2026.7). Prefer `"source"` or `"create|source"` instead.
Note: the `python.uv_venv_auto` **setting** itself is not going away — only the `true` value is
being phased out.
:::

One difference between the legacy `true` value and the newer string values is that `true` also
exports `UV_PYTHON` (set to just the Python version number). This tells `uv` which Python version
to use, but does not guarantee that `uv` uses the specific interpreter managed by `mise` — `uv`
may fall back to a system or self-managed Python of the same version.

To strictly ensure `uv` uses `mise`'s managed Python interpreter, set `UV_PYTHON` to the actual
install path instead:

```toml
[tools]
python = "3.12"

[env]
UV_PYTHON = { value = "{{ tools.python.path }}", tools = true }
```

See the [mise + uv Cookbook](/mise-cookbook/python.html#mise-uv) for more examples.

## Default Python packages

mise can automatically install a default set of Python packages with pip right after installing a
Python version. To enable this feature, provide a `$HOME/.default-python-packages` file that lists
one package per line, for example:

```text
ansible
pipenv
```

You can specify a non-default location of this file by setting a `MISE_PYTHON_DEFAULT_PACKAGES_FILE`
variable.

## Precompiled python binaries

By default, mise will
download [precompiled binaries](https://github.com/astral-sh/python-build-standalone)
for python instead of compiling them with python-build. This makes installing python much faster.

In addition to being faster, it also means you don't have to install all of the system dependencies
either.

That said, there are
some [quirks](https://github.com/astral-sh/python-build-standalone/blob/main/docs/quirks.rst)
with the precompiled binaries to be aware of.

If you'd like to disable these binaries, set `mise settings python.compile=1`.

These binaries may not work on older CPUs however you may opt into binaries which
are more compatible with older CPUs by setting `MISE_PYTHON_PRECOMPILED_ARCH` with
a different version. See <https://gregoryszorc.com/docs/python-build-standalone/main/running.html> for
more information
on this option. Set it to "x86\_64" for the most compatible binaries.

## python-build

Optionally, mise
uses [python-build](https://github.com/pyenv/pyenv/tree/master/plugins/python-build) (part of pyenv)
to compile python runtimes,
you need to ensure
its [dependencies](https://github.com/pyenv/pyenv/wiki#suggested-build-environment) are installed
before installing python with
python-build.

## Installing free-threaded python

Free-threaded python can be installed via python-build by running the following:

```bash
MISE_PYTHON_COMPILE=0 MISE_PYTHON_PRECOMPILED_FLAVOR=freethreaded+pgo-full mise install python
```

Or to compile with python-build:

```bash
MISE_PYTHON_COMPILE=1 PYTHON_BUILD_FREE_THREADING=1 mise install python
```

## Troubleshooting errors with Homebrew

If you normally use Homebrew and you see errors regarding OpenSSL,
your best bet might be using the following command to install Python:

```sh
CFLAGS="-I$(brew --prefix openssl)/include" \
LDFLAGS="-L$(brew --prefix openssl)/lib" \
mise install python@latest;
```

Homebrew installs its own OpenSSL version, which may collide with system-expected ones.
You could even add that to your
`.profile`,
`.bashrc`,
`.zshrc`...
to avoid setting them every time

Additionally, if you encounter issues with python-build,
you may benefit from unlinking pkg-config prior to install
([reason](https://github.com/pyenv/pyenv/issues/2823#issuecomment-1769081965)).

```sh
brew unlink pkg-config
mise install python@latest
brew link pkg-config
```

Thus the entire script would look like:

```sh
brew unlink pkg-config
CFLAGS="-I$(brew --prefix openssl)/include" \
  LDFLAGS="-L$(brew --prefix openssl)/lib" \
  mise install python@latest
brew link pkg-config
```

## Settings

`python-build` already has
a [handful of settings](https://github.com/pyenv/pyenv/tree/master/plugins/python-build), in
additional to that python in mise has a few extra configuration variables.

Set these with `mise settings set [VARIABLE] [VALUE]` or by setting the environment variable.

---

---
url: /registry.md
---

# Registry

List of all [tools](#tools) aliased by default in `mise`.

You can use these shorthands with `mise use`. This allows you to use a tool without needing to know the full name. For example, to use the `aws-cli` tool, you can do the following:

```shell
mise use aws-cli
```

instead of

```shell
mise use aqua:aws/aws-cli
```

If a tool is not available in the registry, you can install it by its full name. [github](./dev-tools/backends/github.html) and [aqua](./dev-tools/backends/aqua.html) give you for example access to almost all programs available on GitHub.

## Backends

In addition to built-in [core tools](/core-tools.html), `mise` supports a variety of [backends](/dev-tools/backends/) to install tools.

In general, the preferred [backend](/dev-tools/backends/) to use for new tools is the following:

* [aqua](./dev-tools/backends/aqua.html) - offers the most features and security while not requiring plugins
* [github](./dev-tools/backends/github.html) - for tools that are not available in the aqua registry, but are available on GitHub
* [gitlab](./dev-tools/backends/gitlab.html) - for tools that are not available in the aqua registry, but are available on GitLab
* [pipx](./dev-tools/backends/pipx.html) - only for python tools, requires python to be installed but this generally would always be the case for python tools
* [npm](./dev-tools/backends/npm.html) - only for node tools, requires node to be installed but this generally would always be the case for node tools
* [go](./dev-tools/backends/go.html) - only for go tools, requires go to be installed to compile. Because go tools can be distributed as a single binary, aqua/github are definitely preferred.
* [cargo](./dev-tools/backends/cargo.html) - only for rust tools, requires rust to be installed to compile. Because rust tools can be distributed as a single binary, aqua/github are definitely preferred.
* [dotnet](./dev-tools/backends/dotnet.html) - only for dotnet tools, requires dotnet to be installed to compile. Because dotnet tools can be distributed as a single binary, aqua/github are definitely preferred.

New vfox and asdf tools are almost never accepted for supply-chain security reasons.

### Backends Priority

Each tool can define its own priority if it has more than one backend it supports. If you would like to disable a backend, you can do so with the following command:

```shell
mise settings disable_backends=asdf
```

This will disable the [asdf](./dev-tools/backends/asdf.html) backend. See [Aliases](/dev-tools/aliases.html) for a way to set a default backend for a tool. Note that the `asdf` backend is disabled by default on Windows.

You can also specify the full name for a tool using `mise use aqua:1password/cli` if you want to use a specific backend.

### Environment Variable Overrides

You can override the backend for any tool using environment variables with the pattern `MISE_BACKENDS_<TOOL>`. This takes the highest priority and overrides any registry or alias configuration:

```shell
# Use vfox backend for php
export MISE_BACKENDS_PHP='vfox:mise-plugins/vfox-php'
mise install php@latest
```

The tool name in the environment variable should be in SHOUTY\_SNAKE\_CASE (uppercase with underscores). For example, `my-tool` becomes `MISE_BACKENDS_MY_TOOL`.

Source: <https://github.com/jdx/mise/blob/main/registry/>

## Tools {#tools}

Note that [`mise registry`](/cli/registry.html) can be used to list all tools in the registry. [`mise use`](/cli/use.html) without any arguments will show a `tui` to select a tool to install.

---

---
url: /lang/ruby.md
---
# Ruby

Like `rvm`, `rbenv`, or `asdf`, `mise` can manage multiple versions of [Ruby](https://www.ruby-lang.org/) on the same system.

> The following are instructions for using the ruby mise core plugin. This is used when there isn't a
> git plugin installed named "ruby". If you want to use [asdf-ruby](https://github.com/asdf-vm/asdf-ruby)
> then use `mise plugins install ruby GIT_URL`.

The code for this is inside the mise repository at
[`./src/plugins/core/ruby.rs`](https://github.com/jdx/mise/blob/main/src/plugins/core/ruby.rs).

## Usage

The following installs the latest version of ruby-3.2.x (if some version of 3.2.x is not already
installed) and makes it the global default:

```sh
mise use -g ruby@3.2
```

Behind the scenes, mise uses [`ruby-build`](https://github.com/rbenv/ruby-build) to compile ruby
from source. Ensure that you have the necessary
[dependencies](https://github.com/rbenv/ruby-build/wiki#suggested-build-environment) installed.
You can check its [README](https://github.com/rbenv/ruby-build/blob/master/README.md) for additional settings and some
troubleshooting.

## Precompiled Binaries

Mise can download precompiled Ruby binaries instead of
compiling from source. This significantly reduces installation time.

Precompiled binaries will become the default in 2026.8.0. To opt in now:

```sh
mise settings ruby.compile=false
mise use ruby@3.4.1
```

Precompiled binaries are sourced from [jdx/ruby](https://github.com/jdx/ruby) and are available
for the following platforms:

* macOS (arm64/Apple Silicon only)
* Linux arm64
* Linux x86\_64

If a precompiled binary is not available for your platform or Ruby version, mise automatically
falls back to compiling from source using ruby-build.

To always compile from source even when precompiled binaries are available:

```sh
mise settings ruby.compile=true
```

You can also use a custom source for precompiled binaries by setting `ruby.precompiled_url` to
either a GitHub repo (e.g., `owner/repo`) or a full URL template.

You can also install a specific ruby flavour. To get the latest version from a flavour, just use the
flavour prefix.

```sh
mise use -g ruby@truffleruby            # latest version of truffleruby
```

## Default gems

mise can automatically install a default set of gems right after installing a new ruby version.
To enable this feature, provide a `$HOME/.default-gems` file that lists one gem per line, for
example:

```text
# supports comments
pry
bcat ~> 0.6.0 # supports version constraints
rubocop --pre # install prerelease version
```

## `.ruby-version` and `Gemfile` support

mise uses a `mise.toml` or `.tool-versions` file for auto-switching between software versions.
However, it can also read ruby-specific version files `.ruby-version` or `Gemfile`
(if it specifies a ruby version).

Create a `.ruby-version` file for the current version of ruby:

```sh
ruby -v > .ruby-version
```

Enable idiomatic version file reading for ruby:

```sh
mise settings add idiomatic_version_file_enable_tools ruby
```

See [idiomatic version files](/configuration.html#idiomatic-version-files) for more information.

## Manually updating ruby-build

ruby-build should update daily, however if you find versions do not yet exist you can force an
update:

```bash
mise cache clean
mise ls-remote ruby
```

## Settings

`ruby-build` already has a
[handful of settings](https://github.com/rbenv/ruby-build?tab=readme-ov-file#custom-build-configuration),
in additional to that mise has a few extra settings:

---

---
url: /tasks/running-tasks.md
---
# Running Tasks

See available tasks with `mise tasks`. To show tasks hidden with property `hide=true`, use the option `--hidden`.

List dependencies of tasks with `mise tasks deps [tasks]...`.

Run a task with `mise tasks run <task>`, `mise run <task>`, `mise r <task>`, or just `mise <task>`—however
that last one you should never put into scripts or documentation because if mise ever adds a command with that name in a
future mise version, the task will be shadowed and must be run with one of the other forms.

Most mise users will have an alias for `mise run` like `alias mr='mise run'`.

By default, tasks will execute with a maximum of 4 parallel jobs. Customize this with the `--jobs` option,
`jobs` setting or `MISE_JOBS` environment variable. The output normally will be by line, prefixed with the task
label. By printing line-by-line we avoid interleaving output from parallel executions. However, if
\--jobs == 1, the output will be set to `interleave`.

To just print stdout/stderr directly, use `--interleave`, the `task.output` setting, or `MISE_TASK_OUTPUT=interleave`.

Stdin is not read by default. To enable this, set `raw = true` on the task that needs it. This will prevent
it running in parallel with any other task—a RWMutex will get a write lock in this case. This also prevents redactions applied to the output.

Extra arguments will be passed to the task, for example, if we want to run in release mode:

```bash
mise run build --release
```

If there are multiple commands, the args are only passed to the last command.

:::tip
You can define arguments/flags for tasks which will provide validation, parsing, autocomplete, and documentation.

* [Arguments in File Tasks](/tasks/file-tasks#arguments)
* [Arguments in TOML Tasks](/tasks/toml-tasks#arguments)

Autocomplete will work automatically for tasks if the `usage` CLI is installed and mise completions are working.

Markdown documentation can be generated with [`mise generate task-docs`](/cli/generate/task-docs).
:::

Multiple tasks/arguments can be separated with this `:::` delimiter:

```bash
mise run build arg1 arg2 ::: test arg3 arg4
```

mise will run the task named "default" if no task is specified—and you've created one named "default". You can also alias a different task to "default".

```bash
mise run
```

## Task Grouping

Tasks can be grouped semantically by using name prefixes separated with `:`s.
For example all testing related tasks may begin with `test:`. Nested grouping
can also be used to further refine groups and simplify pattern matching.
For example running `mise run test:**:local` will match`test:units:local`,
`test:integration:local` and `test:e2e:happy:local`
(See [Wildcards](#wildcards) for more information).

## Wildcards

Glob style wildcards are supported when running tasks or specifying tasks
dependencies.

Available Wildcard Patterns:

* `?` matches any single character
* `*` matches 0 or more characters
* `**` matches 0 or more groups
* `{glob1,glob2,...}` matches any of the comma-separated glob patterns
* `[ab,...]` matches any of the characters or ranges `[a-z]`
* `[!ab,...]` matches any character not in the character set

### Examples

`mise run generate:{completions,docs:*}`

And with dependencies:

```toml
[tasks."lint:eslint"] # using a ":" means we need to add quotes
run = "eslint ."
[tasks."lint:prettier"]
run = "prettier --check ."
[tasks.lint]
depends = ["lint:*"]
wait_for = ["render"] # does not add as a dependency, but if it is already running, wait for it to finish
```

## Running on file changes

It's often handy to only execute a task if the files it uses changes. For example, we might only want
to run `cargo build` if an ".rs" file changes. This can be done with the following config:

```toml
[tasks.build]
description = 'Build the CLI'
run = "cargo build"
sources = ['Cargo.toml', 'src/**/*.rs'] # skip running if these files haven't changed
outputs = ['target/debug/mycli']
```

Now if `target/debug/mycli` is newer than `Cargo.toml` or any ".rs" file, the task will be skipped. This uses last modified timestamps.
It wouldn't be hard to add checksum support.

## Watching files

Run a task when the source changes with [`mise watch`](/cli/watch.html)

```bash
mise watch build
```

Currently, this just shells out to `watchexec` (which you can install however you want including with mise: `mise use -g watchexec@latest`.
This may change in the future.)

## `mise run` shorthand

Tasks can be run with `mise run <TASK>` or `mise <TASK>`—if the name doesn't conflict with a mise command.
Because mise may later add a command with a conflicting name, it's recommended to use `mise run <TASK>` in
scripts and documentation.

## Execution order

You can use [depends](/tasks/task-configuration.html#depends), [wait\_for](/tasks/task-configuration.html#wait-for) and [depends\_post](/tasks/task-configuration.html#depends-post) to control the order of execution.

```toml
[tasks.build]
run = "echo 'build'"

[tasks.test]
run = "echo 'test'"
depends = ["build"]
```

This will ensure that the `build` task is run before the `test` task.

You can also define a mise task to run other tasks in parallel or in series:

```toml
[tasks.example1]
run = "echo 'example1'"

[tasks.example2]
run = "mise example2"

[tasks.example3]
run = "echo 'example3'"

[tasks.one_by_one]
run = [
    { task = "example1" }, # will wait for example1 to finish before running the next step
    { tasks = ["example2", "example3"] }, # these 2 are run in parallel
]
```

---

---
url: /lang/rust.md
---
# Rust

Rust/cargo can be installed which uses rustup under the hood. mise will install rustup if it is not already
installed and add the requested targets. By default, mise respects the `RUSTUP_HOME` and `CARGO_HOME` environment
variables for the home directories and falls back to their standard location (`~/.rustup` and `~/.cargo`) if they are
not set. You can change this by setting the `MISE_RUSTUP_HOME` and `MISE_CARGO_HOME` environment variables if you'd like
to isolate mise's rustup/cargo from your other rustup/cargo installations.

Unlike most tools, these won't exist inside of `~/.local/share/mise/installs` because they are managed by rustup.
All mise does is set the `RUSTUP_TOOLCHAIN` environment variable to the requested version and rustup will
automatically install it if it doesn't exist.

## Usage

Use the latest stable version of rust:

```sh
mise use -g rust
cargo build
```

Use the latest beta version of rust:

```sh
mise use -g rust@beta
cargo build
```

Use a specific version of rust:

```sh
mise use -g rust@1.82
cargo build
```

## Tool Options

The following [tool-options](/dev-tools/#tool-options) are available for the `rust` backend—these
go in `[tools]` in `mise.toml`.

### `components`

The `components` option allows you to specify which components to install. Multiple components can be
specified by separating them with a comma. The set of available components may vary with different releases and
toolchains. Please consult the Rust documentation for the most up-to-date list of components.

```toml
[tools]
"rust" = { version = "1.83.0", components = "rust-src,llvm-tools" }
```

### `profile`

The `profile` option allows you to specify the type of release to install. The following values
are supported:

* `minimal`: Includes as few components as possible to get a working compiler (`rustc`, `rust-std`, and `cargo`)
* `default`: Includes all of the components in the minimal profile, and adds `rust-docs`, `rustfmt`, and `clippy`
* `complete`: Includes all the components available through `rustup`. This should never be used, as it includes every component ever included in the metadata and thus will almost always fail.

If not set, it defaults to the profile configured in `rustup`. You can check your current default by running `rustup show profile`.

```toml
[tools]
"rust" = { version = "1.83.0", profile = "minimal" }
```

### `targets`

The `targets` option allows you to specify a list of platforms to install for cross-compilation. Multiple targets can
be specified by separating them with a comma.

```toml
[tools]
"rust" = {
  version = "1.83.0",
  targets = "wasm32-unknown-unknown,thumbv2-none-eabi",
}
```

## Settings

---

---
url: /dev-tools/backends/s3.md
---
# S3 Backend&#x20;

You may install tools directly from Amazon S3 or S3-compatible storage (like MinIO) using the `s3` backend. This backend is ideal for enterprise teams hosting proprietary tools in private S3 buckets.

The code for this is inside of the mise repository at [`./src/backend/s3.rs`](https://github.com/jdx/mise/blob/main/src/backend/s3.rs).

::: warning
The S3 backend is experimental and requires `experimental = true` in your mise settings.
:::

## Usage

The following installs a tool from an S3 bucket:

```sh
mise use -g "s3:my-tool[url=s3://my-bucket/tools/my-tool-v1.0.0.tar.gz]@1.0.0"
```

The version will be set in `~/.config/mise/config.toml` with the following format:

```toml
[tools]
"s3:my-tool" = { version = "1.0.0", url = "s3://my-bucket/tools/my-tool-v1.0.0.tar.gz" }
```

## Authentication

The S3 backend uses the AWS SDK default credential chain. Credentials are loaded from (in order):

1. Environment variables: `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`
2. AWS credentials file: `~/.aws/credentials`
3. IAM roles (when running on AWS infrastructure)

```sh
# Set credentials via environment variables
export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export AWS_DEFAULT_REGION="us-east-1"

mise install
```

## Tool Options

The following [tool-options](/dev-tools/#tool-options) are available for the `s3` backend—these
go in `[tools]` in `mise.toml`.

### `url` (Required)

Specifies the S3 URL to download the tool from. The URL supports templating with `{{ version }}`:

```toml
[tools]
"s3:my-tool" = { version = "1.0.0", url = "s3://my-bucket/tools/my-tool-v{{ version }}.tar.gz" }
```

### `endpoint`

Specify a custom S3-compatible endpoint for services like MinIO, DigitalOcean Spaces, or self-hosted S3:

```toml
[tools."s3:my-tool"]
version = "1.0.0"
url = "s3://my-bucket/tools/my-tool-v{{ version }}.tar.gz"
endpoint = "http://minio.internal:9000"
```

### `region`

Specify the AWS region for the S3 bucket:

```toml
[tools."s3:my-tool"]
version = "1.0.0"
url = "s3://my-bucket/tools/my-tool-v{{ version }}.tar.gz"
region = "us-west-2"
```

### Platform-specific URLs

For tools that need different downloads per platform, use the table format:

```toml
[tools."s3:my-tool"]
version = "1.0.0"

[tools."s3:my-tool".platforms]
macos-x64 = { url = "s3://my-bucket/tools/my-tool-v1.0.0-macos-x64.tar.gz" }
macos-arm64 = { url = "s3://my-bucket/tools/my-tool-v1.0.0-macos-arm64.tar.gz" }
linux-x64 = { url = "s3://my-bucket/tools/my-tool-v1.0.0-linux-x64.tar.gz" }
```

### `checksum`

Verify the downloaded file with a checksum:

```toml
[tools."s3:my-tool"]
version = "1.0.0"
url = "s3://my-bucket/tools/my-tool-v1.0.0.tar.gz"
checksum = "sha256:a1b2c3d4e5f6789..."
```

*Instead of specifying the checksum here, you can use [mise.lock](/dev-tools/mise-lock) to manage checksums.*

### `bin_path`

Specify the directory containing binaries within the extracted archive:

```toml
[tools."s3:my-tool"]
version = "1.0.0"
url = "s3://my-bucket/tools/my-tool-v1.0.0.tar.gz"
bin_path = "my-tool-{{ version }}/bin"
```

### `format`

Explicitly specify the archive format when the URL lacks a file extension:

```toml
[tools."s3:my-tool"]
version = "1.0.0"
url = "s3://my-bucket/tools/my-tool-v1.0.0"
format = "tar.gz"
```

## Version Discovery

The S3 backend supports two methods for discovering available versions.

### Manifest File

Fetch available versions from a JSON manifest file stored in S3:

```toml
[tools."s3:my-tool"]
version = "latest"
url = "s3://my-bucket/tools/my-tool-v{{ version }}.tar.gz"
version_list_url = "s3://my-bucket/tools/versions.json"
```

The manifest file can be a JSON array of version strings:

```json
["1.0.0", "1.1.0", "2.0.0"]
```

Or a JSON array of objects (use `version_json_path` to extract versions):

```json
[{ "version": "1.0.0" }, { "version": "1.1.0" }, { "version": "2.0.0" }]
```

### `version_json_path`

Extract versions from JSON responses using a jq-like path expression:

```toml
[tools."s3:my-tool"]
version = "latest"
url = "s3://my-bucket/tools/my-tool-v{{ version }}.tar.gz"
version_list_url = "s3://my-bucket/tools/releases.json"
version_json_path = ".[].version"
```

### `version_expr`

Extract versions using an [expr-lang](https://expr-lang.org/) expression for complex version extraction logic:

```toml
[tools."s3:my-tool"]
version = "latest"
url = "s3://my-bucket/tools/my-tool-v{{ version }}.tar.gz"
version_list_url = "s3://my-bucket/tools/versions.txt"
version_expr = 'split(body, "\n")'
```

The expression receives the response body as the `body` variable and should return an array of version strings.

### S3 Object Listing

Discover versions by listing objects in the S3 bucket:

```toml
[tools."s3:my-tool"]
version = "latest"
url = "s3://my-bucket/tools/my-tool-v{{ version }}.tar.gz"
version_prefix = "tools/my-tool-v"
version_regex = "my-tool-v([0-9.]+)"
```

* `version_prefix`: The S3 key prefix to list objects from
* `version_regex`: A regular expression to extract version numbers from object keys (first capturing group is used)

## Custom Endpoint Example (MinIO)

Here's a complete example using MinIO as an S3-compatible backend:

```toml
[tools."s3:my-internal-tool"]
version = "latest"
url = "s3://tools-bucket/releases/my-tool-{{ version }}.tar.gz"
endpoint = "http://minio.internal:9000"
region = "us-east-1"
version_list_url = "s3://tools-bucket/releases/versions.json"
bin_path = "bin"
```

With environment variables:

```sh
export AWS_ACCESS_KEY_ID="minio-access-key"
export AWS_SECRET_ACCESS_KEY="minio-secret-key"
mise install
```

## Comparison with HTTP Backend

| Feature           | S3 Backend                                          | HTTP Backend      |
| ----------------- | --------------------------------------------------- | ----------------- |
| Authentication    | AWS credentials (env vars, ~/.aws/credentials, IAM) | HTTP auth headers |
| Version discovery | S3 listing or manifest file                         | HTTP endpoint     |
| Custom endpoints  | Yes (MinIO, etc.)                                   | N/A               |
| Use case          | Private/enterprise tools                            | Public downloads  |

---

---
url: /environments/secrets.md
---
# Secrets

Use mise to manage sensitive environment variables securely. There are multiple supported approaches:

* **[fnox](https://github.com/jdx/fnox)**  — Full-featured secret manager with remote secret storage (e.g.: 1Password, AWS Secrets Manager) and remote encryption (e.g.: AWS KMS). This is a separate project by @jdx that works well alongside mise. There's no direct integration with mise and fnox, you set it up separately.
* [sops](/environments/secrets/sops)  — Encrypt entire files and load them via `env._.file`
* [Direct age encryption](/environments/secrets/age)  — Encrypt individual env vars inline in `mise.toml`

---

---
url: /configuration/settings.md
---
# Settings

The following is a list of all of mise's settings. These can be set via `mise settings key=value`,
by directly modifying `~/.config/mise/config.toml` or local config, or via environment variables.

Some of them also can be set via global CLI flags.

---

---
url: /shell-aliases.md
---
# Shell Aliases

mise can manage shell aliases that are set dynamically when you enter a directory and unset when you leave, similar to how environment variables work.

## Configuration

Shell aliases are defined in `mise.toml` under the `[shell_alias]` section:

```toml
[shell_alias]
ll = "ls -la"
la = "ls -A"
gs = "git status"
gc = "git commit"
```

When you enter a directory with this configuration, these aliases will be automatically set in your shell. When you leave the directory (and the new directory doesn't have the same aliases), they will be unset.

## Supported Shells

Shell aliases are currently supported in:

* **bash** - Uses `alias`/`unalias` commands
* **zsh** - Uses `alias`/`unalias` commands
* **fish** - Uses `alias`/`functions -e` commands

Other shells (nushell, elvish, xonsh, powershell) do not currently support shell aliases.

## Dynamic Behavior

Shell aliases work similarly to environment variables managed by mise:

1. **Set on entry**: When you `cd` into a directory with `[shell_alias]` config, the aliases are set
2. **Updated on change**: If an alias value changes in your config, it will be updated
3. **Unset on exit**: When you leave the directory (or the alias is removed from config), it will be unset

```bash
$ cd ~/myproject
# mise sets: alias ll='ls -la'

$ ll
# Runs: ls -la

$ cd ~
# mise runs: unalias ll
```

## Hierarchy

Like other mise config, shell aliases from parent directories are available in child directories. A child directory can override a parent's alias:

```toml
# ~/projects/mise.toml
[shell_alias]
build = "make build"

# ~/projects/myapp/mise.toml
[shell_alias]
build = "npm run build"  # Overrides parent
```

## Templates

Alias values support [templates](/templates), allowing dynamic values:

```toml
[shell_alias]
proj = "cd {{config_root}}"
node_version = "echo {{exec(command='node --version')}}"
```

## Use Cases

### Project-Specific Shortcuts

Define shortcuts that only make sense within a specific project:

```toml
[shell_alias]
dev = "npm run dev"
test = "npm test"
build = "npm run build"
deploy = "./scripts/deploy.sh"
```

### Tool Wrappers

Create aliases that wrap tools with project-specific defaults:

```toml
[shell_alias]
docker-compose = "docker compose -f docker-compose.dev.yml"
terraform = "terraform -chdir=./infrastructure"
```

### Quick Navigation

```toml
[shell_alias]
src = "cd {{config_root}}/src"
tests = "cd {{config_root}}/tests"
docs = "cd {{config_root}}/docs"
```

## Comparison to Tool Aliases

mise has two different alias features that serve different purposes:

| Feature           | Purpose                                                | Config Key      |
| ----------------- | ------------------------------------------------------ | --------------- |
| **Shell Aliases** | Define shell command shortcuts (`alias ll='ls -la'`)   | `[shell_alias]` |
| **Tool Aliases**  | Define version aliases for tools (`node@lts` → `20.x`) | `[tool_alias]`  |

See [Tool Aliases](/dev-tools/aliases) for documentation on aliasing tool versions.

---

---
url: /mise-cookbook/shell-tricks.md
---
# Shell tricks

A collection of shell utities leveraging mise.

## Prompt colouring

In ZSH to set the prompt colour whenever mise updates the environment (e.g. on cd into a project, or due to modification of the .mise\*.toml):

```shell
# activate mise like normal
source <(command mise activate zsh)

typeset -i _mise_updated

# replace default mise hook
function _mise_hook {
  local diff=${__MISE_DIFF}
  source <(command mise hook-env -s zsh)
  [[ ${diff} == ${__MISE_DIFF} ]]
  _mise_updated=$?
}

_PROMPT="❱ "  # or _PROMPT=${PROMPT} to keep the default

function _prompt {
  if (( ${_mise_updated} )); then
    PROMPT='%F{blue}${_PROMPT}%f'
  else
    PROMPT='%(?.%F{green}${_PROMPT}%f.%F{red}${_PROMPT}%f)'
  fi
}

add-zsh-hook precmd _prompt
```

Now, when mise makes any updates to the environment the prompt will go blue.

## Current configuration environment in powerline-go prompt

[powerline-go](https://github.com/justjanne/powerline-go)'s
`shell-var` segment can be used to display the value of an environment
variable in the prompt.
The current mise [configuration environment](/configuration/environments),
`MISE_ENV` is a good candidate for this.

Mostly, it is as one would expect: include `shell-var` in `-modules`,
and `-shell-var MISE_ENV -shell-var-no-warn-empty` in arguments,
and make sure `MISE_ENV` is exported so `powerline-go` can "see" it.

A gotcha as of February 2025 is that the `shell-var` module does not
tolerate *unset* (as opposed to empty) environment variables.
To work around this, set `MISE_ENV` to an empty value early in the shell
startup scripts, and avoid manually `unset`ing it.
For example for bash, typically in `~/.bashrc`:

```bash
export MISE_ENV=
```

## Inspect what changed after mise hook

Using record-query you can inspect the `__MISE_DIFF` and `__MISE_SESSION` variables to see what's changing in your environment due to the mise hook.

```toml [~/.config/mise/config.toml]
[tools]
"cargo:record-query" = "latest"
```

```shell
function mise_parse_env {
  rq -m < <(
    zcat -q < <(
      printf $'\x1f\x8b\x08\x00\x00\x00\x00\x00'
      base64 -d <<< "$1"
    )
  )
}
```

```shell
$ mise_parse_env "${__MISE_DIFF}"
{
  "new": {
    ...
  },
  "old": {
    ...
  },
  "path": [
    ...
  ]
}
```

---

---
url: /dev-tools/shims.md
---
# Shims

There are several ways for the `mise` context (dev tools, environment variables) to be loaded into your shell:

* `mise activate` (also called ["mise PATH activation"](#path-activation)) where `mise` updates your `PATH` and other environment variables every time your prompt is displayed.
* [`mise activate --shims`](#mise-activate-shims) which uses shims to load dev tools.
* Using [`mise x|exec`](/cli/exec) or [`mise r|run`](/cli/run) for ad-hoc commands or tasks (see ["neither shims nor PATH"](#neither-shims-nor-path)).

This page will help you understand the differences between these methods and how to use them. In particular, it will help you decide if you should use shims or `mise activate` in your shell.

## Overview of the `mise` activation methods {#overview}

### PATH activation {#path-activation}

Mise's "PATH" activation method updates environment variables every time the prompt is displayed. In particular, it updates the `PATH` environment variable, which is used by your shell to search for the programs it can run.

::: info
This is the method used when you add the `echo 'eval "$(mise activate bash)"' >> ~/.bashrc` line to your shell rc file (in this case, for bash).
:::

For example, by default, your `PATH` variable might look like this:

```sh
echo $PATH
/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
```

If using [`mise activate`](/cli/activate.html), `mise` will automatically add the required tools to `PATH`.

```sh
PATH="$HOME/.local/share/mise/installs/python/3.13.0/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
```

In this example, the python `bin` directory was added at the beginning of the `PATH`, making it available in the current shell session.

While the `PATH` design of `mise` works great in most cases, there are some situations where `shims` are preferable. This is the case when you are not using an interactive shell (for example, when using `mise` in an IDE or a script).

### Shims {#mise-activate-shims}

::: warning
`mise activate --shims` does not support all the features of `mise activate`.
See [shims vs path](/dev-tools/shims.html#shims-vs-path) for more information.
:::

When using shims, `mise` places small executables (`shims`) in a directory that is included in your `PATH`. You can think of `shims` as symlinks to the mise binary that intercept commands and load the appropriate context.

```sh
ls -l ~/.local/share/mise/shims/node
# [...] ~/.local/share/mise/shims/node -> ~/.local/bin/mise
```

By default, the shim directory is located at `~/.local/share/mise/shims`. When installing a tool (for example, `node`), `mise` will add some entries for every binary provided by this tool in the `shims` directory (for example, `~/.local/share/mise/shims/node`).

```sh
mise use -g node@20
npm install -g prettier@3.1.0

~/.local/share/mise/shims/node -v
# v20.0.0
~/.local/share/mise/shims/prettier -v
# 3.1.0
```

To avoid calling `~/.local/share/mise/shims/node`, you can add the `shims` directory to your `PATH`.

```sh
export PATH="$HOME/.local/share/mise/shims:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
```

This will effectively make all dev tools available in your current shell session as well as non-interactive environments.

::: tip
[`mise activate --shims`](/cli/activate.html#shims) is a shorthand for adding the shims directory to PATH.
:::

## How to add mise shims to PATH

The recommended way to add `shims` to `PATH` is to call [`mise activate --shims`](/cli/activate.html#shims) in one of your shell initialization file. For example, you can do the following:

::: code-group

```sh [bash]
# note that bash will read from ~/.profile or ~/.bash_profile if the latter exists
# ergo, you may want to check to see which is defined on your system and only append to the existing file
echo 'eval "$(mise activate bash --shims)"' >> ~/.bash_profile # this sets up non-interactive sessions
echo 'eval "$(mise activate bash)"' >> ~/.bashrc       # this sets up interactive sessions
```

```sh [zsh]
echo 'eval "$(mise activate zsh --shims)"' >> ~/.zprofile # this sets up non-interactive sessions
echo 'eval "$(mise activate zsh)"' >> ~/.zshrc    # this sets up interactive sessions
```

```sh [fish]
echo 'mise activate fish --shims | source' >> ~/.config/fish/config.fish
echo 'mise activate fish | source' >> ~/.config/fish/fish.config
```

:::

In this example, we use [`mise activate --shims`](/cli/activate.html#shims) in the non-interactive shell configuration file (like `.bash_profile` or `.zprofile`) and `mise activate` in the interactive shell configuration file (like `.bashrc` or `.zshrc`)

::: info
[`mise activate`](/cli/activate.html) will remove the shims directory from the `PATH` so it's fine
to call [`mise activate --shims`](/cli/activate.html#shims) in your shell profile file then later call `mise activate` in an interactive session.
:::

* You can also decide to use only `shims` if you prefer, though this comes with some [limitations](/dev-tools/shims.html#shims-vs-path).
* An alternative to [`mise activate --shims`](/cli/activate.html#shims) is to use `export PATH="$HOME/.local/share/mise/shims:$PATH"`. This can be helpful if `mise` is not yet available at that point in time.

### mise reshim

To force `mise` to update the content of the `shims` directory, you can manually call `mise reshim`.

Note that `mise` already runs a reshim anytime a tool is installed/updated/removed, so you don't need to use it for those scenarios. It is also done by default when using most tools such as `npm`.

`mise reshim` only creates/removes the shims. Some users sometimes use it as a
"fix it" button, but it is only necessary if `~/.local/share/mise/shims` doesn't contain something it should.

Do not add additional executable in the `mise` directory, `mise` will delete them with the next reshim.

## Shims vs PATH {#shims-vs-path}

The following features are affected when shims are used **instead** of [PATH activation](#path-activation):

* [Env vars](/environments/) defined in mise are only available to mise tools
* Most [hooks](/hooks.html) won't trigger
* The unix `which` command points to the shim, obscuring the real executable

In general, using PATH (`mise activate`) instead of shims for *interactive* situations is recommended.

The way `activate` works is every time the prompt is displayed, mise-en-place will determine what PATH and other
env vars should be and export them. This is why it doesn't work well for non-interactive situations like scripts. The prompt never gets displayed so you have to manually call `mise hook-env` to get mise to update
the env vars. (though there are exceptions, see [hook on `cd`](#hook-on-cd))

### Env vars and shims

A downside of shims is that the environment variables are only loaded when a shim is called. This means if you
set an [environment variable](/environments/) in `mise.toml`, it will only be used when a shim is called.

The following example only works under `mise activate`:

```sh
$ mise set NODE_ENV=production
$ echo $NODE_ENV
production
```

But this will work in either:

```sh
$ mise set NODE_ENV=production
$ node -p process.env.NODE_ENV
production
```

Also, [`mise x|exec`](/cli/exec.html) and [`mise r|run`](/cli/run.html) can be used to get the environment even if you don't need any mise tools:

```sh
$ mise set NODE_ENV=production
$ mise x -- bash -c "echo \$NODE_ENV"
production
$ mise r some_task_that_uses_NODE_ENV
production
```

::: tip
In general, [tasks](/tasks/) are a good way to ensure that the mise environment is always loaded.
:::

### Hooks and shims

The [hooks](/hooks.html) `cd`, `enter`, `exit`, and `watch_files` only trigger with `mise activate`. However `preinstall` and `postinstall` still work with shims because they don't require shell integration.

### `which`

`which` is a command that a lot of users find great value in. Using shims effectively "break" `which` and cause it to show the location of the shim. A workaround is to use `mise which`, which will show the actual location. Some users prefer the "cleanliness" of running `which node` and getting back a real path with a version number inside of it. e.g:

```sh
$ which node
~/.mise/installs/node/20/bin/node
```

### Performance

Truthfully, you're probably not going to notice a difference in performance when using shims vs. using `mise activate`.

* Since mise runs every time the prompt is displayed with `mise activate`, you'll pay a few ms cost
  every time the prompt is displayed. Regardless of whether you're actively using a mise tool, you'll
  pay that penalty every time you run any command. It does have some short-circuiting logic to make it faster
  if there are no changes, but it doesn't help much unless you have a very complex setup.
* shims have basically the same performance profile but run when the shim is called. This makes some situations
  better, and some worse.

If you are calling a shim from within a bash script like this:

```sh
for i in {1..500}; do
    node script.js
done
```

You'll pay the mise penalty every time you call it within the loop. However, if you did the same thing
but call a subprocess from within a shim (say, node creating a node subprocess), you will *not* pay a new
penalty. This is because when a shim is called, mise sets up the environment with PATH for all tools and
those PATH entries will be before the shim directory.

In other words, which is better in terms of performance just depends on how you're calling mise. Really
though most users will not notice a few ms lag on their terminal caused by `mise activate`.

The only difference between these would be that using `hook-env` you will need to call
it again if you change directories but with shims that won't be necessary. The shims directory will be
removed by `mise activate` automatically so you won't need to worry about dealing with shims in your PATH.

## Neither shims nor PATH {#neither-shims-nor-path}

There are many ways to load the mise environment that don't require either, chiefly:
[`mise x|exec`](/cli/exec.html), [`mise r|run`](/cli/run.html) or [`mise en`](/cli/en.html).

These will both load all the tools and env vars before executing something. This might
be ideal because you don't need to modify your shell rc file at all and the environment is always loaded
explicitly. Some might find this is a "clean" way of working.

The obvious downside is that anytime one wants to use `mise` they need to prefix it with `mise exec|run`. Though, you can easily alias them to `mx|mr`.

* This is what one prefers if they like things to be precise over "easy".
* Or perhaps if you're just wanting to use mise on a single project because that's what your team uses and prefer
  not to use it to manage anything else on your system. Using a shell extension for that use-case
  would be overkill.

::: info This is the method Jeff uses

> Part of the reason for this is I often need to make sure I'm on my development version of mise. If you
> work on mise yourself I would recommend working in a similar way and disabling `mise activate` or shims
> while you are working on it.
>
> See [How I use mise](https://mise.jdx.dev/how-i-use-mise.html) for more information.

:::

## Hook on `cd` {#hook-on-cd}

For some shells (`bash`, `zsh`, `fish`, `xonsh`), `mise` hooks into the `cd` command, while in others, it only runs when the prompt is displayed. This relies on `chpwd` in `zsh`, `PROMPT_COMMAND` in `bash`, `fish_prompt` in `fish`, and `on_chdir` in `xonsh`.

The upside is that it doesn't run as frequently but since mise is written in Rust the cost for executing
mise is negligible (a few ms).

::: details Running several commands in a single line

If you run a set of commands in a single line like the following:

```sh
cd ~
cd ~/src/proj1 && node -v && cd ~/src/proj2 && node -v
```

If using `mise activate`, in shell without hook on cd, this will use the tools from `~`, not from `~/src/proj1` or `~/src/proj2` even after the directory changed.

This is because, in these shells `mise` runs just before your prompt gets displayed whereas in others, it hooks on `cd`. Note that shims *will* always work with the inline example above.

:::

## Using mise in rc files

rc files like `.zshrc` are unusual. It's a script but also runs only for interactive sessions. If you need
to access tools provided by mise inside of an rc file you have 2 options:

::: code-group

```sh [hook-env]
eval "$(mise activate zsh)"
eval "$(mise hook-env -s zsh)"
node some_script.js
```

```sh [shims]
eval "$(mise activate zsh --shims)" # should be first
eval "$(mise activate zsh)"
node some_script.js
```

:::

---

---
url: /environments/secrets/sops.md
---
# sops&#x20;

mise reads encrypted secret files and makes values available as environment variables via `env._.file`.

* **Formats**: `.env.json`, `.env.yaml`, `.env.toml`
* **Encryption**: [sops](https://getsops.io) backed by [age](https://github.com/FiloSottile/age)

## Example

```json
{
  "AWS_ACCESS_KEY_ID": "AKIAIOSFODNN7EXAMPLE",
  "AWS_SECRET_ACCESS_KEY": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}
```

```toml [mise.toml]
[env]
_.file = ".env.json"
```

mise will automatically decrypt the file if it is sops-encrypted.

## Encrypt with sops

:::: info
Currently age is the only sops encryption method supported.
::::

1. Install tools: `mise use -g sops age`

2. Generate an age key and note the public key:

```sh
age-keygen -o ~/.config/mise/age.txt
# Public key: <public key>
```

3. Encrypt the file:

```sh
sops encrypt -i --age "<public key>" .env.json
```

:::: tip
The `-i` overwrites the file. The encrypted file is safe to commit. Set `SOPS_AGE_KEY_FILE=~/.config/mise/age.txt` or `MISE_SOPS_AGE_KEY_FILE=~/.config/mise/age.txt` to decrypt/edit with sops.
::::

4. Reference it in config:

```toml
[env]
_.file = ".env.json"
```

Now `mise env` exposes the values.

## Environment Variables

mise supports both mise-specific environment variables and standard SOPS ones:

**Mise-specific variables (highest priority):**

* `MISE_SOPS_AGE_KEY` - Age private key content directly
* `MISE_SOPS_AGE_KEY_FILE` - Path to age private key file

**Standard SOPS variables (fallback):**

* `SOPS_AGE_KEY_FILE` - Path to age private key file
* `SOPS_AGE_KEY` - Age private key content directly

**Precedence order:**

1. `MISE_SOPS_AGE_KEY` (mise setting or env var, checked first)
2. `MISE_SOPS_AGE_KEY_FILE` or `sops.age_key_file` (mise setting or env var)
3. `SOPS_AGE_KEY_FILE` (standard)
4. `SOPS_AGE_KEY` (standard, direct key content)
5. Default: `~/.config/mise/age.txt`

This allows you to override SOPS settings specifically for mise while keeping your standard SOPS configuration intact for other tools.

## Redaction

Mark secrets from files as sensitive:

```toml
[env]
_.file = { path = ".env.json", redact = true }
```

Work with redacted values:

```bash
mise env --redacted
mise env --redacted --values
```

### CI masking (GitHub Actions)

```yaml
- name: Mask secrets
  run: |
    for value in $(mise env --redacted --values); do
      echo "::add-mask::$value"
    done
- name: Use secrets safely
  run: |
    mise exec -- ./deploy.sh
```

If you use [mise-action](https://github.com/jdx/mise-action), values marked `redact = true` are masked automatically.

## Settings

---

---
url: /dev-tools/backends/spm.md
---
# SPM Backend&#x20;

You may install executables managed by [Swift Package Manager](https://www.swift.org/documentation/package-manager) directly from GitHub or GitLab releases.

The code for this is inside of the mise repository at [`./src/backend/spm.rs`](https://github.com/jdx/mise/blob/main/src/backend/spm.rs).

## Dependencies

This relies on having `swift` installed. You can either install it [manually](https://www.swift.org/install) or [with mise](/lang/swift).

> \[!NOTE]
> If you have Xcode installed and selected in your system via `xcode-select`, Swift is already available through the toolchain embedded in the Xcode installation.

## Usage

The following installs the latest version of `tuist`
and sets it as the active version on PATH:

```sh
$ mise use -g spm:tuist/tuist
$ tuist --help
OVERVIEW: Generate, build and test your Xcode projects.

USAGE: tuist <subcommand>
...
```

The version will be set in `~/.config/mise/config.toml` with the following format:

```toml
[tools]
"spm:tuist/tuist" = "latest"
```

### Supported Syntax

| Description                                   | Usage                                           |
| --------------------------------------------- | ----------------------------------------------- |
| GitHub shorthand for latest release version   | `spm:tuist/tuist`                               |
| GitHub shorthand for specific release version | `spm:tuist/tuist@4.15.0`                        |
| GitHub url for latest release version         | `spm:https://github.com/tuist/tuist.git`        |
| GitHub url for specific release version       | `spm:https://github.com/tuist/tuist.git@4.15.0` |

Other syntax may work but is unsupported and untested.

## Tool Options

The following [tool-options](/dev-tools/#tool-options) are available for the backend — these
go in `[tools]` in `mise.toml`.

### `provider`

Set the provider type to use for fetching assets and release information. Either `github` or `gitlab` (default is `github`).
Ensure the `provider` is set to the correct type if you use shorthand notation and `api_url` for self-hosted repositories
as the type probably cannot be derived correctly from the URL.

```toml
[tools]
"spm:patricklorran/ios-settings" = { version = "latest", provider = "gitlab" }
```

### `api_url`

Set the URL for the provider's API. This is useful when using a self-hosted instance.

```toml
[tools]
"spm:acme/my-tool" = { version = "latest", provider = "gitlab", api_url = "https://gitlab.acme.com/api/v4" }
```

---

---
url: /lang/swift.md
---
# Swift&#x20;

`mise` can be used to manage multiple versions of [`swift`](https://swift.org/) on the same system. Swift is supported for macos and linux.

## Usage

Use the latest stable version of swift:

```sh
mise use -g swift
swift --version
```

See [a mise guide for Swift developers](https://tuist.dev/blog/2025/02/04/mise) on how to use `mise` with `swift`.

## Settings

---

---
url: /tasks/task-arguments.md
---
# Task Arguments

Task arguments allow you to pass parameters to tasks, making them more flexible and reusable. There are three ways to define task arguments in mise, but only two are recommended for current use.

## Recommended Methods

### 1. Usage Field (Preferred) {#usage-field}

The **usage field** is the recommended approach for defining task arguments. It provides a clean, declarative syntax that works with both TOML tasks and file tasks.

#### Quick Example

```mise-toml [mise.toml]
[tasks.deploy]
description = "Deploy application"
usage = '''
arg "<environment>" help="Target environment" {
  choices "dev" "staging" "prod"
}
flag "-v --verbose" help="Enable verbose output"
flag "--region <region>" help="AWS region" default="us-east-1" env="AWS_REGION"
'''

run = '''
echo "Deploying to ${usage_environment?} in ${usage_region?}"
[[ "${usage_verbose?}" == "true" ]] && set -x
./deploy.sh "${usage_environment?}" "${usage_region?}"
'''
```

Arguments defined in the usage field are automatically available as environment variables prefixed with `usage_`:

```shell
# Execute with arguments
$ mise run deploy staging --verbose --region us-west-2

# Inside the task, these are available as:
# $usage_environment = "staging"
# $usage_verbose = "true"
# $usage_region = "us-west-2"
```

In addition to environment variables, **usage values are available inside Tera
templates in task run scripts** via a `usage` map:

```mise-toml [mise.toml]
[tasks.deploy]
description = "Deploy application"
usage = '''
arg "<environment>" help="Target environment"
flag "-v --verbose" help="Enable verbose output"
flag "--region <region>" help="AWS region" default="us-east-1"
'''
run = '''
echo "Deploying to {{ usage.environment }} in {{ usage.region }}"
{% if usage.verbose %}
  echo "Verbose mode enabled"
{% endif %}
'''
```

The `usage` map uses **snake\_case argument/flag names as keys** (just like the
`usage_` environment variables). Names with `-` are converted to `_`, so a flag
like `--dry-run` becomes available as `{{ usage.dry_run }}`
and `$usage_dry_run`. Variadic arguments/flags are exposed as arrays and can be
used with Tera's `for` loops and filters like `length`. The `usage` map is
**separate from** the deprecated Tera template functions (`arg()`, `option()`,
`flag()`) described later on this page—you should not mix the two approaches in
the same task.

**Help output example:**

```shellsession
$ mise run deploy --help
Deploy application

Usage: deploy <environment> [OPTIONS]

Arguments:
  <environment>  Target environment [possible values: dev, staging, prod]

Options:
  -v, --verbose          Enable verbose output
      --region <region>  AWS region [env: AWS_REGION] [default: us-east-1]
  -h, --help            Print help
```

## Complete Usage Specification Reference

### Positional Arguments (`arg`)

Positional arguments are defined with `arg` and must be provided in order.

#### Basic Syntax

```kdl
arg "<name>" help="Description"               // Required positional arg
arg "[name]" help="Description"               // Optional positional arg
arg "<file>"                                  // Completed as filename
arg "<dir>"                                   // Completed as directory
```

#### With Defaults

```kdl
arg "<file>" default="config.toml"            // Default value if not provided
arg "[output]" default="out.txt"              // Optional with default
```

#### Variadic Arguments

```kdl
arg "[files]" var=#true                        // 0 or more files
arg "<files>" var=#true                        // 1 or more files (required)
arg "<files>" var=#true var_min=2              // At least 2 files required
arg "<files>" var=#true var_max=5              // Maximum 5 files allowed
arg "<files>" var=#true var_min=1 var_max=3    // Between 1 and 3 files
```

::: tip Handling Variadic Args with Spaces in Bash
Variadic arguments are passed as a shell-escaped string. To properly handle arguments containing spaces as a bash array, wrap the variable in parentheses:

```bash
# Convert to bash array:
eval "files=($usage_files)"

# Use as array:
for f in "${files[@]}"; do
  echo "Processing: $f"
done

# Or pass to commands:
touch "${files[@]}"
```

:::

#### Environment Variable Backing

```kdl
arg "<token>" env="API_TOKEN"                 // Can be set via $API_TOKEN
arg "<host>" env="API_HOST" default="localhost"
```

Priority order: CLI argument > Environment variable > Default value

#### Choices (Enum Values)

```kdl
arg "<level>" {
  choices "debug" "info" "warn" "error"
}
arg "<shell>" {
  choices "bash" "zsh" "fish"
  help "Shell type"
}
```

#### Advanced Features

```kdl
arg "<file>" long_help="Extended help text shown with --help"

// Hidden from help output
arg "<file>" hide=#true
```

#### Double-Dash Behavior

```kdl
// Must use: mycli -- file.txt
arg "<file>" double_dash="required"

// Both work: mycli file.txt or mycli -- file.txt
arg "<file>" double_dash="optional"

// After first arg, behaves as if -- was used
arg "<files>" double_dash="automatic"
```

### Flags (`flag`)

Flags can be defined as booleans or as accepting values.

#### Boolean Flags

```kdl
flag "-f --force"
flag "-v --verbose" help="Enable verbose mode"
flag "--dry-run" help="Preview without executing"
```

#### Short-Only or Long-Only

```kdl
flag "-f"                                     // Short flag only
flag "--force"                                // Long flag only
```

#### Flag With Values

```kdl
flag "-o --output <file>" help="Output file"
flag "--port <port>" help="Server port"
flag "--color <when>" {
  choices "auto" "always" "never"
}
```

#### Flag With Defaults

```kdl
flag "--force" default=#true
flag "--format <format>" help="Output format" default="json"
flag "--port <port>" help="Server port" default="8080"
flag "--color <when>" {
  choices "auto" "always" "never"
  default "auto"
}
```

#### Count Flags

```kdl
// Can be repeated: -vvv
// $usage_verbose = number of times used (e.g., 3)
flag "-v --verbose" count=#true
```

#### Negation

```kdl
flag "--color" negate="--no-color" default=#true
// Default: $usage_color = "true"
// With --no-color: $usage_color = "false"
```

#### Global Flags

```kdl
// Available on all subcommands (if using cmd structure)
flag "-v --verbose" global=#true
```

#### Flag Advanced Features

```kdl
flag "--verbose" long_help="Extended help text"
flag "--debug" hide=#true                      // Hidden from help
```

### Completion (`complete`)

Custom completion can be defined for any argument or flag by name:

```kdl
arg "<plugin>"
complete "plugin" run="mise plugins ls"       // Complete with command output
```

#### With Descriptions

```kdl
complete "plugin" run="mycli plugins list" descriptions=#true
```

Output format (split on `:` for value and description):

```
nodejs:JavaScript runtime
python:Python language
ruby:Ruby language
```

### Long Help Text

For detailed help text, use multi-line format:

```mise-toml
[tasks.complex]
usage = '''
arg "<input>" {
  help "Input file to process"
  long_help """
  The input file should be in JSON or YAML format.

  Supported schemas:
  - schema-v1: Legacy format
  - schema-v2: Current format (recommended)
  - schema-v3: Experimental format

  Example:
    mise run complex data.json
  """
}
flag "--format <fmt>" {
  help "Output format"
  long_help """
  Supported output formats:
  - json: JSON output (default)
  - yaml: YAML output
  - toml: TOML output
  """
  choices "json" "yaml" "toml"
  default "json"
}
'''
run = 'process-data "${usage_input?}" --format "${usage_format?}"'
```

### Hide Arguments

Hide arguments from help output (useful for deprecated or internal options):

```kdl
arg "<legacy_arg>" hide=#true
flag "--internal-debug" hide=#true
```

### Combining Features Example

```mise-toml [mise.toml]
[tasks.deploy]
description = "Deploy application to cloud"
usage = '''
// Positional arguments
arg "<environment>" {
  help "Deployment environment"
  choices "dev" "staging" "prod"
}

arg "[services]" {
  help "Services to deploy (default: all)"
  var #true
  var_min 0
}

// Flags
flag "-v --verbose" {
  help "Enable verbose logging"
  count #true
  default 0
}

flag "--dry-run" help="Show what would be deployed without doing it"

flag "--region <region>" {
  help "Cloud region"
  env "AWS_REGION"
  default "us-east-1"
  choices "us-east-1" "us-west-2" "eu-west-1"
}

flag "--skip-tests" help="Skip running tests before deploy"

flag "--force" help="Force deployment even with warnings"

// Custom completions
complete "services" run="mycli list-services"
'''

run = '''
#!/usr/bin/env bash
set -euo pipefail

# Handle verbosity
if [[ "${usage_verbose?}" -ge 2 ]]; then
  set -x
elif [[ "${usage_verbose?}" -ge 1 ]]; then
  export VERBOSE=1
fi

# Validate environment
ENVIRONMENT="${usage_environment?}"
REGION="${usage_region?}"
DRY_RUN="${usage_dry_run:-false}"
SKIP_TESTS="${usage_skip_tests:-false}"
FORCE="${usage_force:-false}"

echo "Deploying to $ENVIRONMENT in $REGION"

# Run tests unless skipped
if [[ "$SKIP_TESTS" != "true" ]]; then
  echo "Running tests..."
  npm test
fi

# Deploy services
if [[ -n "${usage_services?}" ]]; then
  echo "Deploying services: ${usage_services?}"
  for service in ${usage_services?}; do
    deploy_service "$service" "$ENVIRONMENT" "$REGION" "$DRY_RUN"
  done
else
  echo "Deploying all services"
  deploy_all "$ENVIRONMENT" "$REGION" "$DRY_RUN"
fi
'''
```

### 2. File Task Headers {#file-task-headers}

For file tasks, you can define arguments directly in the file using special `#MISE` or `#USAGE` comment syntax:

```bash [.mise/tasks/deploy]
#!/usr/bin/env bash
#MISE description "Deploy application"
#USAGE arg "<environment>" help="Deployment environment" {
#USAGE   choices "dev" "staging" "prod"
#USAGE }
#USAGE flag "--dry-run" help="Preview changes without deploying"
#USAGE flag "--region <region>" help="AWS region" default="us-east-1" env="AWS_REGION"

ENVIRONMENT="${usage_environment?}"
REGION="${usage_region?}"
DRY_RUN="${usage_dry_run:-false}"

if [[ "$DRY_RUN" == "true" ]]; then
  echo "DRY RUN: Would deploy to $ENVIRONMENT in $REGION"
else
  echo "Deploying to $ENVIRONMENT in $REGION..."
  ./scripts/deploy.sh "$ENVIRONMENT" "$REGION"
fi
```

::: tip Syntax Options
Use `#MISE` (uppercase, recommended) or `#USAGE` for defining arguments in file tasks. `# [MISE]` or `# [USAGE]` are also accepted as workarounds for formatters.
:::

## Bash Variable Expansion for Usage Variables {#bash-variable-expansion}

When accessing usage-defined variables in bash scripts, use parameter expansion syntax to help [shellcheck](https://www.shellcheck.net/) understand these variables and provide default values for boolean flags.

### Common Patterns

| Syntax            | Behavior                     | Use Case                                           | Example                       |
| ----------------- | ---------------------------- | -------------------------------------------------- | ----------------------------- |
| `${var?}`         | Error if unset               | Required args or flags with defaults in usage spec | `${usage_profile?}`           |
| `${var:?}`        | Error if unset or empty      | When you need to ensure non-empty values           | `${usage_target:?}`           |
| `${var:-default}` | Use default if unset         | Boolean flags without `default=` in usage spec     | `${usage_clean:-false}`       |
| `${var:=default}` | Set and use default if unset | When you want to set the variable for later use    | `${usage_dir:=.}`             |
| `${var:+value}`   | Use value if set             | Conditional flag passing                           | `${usage_verbose:+--verbose}` |

### Guidelines for Usage Variables

#### Args and Flags with Defaults

Use `${usage_var?}` since usage guarantees they'll be set:

```bash
# --profile has default="debug" in usage spec
cargo build --profile "${usage_profile?}"
```

#### Boolean Flags without Defaults

Use `${usage_var:-false}` to provide a default value:

```bash
# --clean flag has no default in usage spec
if [ "${usage_clean:-false}" = "true" ]; then
  cargo clean
fi
```

#### Required Arguments

Use `${usage_var:?}` to ensure non-empty values:

```bash
# <target> is a required positional argument
cargo build --target "${usage_target:?}"
```

#### Conditional Flags

Use `${usage_var:+value}` to pass flags only when set:

```bash
# Only add --verbose if the flag was provided
mycli deploy ${usage_verbose:+--verbose}
```

These expansions help [shellcheck](https://www.shellcheck.net/) understand your script and prevent warnings about potentially unset variables while maintaining proper error handling.

## Deprecated Method

### Tera Template Functions  {#tera-templates}

::: danger Deprecated - Removal in 2026.11.0
The Tera template method for defining task arguments is **deprecated** and will be **removed in mise 2026.11.0**.

**Why it's being removed:**

* **Two-pass parsing issues**: Template functions return empty strings during spec collection, causing unexpected behavior when trying to use them as normal template values
* **Complex escaping rules**: Shell escaping rules are confusing and error-prone
* **Inconsistent behavior**: Doesn't work the same way between TOML and file tasks
* **Poor user experience**: Mixes argument definitions with script logic

**Migration required:** Please migrate to the [usage field](#usage-field) method before 2026.11.0.

**Opt-out setting:** If you want to disable the two-pass parsing behavior immediately (before removal), you can set:

```toml
# ~/.config/mise/config.toml
[settings]
task.disable_spec_from_run_scripts = true
```

Or via environment variable: `MISE_TASK_DISABLE_SPEC_FROM_RUN_SCRIPTS=1`

When enabled, mise will only use the `usage` field for spec generation, ignoring any `arg()`, `option()`, or `flag()` functions in run scripts. See [Settings](/configuration/settings) for more details.
:::

Previously, you could define arguments inline in run scripts using Tera template functions:

```mise-toml [mise.toml]
# ❌ DEPRECATED - Do not use
[tasks.test]
run = 'cargo test {{arg(name="file", default="all")}}'
```

```mise-toml [mise.toml]
# ❌ DEPRECATED - Do not use
[tasks.build]
run = [
    'cargo build {{option(name="profile", default="dev")}}',
    './scripts/package.sh {{flag(name="verbose")}}'
]
```

**Problems with this approach:**

1. **Empty strings during parsing**: During spec collection (first pass), template functions return empty strings, so you can't use them in templates like:

   ```toml
   # This doesn't work as expected!
   run = 'echo "File: {{arg(name="file")}}" > {{arg(name="file")}}.log'
   # First pass: 'echo "File: " > .log' (invalid!)
   ```

2. **Escaping complexity**: Different shell types require different escaping:

   ```toml
   # Escaping behavior varies by shell
   run = 'cmd {{arg(name="file")}}' # May or may not be properly escaped
   ```

3. **No help generation**: Doesn't generate proper `--help` output

### Migration Guide

Here's how to migrate from Tera templates to the usage field:

#### Example 1: Simple Arguments

**Old (Deprecated):**

```mise-toml
[tasks.test]
run = '''
cargo test {{arg(
  name="file",
  default="all",
  help="Test file"
)}}
'''
```

**New (Preferred):**

```mise-toml
[tasks.test]
usage = 'arg "<file>" help="Test file" default="all"'
run = 'cargo test ${usage_file?}'
```

#### Example 2: Multiple Arguments with Flags

**Old (Deprecated):**

```mise-toml
[tasks.build]
run = [
  'cargo build {{arg(name="target", default="debug")}}',
  './package.sh {{flag(name="verbose")}}'
]
```

**New (Preferred):**

```mise-toml
[tasks.build]
usage = '''
arg "<target>" default="debug"
flag "-v --verbose"
'''
run = [
  'cargo build ${usage_target?}',
  './package.sh ${usage_verbose?}'
]
```

#### Example 3: Options with Choices

**Old (Deprecated):**

```mise-toml
[tasks.deploy]
run = '''
deploy {{option(
  name="env",
  choices=["dev", "prod"]
)}} {{flag(name="force")}}
'''
```

**New (Preferred):**

```mise-toml
[tasks.deploy]
usage = '''
flag "--env <env>" {
  choices "dev" "prod"
}
flag "--force"
'''
run = 'deploy --env ${usage_env?} ${usage_force?}'
```

#### Example 4: Variadic Arguments

**Old (Deprecated):**

```mise-toml
[tasks.lint]
run = 'eslint {{arg(name="files", var=true)}}'
```

**New (Preferred):**

```mise-toml
[tasks.lint]
usage = 'arg "<files>" var=#true'
run = 'eslint ${usage_files?}'
```

::: tip Handling Arguments with Spaces
If your variadic arguments may contain spaces, convert the variable to a bash array:

```mise-toml
[tasks.process]
usage = 'arg "<files>" var=#true'
run = '''
eval "files=($usage_files)"
for f in "${files[@]}"; do
  process "$f"
done
'''
```

:::

## See Also

* [Task Configuration](/tasks/task-configuration) - Complete task configuration reference
* [TOML Tasks](/tasks/toml-tasks) - TOML task syntax
* [File Tasks](/tasks/file-tasks) - File-based task syntax
* [Running Tasks](/tasks/running-tasks) - How to execute tasks
* [Usage Spec Documentation](https://usage.jdx.dev/spec/) - Complete usage specification reference

---

---
url: /tasks/task-configuration.md
---
# Task Configuration

This is an exhaustive list of all the configuration options available for tasks in `mise.toml` or
as file tasks.

## Task properties

All examples are in toml-task format instead of file, however they apply in both except where otherwise noted.

### `run`

* **Type**: `string | (string | { task: string } | { tasks: string[] })[]`

The command(s) to run. This is the only required property for a task.

You can now mix scripts with task references:

```mise-toml
[tasks.grouped]
run = [
  { task = "t1" },          # run t1 (with its dependencies)
  { tasks = ["t2", "t3"] }, # run t2 and t3 in parallel (with their dependencies)
  "echo end",               # then run a script
]
```

Simple forms still work and are equivalent:

```mise-toml
tasks.a = "echo hello"
tasks.b = ["echo hello"]
tasks.c.run = "echo hello"
[tasks.d]
run = "echo hello"
[tasks.e]
run = ["echo hello"]
```

### `run_windows`

* **Type**: `string | (string | { task: string } | { tasks: string[] })[]`

Windows-specific variant of `run` supporting the same structured syntax:

```mise-toml
[tasks.build]
run = "cargo build"
run_windows = "cargo build --features windows"
```

### `description`

* **Type**: `string`

A description of the task. This is used in (among other places)
the help output, completions, `mise run` (without arguments), and `mise tasks`.

```mise-toml
[tasks.build]
description = "Build the CLI"
run = "cargo build"
```

### `alias`

* **Type**: `string | string[]`

An alias for the task so you can run it with `mise run <alias>` instead of the full task name.

```mise-toml
[tasks.build]
alias = "b" # run with `mise run b`
run = "cargo build"
```

### `depends`

* **Type**: `string | string[] | { task: string, args?: string[], env?: { [key]: string } }[]`

Tasks that must be run before this task. This is a list of task names or aliases. Arguments can be
passed to the task, e.g.: `depends = ["build --release"]`. If multiple tasks have the same dependency,
that dependency will only be run once. mise will run whatever it can in parallel (up to [`--jobs`](/cli/run))
through the use of `depends` and related properties.

```mise-toml
[tasks.build]
run = "cargo build"
[tasks.test]
depends = ["build"]
run = "cargo test"
```

#### Passing environment variables to dependencies

You can pass environment variables to specific dependencies using two syntaxes:

**Shell-style inline:**

```mise-toml
[tasks.test]
depends = ["NODE_ENV=test setup"]
run = "npm test"

[tasks.setup]
run = 'echo "Setting up for $NODE_ENV"'
```

**Structured object format:**

```mise-toml
[tasks.test]
depends = [
  { task = "setup", env = { NODE_ENV = "test", DEBUG = "true" } }
]
run = "npm test"
```

The structured format also supports combining env vars with arguments:

```mise-toml
[tasks.deploy]
depends = [
  { task = "build", args = ["--release"],
    env = { RUSTFLAGS = "-C opt-level=3" } }
]
run = "./deploy.sh"
```

Note: These environment variables are passed only to the specified dependency, not to the current task or other dependencies.

### `depends_post`

* **Type**: `string | string[] | { task: string, args?: string[], env?: { [key]: string } }[]`

Like `depends` but these tasks run *after* this task and its dependencies complete. For example, you
may want a `postlint` task that you can run individually without also running `lint`:

```mise-toml
[tasks.lint]
run = "eslint ."
depends_post = ["postlint"]
[tasks.postlint]
run = "echo 'linting complete'"
```

Supports the same argument and environment variable syntax as `depends`.

### `wait_for`

* **Type**: `string | string[] | { task: string, args?: string[], env?: { [key]: string } }[]`

Similar to `depends`, it will wait for these tasks to complete before running however they won't be
added to the list of tasks to run. This is essentially optional dependencies.

```mise-toml
[tasks.lint]
wait_for = ["render"] # creates some js files, so if it's running, wait for it to finish
run = "eslint ."
```

Supports the same argument and environment variable syntax as `depends`.

`wait_for` matches tasks differently depending on whether args or env vars are specified:

* `wait_for = ["setup"]` — matches by name, regardless of args or env overrides. If another task runs `depends = ["DEBUG=1 setup"]`, this will still match and wait for it.
* `wait_for = ["setup arg1"]` or `wait_for = ["DEBUG=1 setup"]` — matches only tasks running with that exact args/env configuration.

### `env`

* **Type**: `{ [key]: string | int | bool }`

Environment variables specific to this task. These will not be passed to `depends` tasks.

```mise-toml
[tasks.test]
env.TEST_ENV_VAR = "ABC"
run = [
    "echo $TEST_ENV_VAR",
    "mise run some-other-task", # running tasks like this _will_ have TEST_ENV_VAR set of course
]
```

### `tools`

* **Type**: `{ [key]: string }`

Tools to install and activate before running the task. This is useful for tasks that require a specific tool to be
installed or a tool with a different version. It will only be used for that task, not dependencies.

```mise-toml
[tasks.build]
tools.rust = "1.50.0"
run = "cargo build"
```

### `dir`

* **Type**: `string`
* **Default**: "{{ config\_root }}" - the directory containing `mise.toml`, or in the case of something like `~/src/myproj/.config/mise.toml`, it will be `~/src/myproj`.

The directory to run the task from. The most common way this is used is when you want the task to execute
in the user's current directory:

```mise-toml
[tasks.test]
dir = "{{cwd}}"
run = "cargo test"
```

### `hide`

* **Type**: `bool`
* **Default**: `false`

Hide the task from help, completion, and other output like `mise tasks`. Useful for deprecated or internal
tasks you don't want others to easily see.

```mise-toml
[tasks.internal]
hide = true
run = "echo my internal task"
```

### `confirm`

* **Type**: `string`

A message to show before running the task. This is useful for tasks that are destructive or take a long
time to run. The user will be prompted to confirm before the task is run.

```mise-toml
[tasks.release]
confirm = "Are you sure you want to cut a release?"
description = 'Cut a new release'
file = 'scripts/release.sh'
```

The confirm message supports Tera templates and can reference usage arguments:

```mise-toml
[tasks.deploy]
usage = '''
arg "<environment>" help="Environment to deploy to"
flag "--force" help="Force deployment"
'''
confirm = "Deploy to {{ usage.environment }}?{% if usage.force %} (forced){% endif %}"
run = "deploy.sh ${usage_environment}"
```

### `raw`

* **Type**: `bool`
* **Default**: `false`

Connects the task directly to the shell's stdin/stdout/stderr. This is useful for tasks that need to
accept input or output in a way that mise's normal task handling doesn't support. This is not recommended
to use because it really screws up the output whenever mise runs tasks in parallel. Ensure when using
this that no other tasks are running at the same time.

In the future we could have a property like `single = true` or something that prevents multiple tasks
from running at the same time. If that sounds useful, search/file a ticket.

### `sources`

* **Type**: `string | string[]`

Files or directories that this task uses as input, if this and `outputs` is defined, mise will skip
executing tasks where the modification time of the oldest output file is newer than the modification
time of the newest source file. This is useful for tasks that are expensive to run and only need to
be run when their inputs change.

The task itself will be automatically added as a source, so if you edit the definition that will also
cause the task to be run.

This is also used in `mise watch` to know which files/directories to watch.

This can be specified with relative paths to the config file and/or with glob patterns, e.g.: `src/**/*.rs`.
Ensure you don't go crazy with adding a ton of files in a glob though—mise has to scan each and every one to check
the timestamp.

```mise-toml
[tasks.build]
run = "cargo build"
sources = ["Cargo.toml", "src/**/*.rs"]
outputs = ["target/debug/mycli"]
```

Running the above will only execute `cargo build` if `mise.toml`, `Cargo.toml`, or any ".rs" file in the `src` directory
has changed since the last build.

The [`task_source_files`](../templates.md#task-source-files) function can be used to iterate over a task's
`sources` within its template context.

### `outputs`

* **Type**: `string | string[] | { auto = true }`
* **Default**: `{ auto = true }`

The counterpart to `sources`, these are the files or directories that the task will create/modify after
it executes.

`auto = true` is an alternative to specifying output files manually. In that case, mise will touch
an internally tracked file based on the hash of the task definition (stored in `~/.local/state/mise/task-outputs/<hash>` if you're curious).
This is useful if you want `mise run` to execute when sources change but don't want to have to manually `touch`
a file for `sources` to work.

```mise-toml
[tasks.build]
run = "cargo build"
sources = ["Cargo.toml", "src/**/*.rs"]
outputs = { auto = true } # this is the default when sources is defined
```

### `shell`

* **Type**: `string`
* **Default**: [`unix_default_inline_shell_args`](/configuration/settings.html#unix_default_inline_shell_args) or [`windows_default_inline_shell_args`](/configuration/settings.html#windows_default_inline_shell_args)
* **Note**: Only applies to toml-tasks.

The shell to use to run the task. This is useful if you want to run a task with a different shell than
the default such as `fish`, `zsh`, or `pwsh`. Generally though, it's recommended to use a [shebang](./toml-tasks#shell-shebang) instead
because that will allow IDEs with mise support to show syntax highlighting and linting for the script.

```mise-toml
[tasks.hello]
run = '''
#!/usr/bin/env node
console.log('hello world')
'''
```

### `quiet`

* **Type**: `bool`
* **Default**: `false`

Suppress mise's output for the task such as showing the command that is run, e.g.: `[build] $ cargo build`.
When this is set, mise won't show any output other than what the script itself outputs. If you'd also
like to hide even the output that the task emits, use [`silent`](#silent).

### `silent`

* **Type**: `bool | "stdout" | "stderr"`
* **Default**: `false`

Suppress all output from the task. If set to `"stdout"` or `"stderr"`, only that stream will be suppressed.

### `usage`

* **Type**: `string`

::: tip
For comprehensive information about task arguments and the usage field, see the dedicated [Task Arguments](/tasks/task-arguments) page.
:::

More advanced usage specs can be added to the task's `usage` field. This only applies to toml-tasks.

```mise-toml
[tasks.test]
usage = '''
arg "<file>" help="The file to test" default="src/main.rs"
'''
run = 'cargo test ${usage_file?}'
```

#### Environment Variable Support for Args and Flags

Both args and flags in usage specs can specify an environment variable as an alternative source for their value. This allows task arguments to be provided through environment variables when not specified on the command line.

The precedence order is:

1. CLI arguments/flags (highest priority)
2. Environment variables (middle priority)
3. Default values (lowest priority)

**For positional arguments:**

```mise-toml
[tasks.deploy]
usage = '''
arg "<environment>" env="DEPLOY_ENV" help="Target environment" default="staging"
arg "<region>" env="AWS_REGION" help="AWS region" default="us-east-1"
'''

run = '''
echo "Deploying to ${usage_environment?} in ${usage_region?}"
'''
```

Usage examples:

```bash
# Using CLI args (highest priority)
mise run deploy production us-west-2

# Using environment variables
export DEPLOY_ENV=production
export AWS_REGION=us-west-2
mise run deploy

# Using defaults (lowest priority)
mise run deploy  # deploys to staging in us-east-1

# CLI overrides environment variable
export DEPLOY_ENV=staging
mise run deploy production  # deploys to production
```

**For flags:**

```mise-toml
[tasks.build]
usage = '''
flag "-p --profile <profile>" env="BUILD_PROFILE" help="Build profile" default="dev"
flag "-v --verbose" env="VERBOSE" help="Verbose output"
'''

run = '''
echo "Building with profile: ${usage_profile?}"
echo "Verbose: ${usage_verbose:-false}"
'''
```

Usage examples:

```bash
# Using CLI flags
mise run build --profile release --verbose

# Using environment variables
export BUILD_PROFILE=release
export VERBOSE=true
mise run build

# Mixed usage - env var provides one, CLI provides another
export BUILD_PROFILE=release
mise run build --verbose
```

**File tasks** (tasks defined as executable files in `mise-tasks/` or `.mise/tasks/`) also support the `env` attribute:

```bash
#!/usr/bin/env bash
#USAGE arg "<input>" env="INPUT_FILE" help="Input file to process"
#USAGE flag "-o --output <file>" env="OUTPUT_FILE" help="Output file" default="out.txt"

echo "Processing ${usage_input?} -> ${usage_output?}"
```

**Required arguments:**

Environment variables can satisfy required argument checks. If an argument is marked as required (using angle brackets `<arg>`), providing its value through the environment variable specified in the `env` attribute fulfills that requirement:

```mise-toml
[tasks.deploy]
usage = '''
arg "<api-key>" env="API_KEY" help="API key for deployment"
'''
run = 'deploy --api-key ${usage_api_key?}'
```

```bash
# This will fail - no API_KEY provided
mise run deploy

# This succeeds - API_KEY provided via environment
export API_KEY=secret123
mise run deploy

# This also succeeds - provided via CLI
mise run deploy secret123
```

## Vars

Vars are variables that can be shared between tasks like environment variables but they are not
passed as environment variables to the scripts. They are defined in the `vars` section of the
`mise.toml` file.

```mise-toml
[vars]
e2e_args = '--headless'

[tasks.test]
run = './scripts/test-e2e.sh {{vars.e2e_args}}'
```

Tasks can also define task-local vars that override config vars for that task:

```mise-toml
[tasks.test]
vars = { e2e_args = "--headed" }
run = './scripts/test-e2e.sh {{vars.e2e_args}}'
```

Like most configuration in mise, vars can be defined across several files. So for example, you could
put some vars in your global mise config `~/.config/mise/config.toml`, use them in a task at
`~/src/work/myproject/mise.toml`. You can also override those vars in "later" config files such
as `~/src/work/myproject/mise.local.toml` and they will be used inside tasks of any config file.

As of this writing vars are only supported in TOML tasks. I want to add support for file tasks, but
I don't want to turn all file tasks into tera templates just for this feature.

## `[task_config]` options

Options available in the top-level `mise.toml` `[task_config]` section. These apply to all tasks which
are included by that config file or use the same root directory, e.g.: `~/src/myprojec/mise.toml`'s `[task_config]`
applies to file tasks like `~/src/myproject/mise-tasks/mytask` but not to tasks in `~/src/myproject/subproj/mise.toml`.

### `task_config.dir`

Change the default directory tasks are run from.

```toml
[task_config]
dir = "{{cwd}}"
```

### `task_config.includes`

Add toml files containing toml tasks, or file tasks to include when looking for tasks.

```toml
[task_config]
includes = [
    "tasks.toml", # a task toml file
    "mytasks"     # a directory containing file tasks (in addition to the default file tasks directories)
]
```

If using included task toml files, note that they have a different format than the `mise.toml` file. They are just a list of tasks.
The file should be the same format as the `[tasks]` section of `mise.toml` but without the `[task]` prefix:

::: code-group

```mise-toml [tasks.toml]
task1 = "echo task1"
task2 = "echo task2"
task3 = "echo task3"

[task4]
run = "echo task4"
vars = { target = "linux" }
```

:::

If you want auto-completion/validation in included toml tasks files, you can use the following JSON schema: <https://mise.jdx.dev/schema/mise-task.json>

#### Remote Git Includes&#x20;

You can include directories of tasks from git repositories using the `git::` URL syntax:

::: code-group

```mise-toml [ssh]
[task_config]
includes = [
    "git::ssh://git@github.com/myorg/shared-tasks.git//tasks?ref=v1.0.0"
]
```

```mise-toml [https]
[task_config]
includes = [
    "git::https://github.com/myorg/shared-tasks.git//tasks?ref=main"
]
```

:::

URL format: `git::<protocol>://<url>//<path>?<ref>`

Required fields:

* `protocol`: The git protocol (ssh or https).
* `url`: The git repository URL.
* `path`: The path to the directory in the repository.

Optional fields:

* `ref`: The git reference (branch, tag, commit). Defaults to the repository's default branch.

The repository will be cloned and cached in `MISE_CACHE_DIR/remote-git-tasks-cache`. Tasks from the included directory will be loaded as if they were local file tasks. You can disable caching with `MISE_TASK_REMOTE_NO_CACHE=true` or the `--no-cache` flag.

## Monorepo Support&#x20;

mise supports monorepo-style task organization with target path syntax. Enable it by setting `experimental_monorepo_root = true` in your root `mise.toml`.

For complete documentation on monorepo tasks including:

* Task path syntax and wildcards
* Tool layering from parent configs
* Performance tuning
* Best practices and troubleshooting

See the dedicated [Monorepo Tasks](/tasks/monorepo) documentation.

## `redactions`&#x20;

* **Type**: `string[]`

Redactions are a way to hide sensitive information from the output of tasks. This is useful for things like
API keys, passwords, or other sensitive information that you don't want to accidentally leak in logs or
other output.

A list of environment variables to redact from the output.

```toml
redactions = ["API_KEY", "PASSWORD"]
```

Running the above task will output `echo [redacted]` instead.

You can also specify these as a glob pattern, e.g.: `redactions.env = ["SECRETS_*"]`.

## `[vars]` options

Vars are variables that can be shared between tasks like environment variables but they are not
passed as environment variables to the scripts. They are defined in the `vars` section of the
`mise.toml` file.

```mise-toml
[vars]
e2e_args = '--headless'
[tasks.test]
run = './scripts/test-e2e.sh {{vars.e2e_args}}'
vars = { e2e_args = '--headed' }
```

The task-level `vars` override any config-level vars with the same name. In the example above, `e2e_args` resolves to `'--headed'` instead of the config-level `'--headless'`.

Like `[env]`, vars can also be read in as a file:

```toml
[vars]
_.file = ".env"
```

[Secrets](/environments/secrets/) are also supported as vars.

## Task Configuration Settings

The following settings control task behavior. These can be set globally in `~/.config/mise/config.toml` or per-project in `mise.toml`:

---

---
url: /tasks/architecture.md
---
# Task System Architecture

Understanding how mise's task system works helps you write more efficient tasks and troubleshoot dependency issues.

## Task Dependency System

mise uses a sophisticated dependency graph system to manage task execution order and parallelism. This ensures tasks run in the correct order while maximizing performance through parallel execution.

### Dependency Graph Resolution

When you run `mise run build`, mise creates a directed acyclic graph (DAG) of all tasks and their dependencies:

```mermaid
graph TD
    A[lint] --> D[test]
    B[format] --> D[test]
    C[build] --> D[test]
    D[test] --> E[package]
    F[docs] --> E[package]
    E[package] --> G[deploy]
```

This graph ensures that:

* Dependencies run before dependents
* Independent tasks run in parallel
* No circular dependencies exist
* Failed dependencies prevent dependents from running

### Dependency Types

mise supports three types of task dependencies:

#### `depends` - Prerequisites

Tasks that must complete successfully before this task runs:

```toml
[tasks.test]
depends = ["lint", "build"]
run = "npm test"
```

#### `depends_post` - Cleanup Tasks

Tasks that run after this task completes (whether successful or failed):

```toml
[tasks.deploy]
depends = ["build", "test"]
depends_post = ["cleanup", "notify"]
run = "kubectl apply -f deployment.yaml"
```

#### `wait_for` - Soft Dependencies

Tasks that should run first if they're in the current execution, but don't fail if they're not available:

```toml
[tasks.integration-test]
wait_for = ["start-services"]  # Only waits if start-services is also being run
run = "npm run test:integration"
```

## Parallel Execution Engine

### Job Control

mise executes tasks in parallel up to the configured job limit:

```bash
mise run --jobs 8 test        # Use 8 parallel jobs
mise run -j 1 test            # Force sequential execution
```

The default is 4 parallel jobs, but you can configure this globally:

```toml
# ~/.config/mise/config.toml
[settings]
jobs = 8
```

### Example Execution Flow

Given these tasks:

```toml
[tasks.lint]
run = "eslint src/"

[tasks.test-unit]
depends = ["lint"]
run = "npm run test:unit"

[tasks.test-integration]
depends = ["lint"]
run = "npm run test:integration"

[tasks.build]
depends = ["test-unit", "test-integration"]
run = "npm run build"
```

Execution with `--jobs 2`:

```
Time →
0s:   [lint]
5s:   [test-unit] [test-integration]  # Run in parallel after lint
15s:  [build]                        # Waits for both tests
```

## Task Discovery and Resolution

### Task Sources

mise discovers tasks from multiple sources in this order:

1. **File tasks**: Executable files in task directories
2. **TOML tasks**: Defined in `mise.toml` files
3. **Parent directory tasks**: Available from parent directories

### Task Resolution Process

When you run `mise run build`, mise:

1. **Discovers all tasks** from all configuration sources
2. **Resolves the task name** (handles aliases and partial matches)
3. **Builds dependency graph** including all dependencies
4. **Validates graph** (checks for circular dependencies)
5. **Executes in dependency order** with parallelism

### Task Resolution Across Directories

Tasks from parent directories are available in subdirectories and can be overridden:

```
project/
├── mise.toml              # defines: lint, test, build
└── frontend/
    └── mise.toml          # overrides: test, adds: bundle
```

In `frontend/`, you have access to: `lint` (from parent), `test` (overridden), `build` (from parent), `bundle` (local).

## Advanced Dependency Features

### Conditional Dependencies

Use task arguments for conditional behavior:

```toml
[tasks.test]
depends = ["build"]
run = '''
if [ "$1" = "--with-lint" ]; then
  mise run lint
fi
npm test
'''
```

### Dynamic Dependencies

Tasks can specify dependencies at runtime:

```bash
#!/usr/bin/env bash
#MISE depends=["setup"]

# Additional conditional dependency
if [ ! -f ".env" ]; then
  mise run generate-env
fi

npm start
```

### Cross-Project Dependencies

Reference tasks from other directories:

```toml
[tasks.deploy-all]
depends = [
  "../api:build",
  "../frontend:build",
  "deploy-infrastructure"
]
run = "echo 'All services deployed'"
```

## Performance Optimizations

### Source and Output Tracking

Tasks can skip execution if sources haven't changed:

```toml
[tasks.build]
sources = ["src/**/*.ts", "package.json"]
outputs = ["dist/**/*"]
run = "npm run build"
```

mise will only run the task if:

* Source files are newer than output files
* The task has never been run
* Dependencies have changed

### Incremental Execution

Use `mise run --force` to ignore source/output checking:

```bash
mise run --force build     # Always run, ignore source changes
```

### Parallel File Watching

Use `mise watch` for continuous development:

```bash
mise watch              # Watch all task sources
mise watch build test   # Watch specific tasks
```

This automatically reruns tasks when their source files change.

## Debugging Task Dependencies

### Visualize Dependencies

```bash
mise tasks deps build           # Show build's dependencies
mise tasks deps --dot > deps.dot # Generate graphviz diagram
```

### Execution Tracing

```bash
mise run --verbose build       # Show task execution details
mise run --dry-run build       # Show what would run without executing
```

### Common Issues

**Circular Dependencies**:

```
Error: Circular dependency detected: test → build → test
```

Solution: Remove the circular reference or use `wait_for` instead of `depends`.

**Missing Dependencies**:

```
Error: Task 'build' depends on 'lint' but 'lint' was not found
```

Solution: Define the missing task or remove the dependency.

**Slow Parallel Execution**:

* Check if tasks have unnecessary dependencies
* Use `mise tasks deps` to verify dependency graph
* Consider increasing `--jobs` if you have CPU cores available

The task architecture is designed to scale from simple single-task projects to complex multi-service applications with intricate build dependencies.

---

---
url: /tasks/templates.md
---
# Task Templates

::: warning
This feature is experimental and requires `experimental = true` in your settings.
:::

Task templates allow you to define reusable task definitions that can be extended by multiple tasks. This is particularly useful in monorepos or projects with similar task patterns across different components.

## Defining Templates

Templates are defined in the `[task_templates.*]` section of your `mise.toml`:

```toml
[settings]
experimental = true

[task_templates."python:build"]
description = "Build a Python project"
run = "uv build"
tools = { python = "3.12", uv = "latest" }
env = { PYTHONPATH = "src" }

[task_templates."python:test"]
description = "Run Python tests"
run = "pytest"
tools = { python = "3.12" }
depends = ["build"]
```

## Extending Templates

Tasks can extend templates using the `extends` field:

```toml
[tasks.build]
extends = "python:build"

[tasks.test]
extends = "python:test"
run = "pytest --cov"  # Override run while keeping tools, depends
```

## Template Naming

Templates use colon (`:`) separators for namespacing, similar to task naming conventions in monorepos:

* `python:build`
* `python:test`
* `rust:cargo:build`
* `node:npm:test`

## Merge Semantics

When a task extends a template, fields are merged according to these rules:

| Field                                   | Behavior                                                    |
| --------------------------------------- | ----------------------------------------------------------- |
| `run`, `run_windows`                    | Local overrides completely                                  |
| `tools`                                 | Deep merge (local tools added/override template)            |
| `env`                                   | Deep merge (local env added/override template)              |
| `depends`, `depends_post`, `wait_for`   | Local overrides completely (not merged)                     |
| `dir`                                   | Local overrides; defaults to config\_root if not in template |
| `sources`, `outputs`                    | Local overrides completely                                  |
| `description`, `shell`, `timeout`, etc. | Local overrides template (if set)                           |
| `quiet`, `hide`, `raw`                  | Not carried over (must be set explicitly in task)           |

### Example: Deep Merge for Tools

```toml
[task_templates."fullstack:build"]
tools = { python = "3.12", node = "18" }

[tasks.build]
extends = "fullstack:build"
tools = { node = "20" }  # Override node, keep python from template
# Result: tools = { python = "3.12", node = "20" }
```

### Example: Deep Merge for Env

```toml
[task_templates."python:build"]
env = { PYTHONPATH = "src", DEBUG = "0" }

[tasks.build]
extends = "python:build"
env = { DEBUG = "1" }  # Override DEBUG, keep PYTHONPATH from template
# Result: env = { PYTHONPATH = "src", DEBUG = "1" }
```

### Example: Complete Override for Depends

```toml
[task_templates."python:test"]
depends = ["lint", "typecheck"]

[tasks.test]
extends = "python:test"
depends = ["build"]  # Completely replaces template depends
# Result: depends = ["build"] (lint and typecheck NOT included)
```

## Tera Templating

Templates support Tera templating, rendered with the **using project's context**:

```toml
[task_templates."python:build"]
description = "Build Python project"
dir = "{{ config_root }}"  # Resolves to the PROJECT's directory
run = "uv build"
env = { PROJECT = "{{ config_root | basename }}" }
```

Available variables (same as regular tasks):

* {{ config\_root }} - The project using the template (NOT where template is defined)
* {{ env.VAR }} - Environment variables
* {{ cwd }} - Current working directory
* {{ vars.\* }} - User-defined variables from config

## Monorepo Usage

Task templates are especially useful in monorepos where multiple packages share similar build patterns:

```toml
# Root mise.toml
[settings]
experimental = true
experimental_monorepo_root = true

[task_templates."python:build"]
run = "uv build"
tools = { python = "3.12", uv = "latest" }

[task_templates."python:test"]
run = "pytest"
tools = { python = "3.12" }
depends = ["build"]

[task_templates."python:lint"]
run = "ruff check ."
tools = { python = "3.12", ruff = "latest" }
```

```toml
# packages/api/mise.toml
[tasks.build]
extends = "python:build"

[tasks.test]
extends = "python:test"
run = "pytest --cov"  # Add coverage

[tasks.lint]
extends = "python:lint"
```

```toml
# packages/worker/mise.toml
[tasks.build]
extends = "python:build"

[tasks.test]
extends = "python:test"

[tasks.lint]
extends = "python:lint"
```

## Future Enhancements

The following features are planned for future releases:

* **Global templates**: Define templates in `~/.config/mise/config.toml` for use across all projects
* **Template packages**: Import templates from external sources
* **Pattern-matching rules**: Auto-apply templates based on file detection (e.g., auto-apply `python:*` templates when `pyproject.toml` exists)
* **File task templates**: Define templates as standalone script files, similar to [file tasks](/tasks/file-tasks)

---

---
url: /tasks.md
---
# Tasks

> Like [make](https://www.gnu.org/software/make/manual/make.html) it manages *tasks* used
> to build and test projects.

You can define tasks in `mise.toml` files or as standalone shell scripts. These are useful for
things like running linters, tests, builders, servers, and other tasks that are specific to a
project. Of
course, tasks launched with mise will include the mise environment—your tools and env vars defined
in `mise.toml`.

Here's my favorite features about mise's task runner:

* building dependencies in parallel—by default with no configuration required
* last-modified checking to avoid rebuilding when there are no changes—requires minimal config
* [mise watch](./running-tasks.html#watching-files) to automatically rebuild on changes—no configuration required, but it helps
* ability to write tasks as actual bash script files and not inside yml/json/toml strings that lack
  syntax highlighting and linting/checking support

There are 2 ways to define tasks: [inside of `mise.toml` files](./toml-tasks.html) or as [standalone shell scripts](./file-tasks.html). You can also use [task templates](./templates.html) to create reusable task definitions.

## Tasks in `mise.toml` files

Tasks are defined in the `[tasks]` section of the `mise.toml` file.

```toml [mise.toml]
[tasks.build]
description = "Build the CLI"
run = "cargo build"
```

You can then run the task with `mise run build` (or `mise build` if it doesn't conflict with an existing command).

* See [TOML tasks](./toml-tasks.html) for more information.
* See [Running Tasks](./running-tasks.html) to learn how to run tasks.

## File Tasks

You can also define tasks as standalone shell scripts. All you have to do is to create an `executable` file in a specific directory like `mise-tasks`.

```sh [mise-tasks/build]
#!/usr/bin/env bash
#MISE description="Build the CLI"
cargo build
```

You can then run the task with `mise run build` like for TOML tasks.
See the [file tasks reference](./file-tasks.html) for more information.

## Environment variables passed to tasks

The following environment variables are passed to the task:

* `MISE_ORIGINAL_CWD`: The original working directory from where the task was run.
* `MISE_CONFIG_ROOT`: The directory containing the `mise.toml` file where the task was defined or if the config path is something like `~/src/myproj/.config/mise.toml`, it will be `~/src/myproj`.
* `MISE_PROJECT_ROOT`: The root of the project.
* `MISE_TASK_NAME`: The name of the task being run.
* `MISE_TASK_DIR`: The directory containing the task script.
* `MISE_TASK_FILE`: The full path to the task script.

---

---
url: /templates.md
---
# Templates

Templates in mise provide a powerful way to configure different aspects of
your environment and project settings.

A template is a string that contains variables, expressions, and control structures.
When rendered, the template engine (`tera`) replaces the variables with their values.

You can define and use templates in the following locations:

* Most `mise.toml` configuration values
  * The `mise.toml` file itself is not templated and must be valid toml
* `.tool-versions` files
* *(Submit a ticket if you want to see it used elsewhere!)*

## Example

Here is an example of a `mise.toml` file that uses templates:

```toml
[env]
PROJECT_NAME = "{{ cwd | basename }}"
TERRAFORM_VERSION = "1.0.0"

[tools]
# refers to env variable defined in this file
terraform = "{{ env.TERRAFORM_VERSION }}"
# refers to external env variable
node = "{{ get_env(name='NODE_VERSION', default='20') }}"
```

You will find more examples in the [cookbook](./mise-cookbook/index.md).

## Template Rendering

Mise uses [tera](https://keats.github.io/tera/docs/) to provide the template feature.
In the template, there are 3 kinds of delimiters:

* `{{` and `}}` for expressions
* `{%` and `%}` for statements
* `{#` and `#}` for comments

Additionally, use `raw` block to skip rendering tera delimiters:

```
{% raw %}
  Hello {{ name }}
{% endraw %}
```

This will become `Hello {{name}}`.

Tera supports [literals](https://keats.github.io/tera/docs/#literals), including:

* booleans: `true` (or `True`) and `false` (or `False`)
* integers
* floats
* strings: text delimited by `""`, `''` or \`\`
* arrays: a comma-separated list of literals and/or ident surrounded by
  `[` and `]` (trailing comma allowed)

You can render a variable by using the `{{ name }}`.
For complex attributes, use:

* dot `.`, e.g. `{{ product.name }}`
* square brackets `[]`, e.g. `{{ product["name"] }}`

Tera also supports powerful [expressions](https://keats.github.io/tera/docs/#expressions):

* mathematical expressions
  * `+`
  * `-`
  * `/`
  * `*`
  * `%`
* comparisons
  * `==`
  * `!=`
  * `>=`
  * `<=`
  * `<`
  * `>`
* logic
  * `and`
  * `or`
  * `not`
* concatenation `~`, e.g. {{ "hello " ~ 'world' ~ \`!\` }
* in checking, e.g. `{{ some_var in [1, 2, 3] }}`

Tera also supports control structures such as `if` and
`for`. [Read more](https://keats.github.io/tera/docs/#control-structures).

### Tera Filters

You can modify variables using [filters](https://keats.github.io/tera/docs/#filters).
You can filter a variable by a pipe symbol (`|`) and may have named arguments
in parentheses. You can also chain multiple filters.
e.g. `{{ "Doctor Who" | lower | replace(from="doctor", to="Dr.") }}`
will output `Dr. who`.

### Tera Functions

[Functions](https://keats.github.io/tera/docs/#functions) provide
additional features to templates.

### Tera Tests

You can also uses [tests](https://keats.github.io/tera/docs/#tests) to examine variables.

```
{% if my_number is not odd %}
  Even
{% endif %}
```

## Mise Template Features

Mise provides additional variables, functions, filters, and tests on top of tera features.

### Variables

Mise exposes several [variables](https://keats.github.io/tera/docs/#variables).
These variables offer key information about the current environment:

* `env: HashMap<String, String>` – Accesses current environment variables as
  a key-value map.
* `cwd: PathBuf` – Points to the current working directory.
* `config_root: PathBuf` – Locates the directory containing your `mise.toml` file, or in the case of something like `~/src/myproj/.config/mise.toml`, it will point to `~/src/myproj`.
* `mise_bin: String` - Points to the path to the current mise executable
* `mise_pid: String` - Points to the pid of the current mise process
* `mise_env: Vec<String>` - The configuration environment as specified by `MISE_ENV`, `-E`, or `--env`. Will be undefined if the configuration environment is not set.
* `xdg_cache_home: PathBuf` - Points to the directory of XDG cache home
* `xdg_config_home: PathBuf` - Points to the directory of XDG config home
* `xdg_data_home: PathBuf` - Points to the directory of XDG data home
* `xdg_state_home: PathBuf` - Points to the directory of XDG state home
* `tools: HashMap<String, ToolInfo | ToolInfo[]>` – Maps installed tool names to their info.
  Available in task templates and env directives with `tools = true`.
  * When a single version is installed:
    * `tools.<name>.version: String` – The resolved version (e.g., `"22.1.0"`)
    * `tools.<name>.path: String` – The install path
  * When multiple versions are installed, it becomes an array:
    * `tools.<name>[0].version: String` – The first version
    * `tools.<name>[0].path: String` – The first install path
    * `tools.<name>[1].version: String` – The second version, etc.

In **task run scripts**, mise also exposes a `usage` map when the task has a usage
specification (see [Task Arguments](/tasks/task-arguments#usage-field)):

* `usage: HashMap<String, Value>` – Parsed task arguments and flags, keyed by their
  names. Values are **not shell-escaped or quoted** and may be:
  * booleans (for flags and boolean args)
  * strings
  * arrays of booleans/strings for variadic args/flags

The keys are the argument/flag names as written in the usage spec. If the name
contains `-`, use bracket access, e.g. `{{ usage["dry-run"] }}`.
Examples:

```mise-toml
[tasks.deploy]
usage = '''
arg "<environment>" help="Target environment"
flag "-v --verbose" help="Enable verbose output"
arg "[tags]" var=#true
'''
run = '''
echo "env={{ usage.environment }}"
echo "verbose={{ usage.verbose }}"
echo "tag count={{ usage.tags | length }}"
{% for tag in usage.tags %}
  echo "tag={{ tag }}"
{% endfor %}
'''
```

### Functions

#### Tera Built-In Functions

Tera offers many [built-in functions](https://keats.github.io/tera/docs/#built-in-functions).
`[]` indicates an optional function argument.
Some functions:

* `range(end, [start], [step_by])` - Returns an array of integers created
  using the arguments given.
  * `end: usize`: stop before `end`, mandatory
  * `start: usize`: where to start from, defaults to `0`
  * `step_by: usize`: with what number do we increment, defaults to `1`
* `now([timestamp], [utc])` - Returns the local datetime as string or
  the timestamp as integer.
  * `timestamp: bool`: whether to return the timestamp instead of the datetime
  * `utc: bool`: whether to return the UTC datetime instead of
    the local one
  * Tip: use date filter to format date string.
    e.g. `{{ now() | date(format="%Y") }}` gets the current year.
* `throw(message)` - Throws with the message.
* `get_random(end, [start])` - Returns a random integer in a range.
  * `end: usize`: upper end of the range
  * `start: usize`: defaults to 0
* `get_env(name, [default])`: Returns the environment variable value by name.
  Prefer `env` variable than this function.
  * `name: String`: the name of the environment variable
  * `default: String`: a default value in case the environment variable is not found.
    Throws when can't find the environment variable and `default` is not set.

Tera offers more functions. Read more on [tera documentation](https://keats.github.io/tera/docs/#functions).

#### Additional Mise Functions

Mise offers a slew of useful functions in addition to tera's built-ins.

##### General Functions

These functions are available in all tasks, and will always behave the same way regardless
of the task definition they are used in. In other words, their return values are consistent
across task definition(s).

* `exec(command) -> String` – Runs a shell command and returns its output as a string.
* `arch() -> String` – Retrieves the system architecture, such as `x64` or `arm64`.
* `os() -> String` – Returns the name of the operating system,
  e.g. linux, macos, windows.
* `os_family() -> String` – Returns the operating system family, e.g. `unix`, `windows`.
* `num_cpus() -> usize` – Gets the number of CPUs available on the system.
* `choice(n, alphabet)` - Generate a string of `n` with random sample with replacement
  of `alphabet`. For example, `choice(64, HEX)` will generate a random
  64-character lowercase hex string.
* `read_file(path) -> String` – Reads the contents of a file at the given path and returns
  it as a string.

##### Task-Specific Functions

These functions are task-specific and behave differently depending on the task they are used
in. In other words, their return values ***may*** (but are not guaranteed to) be consistent
across executions of any given *task*, and should be expected to be inconsisent across
different task definition(s).

For example, `task_source_files()` returns a different set of filepaths depending on the [`sources`](https://mise.jdx.dev/tasks/task-configuration.html#sources) of the task it's called from.

* `task_source_files() -> Vec<String>` – Returns the task's [`sources`](https://mise.jdx.dev/tasks/task-configuration.html#sources)
  as an array of resolved file paths. This function processes glob patterns and Tera template strings
  defined in the task's sources, expanding them into actual file paths. If a pattern doesn't match any
  files, it will be omitted from the result. Returns an empty array if no sources are configured or if
  no files match the patterns.

#### Examples

```toml
# Using exec to get command output
[alias.node.versions]
current = "{{ exec(command='node --version') }}"

# Using read_file to include content from a file
[env]
VERSION = "{{ read_file(path='VERSION') | trim }}"

# Access resolved source files in task scripts
[tasks.example]
sources = ["src/**/*.ts", "package.json"]
run = '''
{% for file in task_source_files() %}
  echo "Processing: {{ file }}"
{% endfor %}
'''
```

### Exec Options

The `exec` function supports the following options:

* `command: String` – \[required] The command to run.
* `cache_key: String` – The cache key to store the result.
  If the cache key is provided, the result will be cached and reused
  for subsequent calls.
* `cache_duration: String` – The duration to cache the result.
  The duration is in seconds, minutes, hours, days, or weeks.
  e.g. `cache_duration="1d"` will cache the result for 1 day.

### Filters

Tera offers many [built-in filters](https://keats.github.io/tera/docs/#built-in-filters).
`[]` indicates an optional filter argument.
Some filters:

* `str | lower -> String` – Converts a string to lowercase.
* `str | upper -> String` – Converts a string to uppercase.
* `str | capitalize -> String` – Converts a string with all its characters lowercased
  apart from the first char which is uppercased.
* `str | replace(from, to) -> String` – Replaces a string with all instances of
  `from` to `to`. e.g., `{{ name | replace(from="Robert", to="Bob")}}`
* `str | title -> String` – Capitalizes each word inside a sentence.
  e.g., `{{ "foo bar" | title }}` becomes `Foo Bar`.
* `str | trim -> String` – Removes leading and trailing whitespace.
* `str | trim_start -> String` – Removes leading whitespace.
* `str | trim_end -> String` – Removes trailing whitespace.
* `str | truncate -> String` – Truncates a string to the indicated length.
* `str | first -> String` – Returns the first element in an array or string.
* `str | last -> String` – Returns the last element in an array or string.
* `str | join(sep) -> String` – Joins an array of strings with a separator,
  such as `{{ ["a", "b", "c"] | join(sep=", ") }}`
  to produce `a, b, c`.
* `str | length -> usize` – Returns the length of a string or array.
* `str | reverse -> String` – Reverses the order of characters in a string or
  elements in an array.
* `str | urlencode -> String` – Encodes a string to be safely used in URLs,
  converting special characters to percent-encoded values.
* `arr | map(attribute) -> Array` – Extracts an attribute from each object
  in an array.
* `arr | concat(with) -> Array` – Appends values to an array.
* `num | abs -> Number` – Returns the absolute value of a number.
* `num | filesizeformat -> String` – Converts an integer into
  a human-readable file size (e.g., 110 MB).
* `str | date(format) -> String` – Converts a timestamp to
  a formatted date string using the provided format,
  such as `{{ ts | date(format="%Y-%m-%d") }}`.
  Find a list of time format on [`chrono` documentation](https://docs.rs/chrono/latest/chrono/format/strftime/index.html).
* `str | split(pat) -> Array` – Splits a string by the given pattern and
  returns an array of substrings.
* `str | default(value) -> String` – Returns the default value
  if the variable is not defined or is empty.

Tera offers more filters. Read more on [tera documentation](https://keats.github.io/tera/docs/#built-in-filters).

#### Hash

* `str | hash([algorithm], [len]) -> String` – Generates a hash for the input string.
  * `algorithm: "sha256" | "blake3"`: hash algorithm to use (default: `"sha256"`)
  * `len: usize`: truncates the hash string to the given size
  * Examples:
    * `{{ "foo" | hash }}` – SHA256 hash (default)
    * `{{ "foo" | hash(algorithm="blake3") }}` – BLAKE3 hash
    * `{{ "foo" | hash(len=8) }}` – SHA256 hash truncated to 8 characters
* `path | hash_file([len]) -> String` – Returns the BLAKE3 hash of the file
  at the given path.
  * `len: usize`: truncates the hash string to the given size

#### Path Manipulation

* `path | absolute -> String` – Converts the input path into
  an absolute path. Does not require the path to exist.
* `path | canonicalize -> String` – Converts the input path into
  absolute input path version. Throws if path doesn't exist.
* `path | basename -> String` – Extracts the file name from a path,
  e.g. `/foo/bar/baz.txt` becomes `baz.txt`.
* `path | file_size -> String` – Returns the size of a file in bytes.
* `path | dirname -> String` – Returns the directory path for a file,
  e.g. `/foo/bar/baz.txt` becomes `/foo/bar`.
* `path | basename -> String` – Returns the base name of a file,
  e.g. `/foo/bar/baz.txt` becomes `baz.txt`.
* `path | extname -> String` – Returns the extension of a file,
  e.g. `/foo/bar/baz.txt` becomes `.txt`.
* `path | file_stem -> String` – Returns the file name without the extension,
  e.g. `/foo/bar/baz.txt` becomes `baz`.
* `path | file_size -> String` – Returns the size of a file in bytes.
* `path | last_modified -> String` – Returns the last modified time of a file.
* `path[] | join_path -> String` – Joins an array of paths into a single path.

For example, you can use `split()`, `concat()`, and `join_path` filters to
construct a file path:

```toml
[env]
PROJECT_CONFIG = "{{ [config_root] | concat(with='bar.txt') | join_path }}"
```

#### String Manipulation

* `str | quote -> String` – Quotes a string. Converts `'` to `\'` and
  then quotes str, e.g `'it\'s str'`.
* `str | kebabcase -> String` – Converts a string to kebab-case
* `str | lowercamelcase -> String` – Converts a string to lowerCamelCase
* `str | uppercamelcase -> String` – Converts a string to UpperCamelCase
* `str | snakecase -> String` – Converts a string to snake\_case
* `str | shoutysnakecase -> String` – Converts a string to SHOUTY\_SNAKE\_CASE

### Tests

Tera offers many [built-in tests](https://keats.github.io/tera/docs/#built-in-tests).
Some tests:

* `defined` - Returns `true` if the given variable is defined.
* `string` - Returns `true` if the given variable is a string.
* `number` - Returns `true` if the given variable is a number.
* `starting_with` - Returns `true` if the given variable is a string and starts with
  the arg given.
* `ending_with` - Returns `true` if the given variable is a string and ends with
  the arg given.
* `containing` - Returns `true` if the given variable contains the arg given.
* `matching` - Returns `true` if the given variable is a string and matches the regex
  in the argument.

Tera offers more tests. Read more on [tera documentation](https://keats.github.io/tera/docs/#built-in-tests).

Mise offers additional tests:

* `if path is dir` – Checks if the provided path is a directory.
* `if path is file` – Checks if the path points to a file.
* `if path is exists` – Checks if the path exists.

---

---
url: /tips-and-tricks.md
---
# Tips & Tricks

An assortment of helpful tips for using `mise`.

## macOS Rosetta

If you have a need to run tools as x86\_64 on Apple Silicon, this can be done with mise however you'll currently
need to use the x86\_64 version of mise itself. A common reason for doing this is to support compiling node <=14.

You can do this either with the [`MISE_ARCH`](https://mise.jdx.dev/configuration/settings.html#arch)
setting or by using a dedicated rosetta mise bin as described below:

First, you'll need a copy of mise that's built for x86\_64:

```sh
$ curl https://mise.run | MISE_INSTALL_PATH=~/.local/bin/mise-x64 MISE_INSTALL_ARCH=x64 sh
$ ~/.local/bin/mise-x64 --version
mise 2024.x.x
```

::: warning
If `~/.local/bin` is not in PATH, you'll need to prefix all commands with `~/.local/bin/mise-x64`.
:::

Now you can use `mise-x64` to install tools:

```sh
mise-x64 use -g node@20
```

## Shebang

You can specify a tool and its version in a shebang without needing to first
set up a `mise.toml`/`.tool-versions` config:

```typescript
#!/usr/bin/env -S mise x node@20 -- node
// "env -S" allows multiple arguments in a shebang
console.log(`Running node: ${process.version}`);
```

This can also be useful in environments where mise isn't activated
(such as a non-interactive session).

## Bootstrap script

You can download the <https://mise.run> script to use in a project bootstrap script:

```sh
curl https://mise.run > setup-mise.sh
chmod +x setup-mise.sh
./setup-mise.sh
```

::: tip
This file contains checksums so it's more secure to commit it into your project rather than
calling `curl https://mise.run` dynamically—though of course this means it will only fetch
the version of mise that was current when the script was created.
:::

## Installation via zsh zinit

[Zinit](https://github.com/zdharma-continuum/zinit) is a plugin manager for ZSH, which this snippet you will get mise (and usage for shell completion):

```sh
zinit as="command" lucid from="gh-r" for \
    id-as="usage" \
    atpull="%atclone" \
    jdx/usage
    #atload='eval "$(mise activate zsh)"' \

zinit as="command" lucid from="gh-r" for \
    id-as="mise" mv="mise* -> mise" \
    atclone="./mise* completion zsh > _mise" \
    atpull="%atclone" \
    atload='eval "$(mise activate zsh)"' \
    jdx/mise
```

## CI/CD

Using mise in CI/CD is a great way to synchronize tool versions for dev/build.

### GitHub Actions

mise is pretty easy to use without an action:

```yaml
jobs:
  build:
    steps:
      - run: |
          curl https://mise.run | sh
          echo "$HOME/.local/bin" >> $GITHUB_PATH
          echo "$HOME/.local/share/mise/shims" >> $GITHUB_PATH
```

Or you can use the custom action [`jdx/mise-action`](https://github.com/jdx/mise-action):

```yaml
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: jdx/mise-action@v3
      - run: node -v # will be the node version from `mise.toml`/`.tool-versions`
```

## `mise set`

Instead of manually editing `mise.toml` to add env vars, you can use [`mise set`](/cli/set.html) instead:

```sh
mise set NODE_ENV=production
```

## [`mise run`](/cli/run.html) shorthand

As long as the task name doesn't conflict with a mise-provided command you can skip the `run` part:

```sh
mise test
```

::: warning
Don't do this inside of scripts because mise may add a command in a future version and could conflict with your task.
:::

## Software verification

mise provides **native software verification** for aqua tools without requiring external dependencies. For aqua tools, Cosign/Minisign signatures, SLSA provenance, and GitHub artifact attestations are verified automatically using mise's built-in implementation.

For other verification needs (like GPG), you can install additional tools:

```sh
brew install gpg
# Note: cosign and slsa-verifier are no longer needed for aqua tools
# mise now handles verification natively
```

To configure aqua verification (all enabled by default):

```sh
# Disable specific verification methods if needed
export MISE_AQUA_COSIGN=false
export MISE_AQUA_SLSA=false
export MISE_AQUA_GITHUB_ATTESTATIONS=false
export MISE_AQUA_MINISIGN=false
```

## [`mise up --bump`](/cli/upgrade.html)

Use `mise up --bump` to upgrade all software to the latest version and update `mise.toml` files. This keeps the same semver range as before,
so if you had `node = "22"` and node 24 is the latest, `mise up --bump node` will change `mise.toml` to `node = "24"`.

## cargo-binstall

cargo-binstall is sort of like ubi but specific to rust tools. It fetches binaries for cargo releases. mise will use this automatically for `cargo:` tools if it is installed
so if you use `cargo:` you should add this to make `mise i` go much faster.

```sh
mise use -g cargo-binstall
```

## [`mise cache clear`](/cli/cache.html)

mise caches things for obvious reasons but sometimes you want it to use fresh data (maybe it's not noticing a new release). Run `mise cache clear` to remove the cache which
basically just run `rm -rf ~/.cache/mise/*`.

## [`mise en`](/cli/en.html)

`mise en` is a great alternative to `mise activate` if you don't want to always be using mise for some reason. It sets up the mise environment in your current directory
but doesn't keep running and updating the env vars after that.

## Auto-install when entering a project

Auto-install tools when entering a project by adding the following to `mise.toml`:

```toml
[hooks]
enter = "mise i -q"
```

## [`mise tool [TOOL]`](/cli/tool.html)

Get information about what backend a tool is using and other information with `mise tool [TOOL]`:

```sh
❯ mise tool ripgrep
Backend:            aqua:BurntSushi/ripgrep
Installed Versions: 14.1.1
Active Version:     14.1.1
Requested Version:  latest
Config Source:      ~/src/mise/mise.toml
Tool Options:       [none]
```

## [`mise cfg`](/cli/config.html)

List the config files mise is reading in a particular directory with `mise cfg`:

```sh
❯ mise cfg
Path                                    Tools
~/.config/mise/config.toml              (none)
~/.mise/config.toml                     (none)
~/src/mise.toml                         (none)
~/src/mise/.config/mise/conf.d/foo.toml (none)
~/src/mise/mise.toml                    actionlint, bun, cargo-binstall, cargo:…
~/src/mise/mise.local.toml              (none)
```

This is helpful figuring out which order the config files are loaded in to figure out which one is overriding.

## `mise.lock`

When lockfiles are enabled, mise will update `mise.lock` with full versions and tarball checksums (if supported by the backend).
These can be updated with [`mise up`](/cli/upgrade.html). You need to manually create the lockfile, then mise will add the tools to it:

```sh
touch mise.lock
mise i
```

The lockfile uses a consolidated format with `[tools.name.assets]` sections to organize asset information under each tool. Asset information includes checksums, file sizes, and optional download URLs. Legacy lockfiles with separate `[tools.name.checksums]` and `[tools.name.sizes]` sections are automatically migrated to the new format.

Note that at least currently mise needs to actually install the tool to get the tarball checksum (otherwise it would need to download the tarball just
to get the checksum of it since normally that gets deleted). So you may need to run something like `mise uninstall --all` first in order to have it
reinstall everything. It will store the full versions even if it doesn't know the checksum though so it'll still lock the version just not have a checksum
to go with it.

## Lockfile URL Tracking (Avoiding Rate Limits)

When you use a lockfile (`mise.lock`), mise stores the exact download URLs for each tool asset. This means that after the initial install, future `mise install` runs will use the URLs from the lockfile instead of making API calls to GitHub (or other providers). This has several benefits:

* **Avoids GitHub API rate limits**: No need to make repeated API calls for every install, which can quickly exhaust your rate limit, especially in CI or large teams.
* **No need for GITHUB\_TOKEN**: Since the URLs are already known, you don’t need to set up a `GITHUB_TOKEN` for simple installs.
* **Faster installs**: Skipping API lookups speeds up repeated installs.

This is especially useful in CI/CD or when working in environments with strict network or authentication requirements.

---

---
url: /tasks/toml-tasks.md
---
# TOML-based Tasks

Tasks can be defined in `mise.toml` files in different ways. Trivial tasks can be written into a `[tasks]` section, while more detailed tasks each get their own section.

## Trivial task examples

```mise-toml [mise.toml]
build = "cargo build"
test = "cargo test"
lint = "cargo clippy"
```

## Detailed task examples

```mise-toml [mise.toml]
[tasks.cleancache]
run = "rm -rf .cache"
hide = true # hide this task from the list

[tasks.clean]
depends = ['cleancache']
run = "cargo clean" # runs as a shell command

[tasks.build]
description = 'Build the CLI'
run = "cargo build"
alias = 'b' # `mise run b`

[tasks.test]
description = 'Run automated tests'
# multiple commands are run in series
run = [
    'cargo test',
    './scripts/test-e2e.sh',
]
dir = "{{cwd}}" # run in user's cwd, default is the project's base directory

[tasks.lint]
description = 'Lint with clippy'
env = { RUST_BACKTRACE = '1' } # env vars for the script
# you can specify a multiline script instead of individual commands
run = '''
#!/usr/bin/env bash
cargo clippy
'''

[tasks.ci] # only dependencies to be run
description = 'Run CI tasks'
depends = ['build', 'lint', 'test']

[tasks.release]
confirm = 'Are you sure you want to cut a new release?'
description = 'Cut a new release'
file = 'scripts/release.sh' # execute an external script
```

You can use [environment variables](/environments/) or [`vars`](/tasks/task-configuration.html#vars-options) to define common arguments:

```mise-toml [mise.toml]
[env]
VERBOSE_ARGS = '--verbose'

# Vars can be shared between tasks like environment variables,
# but they are not passed as environment variables to the scripts
[vars]
e2e_args = '--headless'

[tasks.test]
run = './scripts/test-e2e.sh {{vars.e2e_args}} $VERBOSE_ARGS'
```

## Adding tasks

You can edit the `mise.toml` file directly or using [`mise tasks add`](/cli/tasks/add)

```shell
mise tasks add pre-commit --depends "test" --depends "render" -- echo pre-commit
```

will add the following to `mise.toml`:

```shell
[tasks.pre-commit]
depends = ["test", "render"]
run = "echo pre-commit"
```

## Common options

For an exhaustive list, see [task configuration](/tasks/task-configuration).

### Run command

Provide the script to run. Can be a single command or an array of commands:

```mise-toml
[tasks.test]
run = 'cargo test'
```

Commands are run in series. If a command fails, the task will stop and the remaining commands will not run.

```mise-toml
[tasks.test]
run = [
    'cargo test',
    './scripts/test-e2e.sh',
]
```

You can specify an alternate command to run on Windows by using the `run_windows` key:

```mise-toml
[tasks.test]
run = 'cargo test'
run_windows = 'cargo test --features windows'
```

### Specifying which directory to use

The [`dir`](/tasks/task-configuration.html#dir) property determines the `cwd` in which the task is executed. You can use the directory
from where the task was run with `dir = "{{cwd}}"`:

```mise-toml
[tasks.test]
run = 'cargo test'
dir = "{{cwd}}"
```

Also, `MISE_ORIGINAL_CWD` is set to the original working directory and will be passed to the task.

### Adding a description and alias

You can add a description to a task and alias for a task.

```mise-toml
[tasks.build]
description = 'Build the CLI'
run = "cargo build"
alias = 'b' # `mise run b`
```

* This alias can be used to run the task
* The description will be displayed when running [`mise tasks ls`](/cli/tasks/ls.html) or [`mise run`](/cli/run.html) with no arguments.

```shell
❯ mise run
Tasks
# Select a task to run
# > build  Build the CLI
#   test   Run the tests
```

### Dependencies

You can specify dependencies for a task. Dependencies are run before the task itself. If a dependency fails, the task will not run.

```mise-toml
[tasks.build]
run = 'cargo build'

[tasks.test]
depends = ['build']
```

There are other ways to specify dependencies, see [wait\_for](/tasks/task-configuration.html#wait-for) and [depends\_post](/tasks/task-configuration.html#depends-post)

### Environment variables

You can specify environment variables for a task:

```mise-toml
[tasks.lint]
description = 'Lint with clippy'
env = { RUST_BACKTRACE = '1' } # env vars for the script
# you can specify a multiline script instead of individual commands
run = '''
#!/usr/bin/env bash
cargo clippy
'''
```

### Sources / Outputs

If you want to skip executing a task if certain files haven't changed (up-to-date), you should specify `sources` and `outputs`:

```mise-toml
[tasks.build]
description = 'Build the CLI'
run = "cargo build"
sources = ['Cargo.toml', 'src/**/*.rs'] # skip running if these files haven't changed
outputs = ['target/debug/mycli']
```

You can use `sources` alone if with [`mise watch`](/cli/watch.html) to run the task when the sources change.
You can use the [`task_source_files()`](../templates.md#task-source-files) function to get the resolved paths of a task's `sources` from within
its [template](../templates.md).

### Confirmation

A message to show before running the task. The user will be prompted to confirm before the task is run.

```mise-toml
[tasks.release]
confirm = 'Are you sure you want to cut a new release?'
description = 'Cut a new release'
file = 'scripts/release.sh'
```

## Specifying a shell or an interpreter {#shell-shebang}

Tasks are executed with `set -e` (`set -o erropt`) if the shell is `sh`, `bash`, or `zsh`. This means that the script
will exit if any command fails. You can disable this by running `set +e` in the script.

```mise-toml
[tasks.echo]
run = '''
set +e
cd /nonexistent
echo "This will not fail the task"
'''
```

You can specify a `shell` command to run the script with (default is [`sh -c`](/configuration/settings.html#unix_default_inline_shell_args) or [`cmd /c`](/configuration/settings.html#windows_default_inline_shell_args)):

```mise-toml
[tasks.lint]
shell = 'bash -c'
run = "cargo clippy"
```

or use a shebang:

```mise-toml
[tasks.lint]
run = '''
#!/usr/bin/env bash
cargo clippy
'''
```

By using a `shebang` (or `shell`), you can run tasks in different languages (e.g., Python, Node.js, Ruby, etc.):

::: code-group

```mise-toml [python]
[tools]
python = 'latest'

[tasks.python_task]
run = '''
#!/usr/bin/env python
for i in range(10):
    print(i)
'''
```

```mise-toml [python + uv]
[tools]
uv = 'latest'

[tasks.python_uv_task]
run = '''
#!/usr/bin/env -S uv run --script
# /// script
# dependencies = ["requests<3", "rich"]
# ///

import requests
from rich.pretty import pprint

resp = requests.get("https://peps.python.org/api/peps.json")
data = resp.json()
pprint([(k, v["title"]) for k, v in data.items()][:10])
'''
```

```mise-toml [node]
[tools]
node = 'lts'

[tasks.node_task]
shell = 'node -e'
run = [
  "console.log('First line')",
  "console.log('Second line')",
]
```

```mise-toml [bun]
[tools]
bun = 'latest'

[tasks.bun_shell]
description = "https://bun.sh/docs/runtime/shell"
run = '''
#!/usr/bin/env bun

import { $ } from "bun";
const response = await fetch("https://example.com");
await $`cat < ${response} | wc -c`; // 1256
'''
```

```mise-toml [deno]
[tools]
deno = 'latest'

[tasks.deno_task]
description = "A more complex task using Deno imports"
run = '''
#!/usr/bin/env -S deno run
import ProgressBar from "jsr:@deno-library/progress";
import { delay } from "jsr:@std/async";

if (!confirm('Start download?')) {
    Deno.exit(1);
}

const progress = new ProgressBar({ title:  "downloading:", total: 100 });
let completed = 0;
async function download() {
  while (completed <= 100) {
    await progress.render(completed++);
    await delay(10);
  }
}
await download();
'''
# ❯ mise run deno_task
# [download_task] $ import ProgressBar from "jsr:@deno-library/progress";
# Start download? [y/N] y
# downloading: ...
```

```mise-toml [ruby]
[tools]
ruby = 'latest'

[tasks.ruby_task]
run = '''
#!/usr/bin/env ruby
puts 'Hello, ruby!'
'''
```

:::

::: details What's a shebang? What's the difference between `#!/usr/bin/env` and `#!/usr/bin/env -S`

A shebang is the character sequence `#!` at the beginning of a script file that tells the system which program should be used to interpret/execute the script.
The [env command](https://manpages.ubuntu.com/manpages/jammy/man1/env.1.html) comes from GNU Coreutils. `mise` does not use `env` but will behave similarly.

For example, `#!/usr/bin/env python` will run the script with the Python interpreter found in the `PATH`.

The `-S` flag allows passing multiple arguments to the interpreter.
It treats the rest of the line as a single argument string to be split.

This is useful when you need to specify interpreter flags or options.
Example: `#!/usr/bin/env -S python -u` will run Python with unbuffered output.

:::

## Using a file or remote script

You can specify a file to run as a task:

```mise-toml
[tasks.release]
description = 'Cut a new release'
file = 'scripts/release.sh' # execute an external script
```

### Remote tasks

Task files can be fetched remotely with multiple protocols:

#### HTTP

```mise-toml
[tasks.build]
file = "https://example.com/build.sh"
```

Please note that the file will be downloaded and executed. Make sure you trust the source.

#### Git&#x20;

::: code-group

```mise-toml [ssh]
[tasks.build]
file = "git::ssh://git@github.com/myorg/example.git//myfile?ref=v1.0.0"
```

```mise-toml [https]
[tasks.build]
file = "git::https://github.com/myorg/example.git//myfile?ref=v1.0.0"
```

:::

Url format must follow these patterns `git::<protocol>://<url>//<path>?<ref>`

Required fields:

* `protocol`: The git repository URL.
* `url`: The git repository URL.
* `path`: The path to the file in the repository.

Optional fields:

* `ref`: The git reference (branch, tag, commit).

#### Cache

Each task file is cached in the `MISE_CACHE_DIR` directory. If the file is updated, it will not be re-downloaded unless the cache is cleared.

:::tip
You can reset the cache by running `mise cache clear`.
:::

You can use the `MISE_TASK_REMOTE_NO_CACHE` environment variable to disable caching of remote tasks.

## Arguments

::: tip
For comprehensive information about task arguments, see the dedicated [Task Arguments](/tasks/task-arguments) page.
:::

By default, arguments are passed to the last script in the `run` array. So if a task was defined as:

```mise-toml
[tasks.test]
run = ['cargo test', './scripts/test-e2e.sh']
```

Then running `mise run test foo bar` will pass `foo bar` to `./scripts/test-e2e.sh` but not to
`cargo test`.

### Recommended: Using the Usage Field

The recommended way to define arguments is using the `usage` field:

```mise-toml
[tasks.test]
usage = '''
arg "<file>" help="Test file to run" default="all"
flag "--format <format>" help="Output format" default="text"
flag "-v --verbose" help="Enable verbose output"
'''
run = 'cargo test ${usage_file?} --format ${usage_format?}'
```

Arguments defined in the usage field are available as environment variables prefixed with `usage_`.

See the [Task Arguments](/tasks/task-arguments#usage-field) page for complete documentation.

### Tera Template Functions&#x20;

::: danger Deprecated - Removal in 2026.11.0
Using Tera template functions (`arg()`, `option()`, `flag()`) in run scripts is **deprecated** and will be **removed in mise 2026.11.0**. Versions >= 2026.5.0 will show a deprecation warning.

**Why it's being removed:**

* Template functions return empty strings during spec collection (two-pass parsing issue)
* Complex and unpredictable shell escaping rules
* Doesn't work consistently between TOML/file tasks

**Please migrate to using the `usage` field instead.** See the [migration guide](/tasks/task-arguments#tera-templates).
:::

You can define arguments using Tera template functions (deprecated):

```mise-toml
[tasks.test]
run = [
    'cargo test {{arg(name="cargo_test_args", var=true)}}',
    './scripts/test-e2e.sh {{option(name="e2e_args")}}',
]
```

Then running `mise run test foo bar` will pass `foo bar` to `cargo test`.
`mise run test --e2e-args baz` will pass `baz` to `./scripts/test-e2e.sh`.

#### Positional Arguments

These are defined in scripts with `{{arg()}}`. They are used for positional
arguments where the order matters.

Example:

```mise-toml
[tasks.test]
run = 'cargo test {{arg(name="file")}}'
# execute: mise run test my-test-file
# runs: cargo test my-test-file
```

* `i`: The index of the argument. This can be used to specify the order of arguments. Defaults to
  the order they're defined in the scripts.
* `name`: The name of the argument. This is used for help/error messages.
* `var`: If `true`, multiple arguments can be passed.
* `default`: The default value if the argument is not provided.

#### Options

These are defined in scripts with `{{option()}}`. They are used for named
arguments where the order doesn't matter.

Example:

```mise-toml
[tasks.test]
run = 'cargo test {{option(name="file")}}'
# execute: mise run test --file my-test-file
# runs: cargo test my-test-file
```

* `name`: The name of the argument. This is used for help/error messages.
* `var`: If `true`, multiple values can be passed.
* `default`: The default value if the option is not provided.

#### Flags

Flags are like options except they don't take values. They are defined in scripts with&#x20;
`{{flag()}}`.

Examples:

```mise-toml
[tasks.echo]
run = 'echo {{flag(name="myflag")}}'
# execute: mise run echo --myflag
# runs: echo true
```

```mise-toml
[tasks.maybeClean]
run = '''
if [ '{{flag(name='clean')}}' = 'true' ]; then
  echo 'cleaning'
fi
'''
# execute: mise run maybeClean --clean
# runs: echo cleaning
```

* `name`: The name of the flag. This is used for help/error messages.

The value will be `true` if the flag is passed, and `false` otherwise.

---

---
url: /dev-tools/aliases.md
---
# Tool Aliases

::: tip
`[alias]` has been renamed to `[tool_alias]` to distinguish it from `[shell_alias]`.
The old `[alias]` key still works but is deprecated.

For shell command aliases (like `alias ll='ls -la'`), see [Shell Aliases](/shell-aliases).
:::

## Aliased Backends

Tools can be aliased so that something like `node` which normally maps to `core:node` can be changed
to something like `asdf:company/our-custom-node` instead.

```toml [~/.config/mise/config.toml]
[tool_alias]
node = 'asdf:company/our-custom-node' # shorthand for https://github.com/company/our-custom-node
erlang = 'asdf:https://github.com/company/our-custom-erlang'
```

## Aliased Versions

mise supports aliasing the versions of runtimes. One use-case for this is to define aliases for LTS
versions of runtimes. For example, you may want to specify `lts-hydrogen` as the version for <node@20.x>
so you can use set it with `node lts-hydrogen` in `mise.toml`/`.tool-versions`.

User aliases can be created by adding a `tool_alias.<PLUGIN>` section to `~/.config/mise/config.toml`:

```toml
[tool_alias.node.versions]
my_custom_20 = '20'
```

Plugins can also provide aliases via a `bin/list-aliases` script. Here is an example showing node.js
versions:

```bash
#!/usr/bin/env bash

echo "lts-hydrogen 18"
echo "lts-gallium 16"
echo "lts-fermium 14"
```

::: info
Because this is mise-specific functionality not currently used by asdf it isn't likely to be in any
plugin currently, but plugin authors can add this script without impacting asdf users.
:::

## Templates

Alias values can be templates, see [Templates](/templates) for details.

```toml
[tool_alias.node.versions]
current = "{{exec(command='node --version')}}"
```

---

---
url: /tool-plugin-development.md
---
# Tool Plugin Development

::: tip
The [mise-tool-plugin-template](https://github.com/jdx/mise-tool-plugin-template) provides a ready-to-use starting point with LuaCATS type definitions, stylua formatting, and hk linting pre-configured.
:::

Tool plugins use a hook-based architecture to manage individual tools. They are compatible with the standard vfox ecosystem and are perfect for tools that need complex installation logic, environment configuration, or legacy file parsing.

## What are Tool Plugins?

Tool plugins use traditional hook functions to manage a single tool. They provide:

* **Standard vfox Compatibility**: Works with both mise and vfox
* **Complex Installation Logic**: Handle source compilation, custom builds, and complex setups
* **Environment Configuration**: Set up complex environment variables beyond just PATH
* **Legacy File Support**: Parse version files from other tools (`.nvmrc`, `.tool-version`, etc.)
* **Cross-Platform Support**: Works on Windows, macOS, and Linux

## Plugin Architecture

Tool plugins are implemented in Lua (version 5.1 at the moment). They use a hook-based architecture with specific functions for different lifecycle events:

```mermaid
graph TD
    A[User Request] --> B[mise CLI]
    B --> C[Tool Plugin]

    C --> D[Available Hook<br/>List Versions]
    C --> E[PreInstall Hook<br/>Download]
    C --> F[PostInstall Hook<br/>Setup]
    C --> G[EnvKeys Hook<br/>Configure]

    subgraph "Plugin Files"
        H[metadata.lua]
        I[hooks/available.lua]
        J[hooks/pre_install.lua]
        K[hooks/env_keys.lua]
        L[hooks/post_install.lua]
    end

    style C fill:#e1f5fe
    style D fill:#e8f5e8
    style E fill:#e8f5e8
    style F fill:#e8f5e8
    style G fill:#e8f5e8
```

## Hook Functions

### Required Hooks

These hooks must be implemented for a functional plugin:

#### Available Hook

Lists all available versions of the tool:

```lua
-- hooks/available.lua
function PLUGIN:Available(ctx)
    local args = ctx.args  -- User arguments

    -- Return array of available versions
    return {
        {
            version = "20.0.0",
            note = "Latest"
        },
        {
            version = "18.18.0",
            note = "LTS",
            addition = {
                {
                    name = "npm",
                    version = "9.8.1"
                }
            }
        }
    }
end
```

##### Rolling Releases

For tools that have rolling releases like "nightly" or "stable" where the version string stays the same but the content changes, you can mark versions as rolling and provide a checksum for update detection:

```lua
function PLUGIN:Available(ctx)
    return {
        {
            version = "nightly",
            note = "Latest development build",
            rolling = true,  -- Mark as rolling release
            checksum = "abc123..."  -- SHA256 of the release asset
        },
        {
            version = "stable",
            note = "Latest stable release",
            rolling = true,
            checksum = "def456..."
        },
        {
            version = "1.0.0",
            note = "Fixed release"
            -- No rolling or checksum needed for fixed versions
        }
    }
end
```

When `rolling = true` is set:

* `mise upgrade` will check if the checksum has changed to detect updates
* `mise upgrade --bump` will preserve the version name (e.g., "nightly") instead of converting it to a semver

The checksum should be the SHA256 hash of the release asset for the user's platform. See the [vfox-neovim plugin](https://github.com/mise-plugins/vfox-neovim) for a complete example.

#### PreInstall Hook

Handles pre-installation logic and returns download information:

```lua
-- hooks/pre_install.lua
function PLUGIN:PreInstall(ctx)
    local version = ctx.version
    local runtimeVersion = ctx.runtimeVersion

    -- Determine download URL and checksums
    local url = "https://nodejs.org/dist/v" .. version .. "/node-v" .. version .. "-linux-x64.tar.gz"

    return {
        version = version,
        url = url,
        sha256 = "abc123...",  -- Optional checksum
        note = "Installing Node.js " .. version,
        -- Optional attestation metadata, choose a verification type
        attestation = {
            -- GitHub
            github_owner = "ownername"
            github_repo = "reponame"
            -- Cosign
            cosign_sig_or_bundle_path = "/path/to/sig/or/bundle/file"
            -- SLSA
            slsa_provenance_path = "/path/to/provenance/file"
        },
        -- Additional files can be specified
        addition = {
            {
                name = "npm",
                url = "https://registry.npmjs.org/npm/-/npm-" .. npm_version .. ".tgz"
            }
        }
    }
end
```

#### EnvKeys Hook

Configures environment variables for the installed tool:

```lua
-- hooks/env_keys.lua
function PLUGIN:EnvKeys(ctx)
    local mainPath = ctx.path
    local runtimeVersion = ctx.runtimeVersion
    local sdkInfo = ctx.sdkInfo['nodejs']
    local path = sdkInfo.path
    local version = sdkInfo.version
    local name = sdkInfo.name

    return {
        {
            key = "NODE_HOME",
            value = mainPath
        },
        {
            key = "PATH",
            value = mainPath .. "/bin"
        },
        -- Multiple PATH entries are automatically merged
        {
            key = "PATH",
            value = mainPath .. "/lib/node_modules/.bin"
        }
    }
end
```

### Optional Hooks

These hooks provide additional functionality:

#### PostInstall Hook

Performs additional setup after installation:

```lua
-- hooks/post_install.lua
function PLUGIN:PostInstall(ctx)
    local rootPath = ctx.rootPath
    local runtimeVersion = ctx.runtimeVersion
    local sdkInfo = ctx.sdkInfo['nodejs']
    local path = sdkInfo.path
    local version = sdkInfo.version

    -- Compile native modules, set permissions, etc.
    local result = os.execute("chmod +x " .. path .. "/bin/*")
    if result ~= 0 then
        error("Failed to set permissions")
    end

    -- No return value needed
end
```

#### PreUse Hook

Modifies version before use:

```lua
-- hooks/pre_use.lua
function PLUGIN:PreUse(ctx)
    local version = ctx.version
    local previousVersion = ctx.previousVersion
    local installedSdks = ctx.installedSdks
    local cwd = ctx.cwd
    local scope = ctx.scope  -- global/project/session

    -- Optionally modify the version
    if version == "latest" then
        version = "20.0.0"  -- Resolve to specific version
    end

    return {
        version = version
    }
end
```

#### ParseLegacyFile Hook

Parses version files from other tools:

```lua
-- hooks/parse_legacy_file.lua
function PLUGIN:ParseLegacyFile(ctx)
    local filename = ctx.filename
    local filepath = ctx.filepath
    local versions = ctx:getInstalledVersions()

    -- Read and parse the file
    local file = require("file")
    local content = file.read(filepath)
    local version = content:match("v?([%d%.]+)")

    return {
        version = version
    }
end
```

## Creating a Tool Plugin

### Using the Template Repository

The easiest way to create a new tool plugin is to use the [mise-tool-plugin-template](https://github.com/jdx/mise-tool-plugin-template) repository as a starting point:

```bash
# Clone the template
git clone https://github.com/jdx/mise-tool-plugin-template my-tool-plugin
cd my-tool-plugin

# Remove the template's git history and start fresh
rm -rf .git
git init

# Customize the plugin for your tool
# Edit metadata.lua, hooks/*.lua files, etc.
```

The template includes:

* Pre-configured plugin structure with all required hooks
* Example implementations with comments
* Linting configuration (`.luacheckrc`, `stylua.toml`)
* Testing setup with mise tasks
* GitHub Actions workflow for CI

### 1. Plugin Structure

Create a directory with this structure (or use the template above):

```
my-tool-plugin/
├── metadata.lua          # Plugin metadata and configuration
├── hooks/               # Hook functions directory
│   ├── available.lua    # List available versions [required]
│   ├── pre_install.lua  # Pre-installation hook [required]
│   ├── env_keys.lua     # Environment configuration [required]
│   ├── post_install.lua # Post-installation hook [optional]
│   ├── pre_use.lua      # Pre-use hook [optional]
│   └── parse_legacy_file.lua # Legacy file parser [optional]
├── lib/                 # Shared library code [optional]
│   └── helper.lua       # Helper functions
└── test/               # Test scripts [optional]
    └── test.sh
```

### 2. metadata.lua

Configure plugin metadata and legacy file support:

```lua
-- metadata.lua
PLUGIN = {
    name = "nodejs",
    version = "1.0.0",
    description = "Node.js runtime environment",
    author = "Plugin Author",

    -- Legacy version files this plugin can parse
    legacyFilenames = {
        '.nvmrc',
        '.node-version'
    }
}
```

### 3. Helper Libraries

Create shared functions in the `lib/` directory:

```lua
-- lib/helper.lua
local M = {}

function M.get_arch()
    -- Use the RUNTIME object provided by vfox/mise
    local arch = RUNTIME.archType
    if arch == "amd64" then
        return "x64"
    elseif arch == "386" then
        return "x86"
    elseif arch == "arm64" then
        return "arm64"
    else
        return arch  -- return as-is for other architectures
    end
end

function M.get_os()
    -- Use the RUNTIME object provided by vfox/mise
    local os = RUNTIME.osType
    if os == "Windows" then
        return "win"
    elseif os == "Darwin" then
        return "darwin"
    else
        return "linux"
    end
end

function M.get_platform()
    return M.get_os() .. "-" .. M.get_arch()
end

return M
```

## Real-World Example: vfox-nodejs

Here's a complete example based on the vfox-nodejs plugin that demonstrates all the concepts:

### Available Hook Example

```lua
-- hooks/available.lua
function PLUGIN:Available(ctx)
    local http = require("http")
    local json = require("json")

    -- Fetch versions from Node.js API
    local resp, err = http.get({
        url = "https://nodejs.org/dist/index.json"
    })

    if err ~= nil then
        error("Failed to fetch versions: " .. err)
    end

    local versions = json.decode(resp.body)
    local result = {}

    for i, v in ipairs(versions) do
        local version = v.version:gsub("^v", "")  -- Remove 'v' prefix
        local note = nil

        if v.lts then
            note = "LTS"
        end

        table.insert(result, {
            version = version,
            note = note,
            addition = {
                {
                    name = "npm",
                    version = v.npm
                }
            }
        })
    end

    return result
end
```

### PreInstall Hook Example

```lua
-- hooks/pre_install.lua
function PLUGIN:PreInstall(ctx)
    local version = ctx.version

    -- Determine platform using RUNTIME object
    local arch_token
    if RUNTIME.archType == "amd64" then
        arch_token = "x64"
    elseif RUNTIME.archType == "386" then
        arch_token = "x86"
    elseif RUNTIME.archType == "arm64" then
        arch_token = "arm64"
    else
        arch_token = RUNTIME.archType
    end
    local os_token
    if RUNTIME.osType == "Windows" then
        os_token = "win"
    elseif RUNTIME.osType == "Darwin" then
        os_token = "darwin"
    else
        os_token = "linux"
    end
    local platform = os_token .. "-" .. arch_token
    local extension = (RUNTIME.osType == "Windows") and "zip" or "tar.gz"

    -- Build download URL
    local filename = "node-v" .. version .. "-" .. platform .. "." .. extension
    local url = "https://nodejs.org/dist/v" .. version .. "/" .. filename

    -- Fetch checksum
    local http = require("http")
    local shasums_url = "https://nodejs.org/dist/v" .. version .. "/SHASUMS256.txt"
    local resp, err = http.get({ url = shasums_url })

    local sha256 = nil
    if err == nil then
        -- Extract SHA256 for our file
        for line in resp.body:gmatch("[^\n]+") do
            if line:match(filename) then
                sha256 = line:match("^(%w+)")
                break
            end
        end
    end

    return {
        version = version,
        url = url,
        sha256 = sha256,
        note = "Installing Node.js " .. version .. " (" .. platform .. ")"
    }
end
```

### EnvKeys Hook Example

```lua
-- hooks/env_keys.lua
function PLUGIN:EnvKeys(ctx)
    local mainPath = ctx.path
    local os_type = RUNTIME.osType

    local env_vars = {
        {
            key = "NODE_HOME",
            value = mainPath
        },
        {
            key = "PATH",
            value = mainPath .. "/bin"
        }
    }

    -- Add npm global modules to PATH
    local npm_global_path = mainPath .. "/lib/node_modules/.bin"
    if os_type == "Windows" then
        npm_global_path = mainPath .. "/node_modules/.bin"
    end

    table.insert(env_vars, {
        key = "PATH",
        value = npm_global_path
    })

    return env_vars
end
```

### PostInstall Hook Example

```lua
-- hooks/post_install.lua
function PLUGIN:PostInstall(ctx)
    local sdkInfo = ctx.sdkInfo['nodejs']
    local path = sdkInfo.path
    -- Set executable permissions on Unix systems
    if RUNTIME.osType ~= "Windows" then
        os.execute("chmod +x " .. path .. "/bin/*")
    end

    -- Create npm cache directory
    local npm_cache_dir = path .. "/.npm"
    os.execute("mkdir -p " .. npm_cache_dir)

    -- Configure npm to use local cache
    local npm_cmd = path .. "/bin/npm"
    if RUNTIME.osType == "Windows" then
        npm_cmd = path .. "/npm.cmd"
    end

    os.execute(npm_cmd .. " config set cache " .. npm_cache_dir)
    os.execute(npm_cmd .. " config set prefix " .. path)
end
```

### Legacy File Support

```lua
-- hooks/parse_legacy_file.lua
function PLUGIN:ParseLegacyFile(ctx)
    local filename = ctx.filename
    local filepath = ctx.filepath
    local file = require("file")

    -- Read file content
    local content = file.read(filepath)
    if not content then
        error("Failed to read " .. filepath)
    end

    -- Parse version from different file formats
    local version = nil

    if filename == ".nvmrc" then
        -- .nvmrc can contain version with or without 'v' prefix
        version = content:match("v?([%d%.]+)")
    elseif filename == ".node-version" then
        -- .node-version typically contains just the version number
        version = content:match("([%d%.]+)")
    end

    -- Remove any whitespace
    if version then
        version = version:gsub("%s+", "")
    end

    return {
        version = version
    }
end
```

## Testing Your Plugin

### Local Development

```bash
# Link your plugin for development
mise plugin link my-tool /path/to/my-tool-plugin

# Test listing versions
mise ls-remote my-tool

# Test installation
mise install my-tool@1.0.0

# Test environment setup
mise use my-tool@1.0.0
my-tool --version

# Test legacy file parsing (if applicable)
echo "2.0.0" > .my-tool-version
mise use my-tool
```

If you're using the template repository, you can run the included tests:

```bash
# Run linting
mise run lint

# Run tests
mise run test
```

### Debug Mode

Use debug mode to see detailed plugin execution:

```bash
mise --debug install nodejs@20.0.0
```

### Plugin Test Script

Create a comprehensive test script:

```bash
#!/bin/bash
# test/test.sh
set -e

echo "Testing nodejs plugin..."

# Install the plugin
mise plugin install nodejs .

# Test basic functionality
mise install nodejs@18.18.0
mise use nodejs@18.18.0

# Verify installation
node --version | grep "18.18.0"
npm --version

# Test legacy file support
echo "20.0.0" > .nvmrc
mise use nodejs
node --version | grep "20.0.0"

# Clean up
rm -f .nvmrc
mise plugin remove nodejs

echo "All tests passed!"
```

## Best Practices

### Error Handling

Always provide meaningful error messages:

```lua
function PLUGIN:Available(ctx)
    local http = require("http")
    local resp, err = http.get({
        url = "https://api.example.com/versions"
    })

    if err ~= nil then
        error("Failed to fetch versions from API: " .. err)
    end

    if resp.status_code ~= 200 then
        error("API returned status " .. resp.status_code .. ": " .. resp.body)
    end

    -- Process response...
end
```

### Platform Detection

Handle different operating systems properly using the RUNTIME object:

```lua
-- lib/platform.lua
local M = {}

function M.is_windows()
    return RUNTIME.osType == "Windows"
end

function M.get_exe_extension()
    return M.is_windows() and ".exe" or ""
end

function M.get_path_separator()
    return M.is_windows() and "\\" or "/"
end

return M
```

**Note:** The `RUNTIME` object is automatically available in all plugin hooks and provides:

* `RUNTIME.osType`: Operating system type ("Windows", "Linux", "Darwin")
* `RUNTIME.archType`: Architecture ("amd64", "arm64", "386", etc.)

### Version Normalization

Normalize versions consistently:

```lua
local function normalize_version(version)
    -- Remove 'v' prefix if present
    version = version:gsub("^v", "")

    -- Remove pre-release suffixes
    version = version:gsub("%-.*", "")

    return version
end
```

### Caching

Cache expensive operations:

```lua
-- Cache versions for 12 hours
local cache = {}
local cache_ttl = 12 * 60 * 60  -- 12 hours in seconds

function PLUGIN:Available(ctx)
    local now = os.time()

    -- Check cache first
    if cache.versions and cache.timestamp and (now - cache.timestamp) < cache_ttl then
        return cache.versions
    end

    -- Fetch fresh data
    local versions = fetch_versions_from_api()

    -- Update cache
    cache.versions = versions
    cache.timestamp = now

    return versions
end
```

## Advanced Features

### Conditional Installation

Different installation logic based on platform or version:

```lua
function PLUGIN:PreInstall(ctx)
    local version = ctx.version

    -- Different logic for different platforms using RUNTIME object
    if RUNTIME.osType == "Windows" then
        -- Windows-specific installation
        return install_windows(version)
    elseif RUNTIME.osType == "Darwin" then
        -- macOS-specific installation
        return install_macos(version)
    else
        -- Linux installation
        return install_linux(version)
    end
end
```

### Source Compilation

For plugins that need to compile from source:

```lua
-- hooks/post_install.lua
function PLUGIN:PostInstall(ctx)
    local sdkInfo = ctx.sdkInfo['tool-name']
    local path = sdkInfo.path
    local version = sdkInfo.version

    -- Change to source directory
    local build_dir = path .. "/src"

    -- Configure build
    local configure_result = os.execute("cd " .. build_dir .. " && ./configure --prefix=" .. path)
    if configure_result ~= 0 then
        error("Configure failed")
    end

    -- Compile
    local make_result = os.execute("cd " .. build_dir .. " && make -j$(nproc)")
    if make_result ~= 0 then
        error("Compilation failed")
    end

    -- Install
    local install_result = os.execute("cd " .. build_dir .. " && make install")
    if install_result ~= 0 then
        error("Installation failed")
    end
end
```

### Environment Configuration

Complex environment variable setup:

```lua
function PLUGIN:EnvKeys(ctx)
    local mainPath = ctx.path
    local version = ctx.sdkInfo['tool-name'].version

    local env_vars = {
        -- Standard environment variables
        {
            key = "TOOL_HOME",
            value = mainPath
        },
        {
            key = "TOOL_VERSION",
            value = version
        },

        -- PATH entries
        {
            key = "PATH",
            value = mainPath .. "/bin"
        },
        {
            key = "PATH",
            value = mainPath .. "/scripts"
        },

        -- Library paths
        {
            key = "LD_LIBRARY_PATH",
            value = mainPath .. "/lib"
        },
        {
            key = "PKG_CONFIG_PATH",
            value = mainPath .. "/lib/pkgconfig"
        }
    }

    -- Platform-specific additions
    if RUNTIME.osType == "Darwin" then
        table.insert(env_vars, {
            key = "DYLD_LIBRARY_PATH",
            value = mainPath .. "/lib"
        })
    end

    return env_vars
end
```

## Next Steps

* [Start with the plugin template](https://github.com/jdx/mise-tool-plugin-template)
* [Learn about Backend Plugin Development](backend-plugin-development.md)
* [Explore available Lua modules](plugin-lua-modules.md)
* [Publishing your plugin](plugin-publishing.md)
* [View the vfox-nodejs plugin source](https://github.com/version-fox/vfox-nodejs)

---

---
url: /dev-tools/tool-stubs.md
---
# Tool Stubs

Tool stubs allow you to create executable files with embedded TOML configuration for tool execution. They provide a convenient way to define tool versions, backends, and execution parameters directly within executable scripts. They are also a good way to have some tools in mise lazy-load since the tools are only fetched when called and not when calling something like `mise install`.

This feature is inspired by [dotslash](https://github.com/facebook/dotslash), which pioneered the concept of executable files with embedded configuration for portable tool execution.

## Overview

A tool stub is an executable file that begins with a shebang line pointing to `mise tool-stub` and contains TOML configuration specifying which tool to execute and how to execute it. When the stub is run, mise automatically installs the specified tool version (if needed) and executes it with the provided arguments.

Tool stubs can use any mise backend but because they default to http—and http backend tools have things like urls and don't require a version—the http stubs look a bit different than non-http stubs.

::: tip
Tool stubs are particularly useful for adding less-commonly used tools to your mise setup. Since tools are only installed when their stub is first executed, you can define many tools without the overhead of installing them all upfront. This is perfect for specialized tools, testing utilities, or project-specific binaries that you might not use every day.
:::

## Tool (non-http) Stubs

```bash
#!/usr/bin/env -S mise tool-stub
# Optional comment describing the tool

version = "1.0.0"
tool = "python"
bin = "python"
```

::: info Why use `env -S`?
The `-S` flag tells `env` to split the command line on spaces, allowing multiple arguments to be passed to the interpreter. This is necessary because shebangs on Unix systems traditionally only support a single argument after the interpreter path. Using `env -S mise tool-stub` allows the shebang to work correctly by splitting it into `env` → `mise` → `tool-stub`.
:::

## Configuration Fields

Tool stub configuration is essentially a subset of what can be done in `mise.toml` \[tools] sections, with the addition of a `tool` field to specify which tool to use. All the same options available for tool configuration in `mise.toml` are supported in tool stubs.

### Optional Fields

* `tool` - Explicit tool name or backend specification (e.g., "python", "github:cli/cli"). This is the only field unique to tool stubs - it specifies which tool entry from the configuration to use. If omitted and a `url` field is present, defaults to the HTTP backend.
* `version` - The version of the tool to use
* `bin` - The binary name to execute within the tool (defaults to the stub filename)

## HTTP Stubs

For multi-platform tarballs:

```toml
#!/usr/bin/env -S mise tool-stub
url = "https://example.com/releases/1.0.0/tool-linux-x64.tar.gz"
```

For platform-specific tarballs:

```toml
#!/usr/bin/env -S mise tool-stub
[platforms.linux-x64]
url = "https://example.com/releases/1.0.0/tool-linux-x64.tar.gz"

[platforms.darwin-arm64]
url = "https://example.com/releases/1.0.0/tool-macos-arm64.tar.gz"
```

### Platform-Specific Binary Paths

Different platforms may have different binary structures or names. You can specify platform-specific `bin` fields when the binary path differs between platforms:

```toml
#!/usr/bin/env -S mise tool-stub
# Global bin field used when platforms have the same structure
bin = "bin/tool"

[platforms.linux-x64]
url = "https://example.com/tool-linux.tar.gz"
# Uses global bin field: "bin/tool"

[platforms.windows-x64]
url = "https://example.com/tool-windows.zip"
bin = "tool.exe"  # Platform-specific binary for Windows
```

The tool stub generator automatically detects when platforms have different binary paths and will generate platform-specific `bin` fields when needed, or use a global `bin` field when all platforms have the same binary structure.

::: tip
tool stubs default to the HTTP backend if no `tool` field is specified and a `url` field is present.
See the [HTTP backend documentation](/dev-tools/backends/http) for full details on configuring HTTP-based tools.
:::

## Generating Tool Stubs (http)

While you can manually create tool stubs with TOML configuration, mise provides a [`mise generate tool-stub`](/cli/generate/tool-stub) command to automatically create stubs for HTTP-based tools.

::: tip Incremental Building
When using platform-specific URLs, the tool stub generator will append new platforms to existing stub files rather than overwriting them. This allows you to incrementally build cross-platform tool stubs by running the command multiple times with different platforms.
:::

### Basic Generation

Generate a tool stub for a tool distributed via HTTP:

```bash
mise generate tool-stub ./bin/gh --url "https://github.com/cli/cli/releases/download/v2.336.0/gh_2.336.0_linux_amd64.tar.gz"
```

This will:

* Download the archive to detect checksums (for security)
* Extract it to auto-detect the binary path
* Generate an executable stub with complete TOML configuration

### Platform-Specific Generation

For tools with different URLs per platform, you can generate all platforms at once:

```bash
mise generate tool-stub ./bin/rg \
  --platform-url linux-x64:https://github.com/BurntSushi/ripgrep/releases/download/14.0.3/ripgrep-14.0.3-x86_64-unknown-linux-musl.tar.gz \
  --platform-url darwin-arm64:https://github.com/BurntSushi/ripgrep/releases/download/14.0.3/ripgrep-14.0.3-aarch64-apple-darwin.tar.gz
```

**Auto-Platform Detection**: If the URL contains platform information, you can omit the platform prefix and let mise auto-detect it:

```bash
# Auto-detect platform from URL (detects as 'macos-arm64')
mise generate tool-stub ./bin/node \
  --platform-url https://nodejs.org/dist/v22.17.1/node-v22.17.1-darwin-arm64.tar.gz

# Auto-detect platform from URL (detects as 'linux-x64')
mise generate tool-stub ./bin/node \
  --platform-url https://github.com/BurntSushi/ripgrep/releases/download/14.0.3/ripgrep-14.0.3-x86_64-unknown-linux-musl.tar.gz
```

Or build them incrementally by adding platforms one at a time:

```bash
# Start with Linux support (explicit platform)
mise generate tool-stub ./bin/rg \
  --platform-url linux-x64:https://github.com/BurntSushi/ripgrep/releases/download/14.0.3/ripgrep-14.0.3-x86_64-unknown-linux-musl.tar.gz

# Later, add macOS support using auto-detection (appends to existing file)
mise generate tool-stub ./bin/rg \
  --platform-url https://github.com/BurntSushi/ripgrep/releases/download/14.0.3/ripgrep-14.0.3-aarch64-apple-darwin.tar.gz

# Add Windows support using auto-detection (appends to existing file)
mise generate tool-stub ./bin/rg \
  --platform-url https://github.com/BurntSushi/ripgrep/releases/download/14.0.3/ripgrep-14.0.3-x86_64-pc-windows-msvc.zip
```

The generator will preserve existing configuration and merge new platforms into the `[platforms]` table. If you specify a platform that already exists, its URL will be updated.

### Generation Options

* `--version VERSION` - Specify tool version (defaults to "latest").
* `--bin PATH` - Override auto-detected binary path
* `--platform-url PLATFORM:URL` - Add platform-specific URL (can be used multiple times)
* `--platform-url URL` - Add platform-specific URL with auto-detected platform from URL filename
* `--platform-bin PLATFORM:PATH` - Set platform-specific binary path
* `--skip-download` - Skip downloading for faster generation (no checksums or binary detection)
* `--lock` - Resolve and embed lockfile data (pinned version + platform URLs/checksums) into an existing stub

### Supported Archive Formats

The generator automatically detects and extracts various archive formats:

* `.tar.gz` / `.tgz` (gzip compressed tarballs)
* `.tar.xz` / `.txz` (xz compressed tarballs)
* `.tar.bz2` / `.tbz2` (bzip2 compressed tarballs)
* `.tar.zst` / `.tzst` (zstd compressed tarballs)
* `.zip` (zip archives)
* `.7z` (7-zip archives, Windows only)

### Generated Stub Example

Running the generation command produces an executable stub like:

```bash
#!/usr/bin/env -S mise tool-stub

version = "latest"
bin = "bin/gh"
url = "https://github.com/cli/cli/releases/download/v2.336.0/gh_2.336.0_linux_amd64.tar.gz"
checksum = "blake3:a1b2c3d4e5f6..."
size = 12345678
```

The generator automatically:

* Calculates BLAKE3 checksums for integrity verification
* Detects file sizes
* Identifies the correct binary path within archives
* Uses the output filename as the tool name

## Examples

### Basic Node.js Stub

```bash
#!/usr/bin/env -S mise tool-stub
# Node.js v20 tool stub

tool = "node"
version = "20.0.0"
bin = "node"
```

### Python with Custom Binary Name

```bash
#!/usr/bin/env -S mise tool-stub
# Python tool accessible as 'py'

tool = "python"
version = "3.11"
bin = "python"
```

### GitHub Release Backend

```bash
#!/usr/bin/env -S mise tool-stub
# GitHub CLI tool

tool = "github:cli/cli"
version = "latest"
```

### Locked Tool Stub

```bash
#!/usr/bin/env -S mise tool-stub

tool = "node"
version = "20.18.1"
bin = "node"

[lock.platforms.linux-x64]
url = "https://nodejs.org/dist/v20.18.1/node-v20.18.1-linux-x64.tar.xz"
checksum = "sha256:abc123..."

[lock.platforms.macos-arm64]
url = "https://nodejs.org/dist/v20.18.1/node-v20.18.1-darwin-arm64.tar.gz"
checksum = "sha256:def456..."
```

The `[lock]` section is generated by `mise generate tool-stub --lock` and provides
reproducible downloads with checksum verification. The tool/version fields are still
used for backend resolution, while lock data provides the download shortcuts.

::: tip
Locking is especially useful for avoiding GitHub API rate limits when users don't have a `GITHUB_TOKEN` set. With locked stubs, tools can be installed without any API calls at runtime.
:::

#### Locking a Stub

```bash
# Create a stub with a fuzzy version
mise generate tool-stub ./bin/node --version 20

# Lock it to pin the exact version and add platform URLs/checksums
mise generate tool-stub ./bin/node --lock
```

This resolves the version, fetches URLs for all common platforms (linux-x64, linux-arm64, macos-x64, macos-arm64, windows-x64), and writes them into a `[lock]` section in the stub.

#### Bumping a Locked Version

To bump the version of a locked stub, pass `--version` along with `--lock`:

```bash
# Bump to the latest node 22.x and re-lock
mise generate tool-stub ./bin/node --lock --version 22
```

### HTTP Backend with Platform Support

```bash
#!/usr/bin/env -S mise tool-stub
# Custom HTTP tool with platform-specific downloads

version = "1.0.0"

[platforms.linux-x64]
url = "https://releases.example.com/v{{version}}/tool-linux-x64.tar.gz"

[platforms.darwin-arm64]
url = "https://releases.example.com/v{{version}}/tool-macos-arm64.tar.gz"
```

## Usage

### Direct Execution

Make the stub executable and run it directly:

```bash
chmod +x ./bin/my-tool
./bin/my-tool --version
```

### Via mise Command

Execute using the [`mise tool-stub`](/cli/tool-stub) command—useful for testing if something isn't working right:

```bash
mise tool-stub ./bin/my-tool --version
```

## Caching

Tool stubs implement intelligent caching which reduces the overhead mise has when running stubs:

* Binary paths are cached based on stub file path and modification time
* Cache is automatically invalidated when the stub file changes
* Missing binaries trigger cache cleanup automatically

Cached stubs have ~4ms of overhead.

## Alternative: Creating Simple Stubs with `mise x`

For basic use cases, you can quickly create simple tool stubs using the [`mise x`](/cli/exec) command as an alternative to writing TOML configuration manually:

```bash
# Create bin directory
mkdir -p ./bin

# Create a simple Node.js stub
cat > ./bin/node << 'EOF'
#!/usr/bin/env bash
exec mise x node@20 -- "$@"
EOF
chmod +x ./bin/node

# Create a Python stub with specific version
cat > ./bin/python << 'EOF'
#!/usr/bin/env bash
exec mise x python@3.11 -- "$@"
EOF
chmod +x ./bin/python
```

This approach is ideal for simple tool execution without the need for custom options, environment variables, or platform-specific settings. For more complex configurations, use the full TOML configuration format described above.

---

---
url: /troubleshooting.md
---
# Troubleshooting

## `mise activate` doesn't work in `~/.profile`, `~/.bash_profile`, `~/.zprofile`

`mise activate` should only be used in `rc` files. These are the interactive ones used when
a real user is using the terminal. (As opposed to being executed by an IDE or something). The prompt
isn't displayed in non-interactive environments so PATH won't be modified.

For non-interactive setups, consider using shims instead which will route calls to the correct
directory by looking at `PWD` every time they're executed. You can also call `mise exec` instead of
expecting things to be directly on PATH. You can also run `mise env` in a non-interactive shell,
however that
will only setup the global tools. It won't modify the environment variables when entering into a
different project.

::: warning
`mise activate --shims` does not support all the features of `mise activate`.
See [shims vs path](/dev-tools/shims.html#shims-vs-path) for more info.
:::

Also see the [shebang](/tips-and-tricks#shebang) example for a way to make scripts call mise to get
the runtime.
That is another way to use mise without activation.

## mise is failing or not working right

First try setting `MISE_DEBUG=1` or `MISE_TRACE=1` and see if that gives you more information.
You can also set `MISE_LOG_FILE_LEVEL=debug MISE_LOG_FILE=/path/to/logfile` to write logs to a file.

If something is happening with the activate hook, you can try disabling it and
calling `eval "$(mise hook-env)"` manually.
It can also be helpful to use `mise env` which will just output environment variables that would be
set.
Also consider using [shims](/dev-tools/shims.md) which can be more compatible.

If runtime installation isn't working right, try using the `--raw` flag which will install things in
series and connect stdin/stdout/stderr directly to the terminal. If a plugin is trying to interact
with you for some reason this will make it work.

Of course check the version of mise with `mise --version` and make sure it is the latest.
Use `mise self-update`
to update it. `mise cache clean` can be used to wipe the internal cache and `mise implode` can be
used
to remove everything except config.

Lastly, there is `mise doctor` which will show diagnostic information and any warnings about issues
detected with your setup. If you submit a bug report, please include the output of `mise doctor`.

## The wrong version of a tool is being used

Likely this means that mise isn't first in PATH—using shims or `mise activate`. You can verify if
this is the case by calling `which -a`, for example, if node@20.0.0 is being used but mise specifies
node@24.0.0, first make sure that mise has this version installed and active by running `mise ls node`.
It should not say missing and have the correct "Requested" version:

```bash
$ mise ls node
Plugin  Version  Config Source       Requested
node    24.0.0  ~/.mise/config.toml  24.0.0
```

If `node -v` isn't showing the right version, make sure mise is activated by running `mise doctor`.
It should not have a "problem" listed about mise not being activated. Lastly, run `which -a node`.
If the directory listed is not a mise directory, then mise is not first in PATH. Whichever node is
being run first needs to have its directory set before mise is. Typically this means setting PATH for
mise shims at the end of bashrc/zshrc.

If using `mise activate`, you have another option of enabling `MISE_ACTIVATE_AGGRESSIVE=1` which will
have mise always prepend its tools to be first in PATH. If you're using something that also modifies
paths dynamically like `mise activate` does, this may not work because the other tool may be modifying
PATH after mise does.

If nothing else, you can run things with [`mise x --`](/cli/exec) to ensure that the correct version is being used.

## New version of a tool is not available

There are 2 places that versions are cached so a brand new release might not appear right away.

The first is that the mise CLI caches versions for. The cache can be cleared with `mise cache clear`.

The second uses the <https://mise-versions.jdx.dev> host as a centralized
place to list all of the versions of most plugins. This is intended to speed up mise and also
get around GitHub rate limits when querying for new versions. Check that repo for your plugin to
see if it has an updated version. This service can be disabled by
setting `MISE_USE_VERSIONS_HOST=0`.

mise-versions itself also struggles with rate limits but you can help it to fetch more frequently by authenticating
with its [GitHub app](https://github.com/apps/mise-versions). It does not require any permissions since it simply
fetches public repository information. The more people do this, the quicker
mise will be able to fetch new versions of tools.

## Windows problems

::: warning
Very basic support for windows is currently available, however because Windows can't support asdf
plugins, they must use core and vfox only—which means only a handful of tools are available on
Windows.
:::

### Path limits

If you have many tools defined in your `mise.toml` hierarchy, then it is possible that `mise x` will produce a `Path` environment variable that is too long for certain tools to handle, most notably, `cmd.exe`. This will affect `mise` tools that invoke `cmd.exe` (like `npm install`).

You have a few options:

1. Set the `MISE_INSTALLS_DIR` environment variable to a shorter location, e.g. `C:\.mise-installs`.
2. Use `powershell.exe` or `pwsh.exe` instead of `cmd.exe`, since they can handle a longer `Path`.
3. Re-organise the `mise.toml` files in your monorepo, to specify only the tools they need.

You can run the following command to test whether you have hit the `cmd.exe` `Path` limitation:

```powershell
# Path is within limits
❯ mise x -- cmd.exe /d /s /c "where.exe where"
C:\Windows\System32\where.exe
# Path exceeds cmd.exe limits
❯ mise x -- cmd.exe /d /s /c "where.exe where"
'where.exe' is not recognized as an internal or external command,
operable program or batch file.
mise ERROR command failed: exit code 1
mise ERROR Run with --verbose or MISE_VERBOSE=1 for more information
```

## mise isn't working when calling from tmux or another shell initialization script

`mise activate` will not update PATH until the shell prompt is displayed. So if you need to access a
tool provided by mise before the prompt is displayed you can either
[add the shims to your PATH](/dev-tools/shims.html#how-to-add-mise-shims-to-path) e.g.

```bash
export PATH="$HOME/.local/share/mise/shims:$PATH"
python --version # will work after adding shims to PATH
```

Or you can manually call `hook-env`:

```bash
eval "$(mise activate bash)"
eval "$(mise hook-env)"
python --version # will work only after calling hook-env explicitly
```

For more information, see [What does `mise activate` do?](/faq#what-does-mise-activate-do)

## Is mise secure?

Providing a secure supply chain is incredibly important. mise already provides a more secure
experience when compared to asdf. Security-oriented evaluations and contributions are welcome.
We also urge users to look after the plugins they use, and urge plugin authors to look after
the users they serve.

For more details see [SECURITY.md](https://github.com/jdx/mise/blob/main/SECURITY.md).

## 403 Forbidden when installing a tool

You may get an error like one of the following:

```text
HTTP status client error (403 Forbidden) for url
403 API rate limit exceeded for
```

This can happen if the tool is hosted on GitHub, and you've hit the API rate limit. This is especially
common running mise in a CI environment like GitHub Actions. If you don't have a `GITHUB_TOKEN`
set, the rate limit is quite low. You can fix this by creating a GitHub token (which needs no scopes)
by going to [https://github.com/settings/tokens/new](https://github.com/settings/tokens/new?description=MISE_GITHUB_TOKEN) and setting it as an environment variable. You can
use any of the following (in order of preference):

* `MISE_GITHUB_TOKEN`
* `GITHUB_TOKEN`
* `GITHUB_API_TOKEN`

## Auto-install on command not found handler does not work for new tools

If you are expecting mise to automatically install a tool when you run a command that is not found (using the [`not_found_auto_install`](/configuration/settings.html#not_found_auto_install) feature), be aware of an important limitation:

**mise can only auto-install missing versions of tools that already have at least one version installed.**

This is because mise does not have a way of knowing which binaries a tool provides unless there is already an installed (even inactive) version of that tool. If you have never installed any version of a tool, mise cannot determine which tool is responsible for a given binary name, and so it cannot auto-install it on demand.

**Workarounds:**

* Manually install at least one version of the tool you want to be auto-installed in the future. After that, the auto-install feature will work for missing versions of that tool.
* Use [`mise x|exec`](/cli/exec) or [`mise r|run`](/cli/run) to trigger auto-install for missing tools, even if no version is currently installed. These commands will attempt to install the required tool versions automatically.

---

---
url: /dev-tools/backends/ubi.md
---
# Ubi Backend

::: warning
The ubi backend is **deprecated**. Please use the [github backend](/dev-tools/backends/github) instead.

To migrate, replace `ubi:owner/repo` with `github:owner/repo` in your configuration files.
:::

You may install GitHub Releases and URL packages directly using [ubi](https://github.com/houseabsolute/ubi) backend. ubi is directly compiled into
the mise codebase so it does not need to be installed separately to be used.

ubi doesn't require plugins or even any configuration for each tool. What it does is try to deduce what
the proper binary/tarball is from GitHub releases and downloads the right one. As long as the vendor
uses a somewhat standard labeling scheme for their releases, ubi should be able to figure it out.

The code for this is inside of the mise repository at [`./src/backend/ubi.rs`](https://github.com/jdx/mise/blob/main/src/backend/ubi.rs).

## Usage

The following installs the latest version of goreleaser
and sets it as the active version on PATH:

```sh
$ mise use -g ubi:goreleaser/goreleaser
$ goreleaser --version
1.25.1
```

The version will be set in `~/.config/mise/config.toml` with the following format:

```toml
[tools]
"ubi:goreleaser/goreleaser" = "latest"
```

## Tool Options

The following [tool-options](/dev-tools/#tool-options) are available for the `ubi` backend—these
go in `[tools]` in `mise.toml`.

### `exe`

The `exe` option allows you to specify the executable name in the archive. This is useful when the
archive contains multiple executables.

If you get an error like `could not find any files named cli in the downloaded zip file`, you can
use the `exe` option to specify the executable name:

```toml
[tools]
"ubi:cli/cli" = { version = "latest", exe = "gh" } # github's cli
```

### `rename_exe`

The `rename_exe` option allows you to specify the name of the executable once it has been extracted.

use the `rename_exe` option to specify the target executable name:

```toml
[tools]
"ubi:cli/cli" = { version = "latest", exe = "gh", rename_exe = "github" } # github's cli
```

### `matching`

Set a string to match against the release filename when there are multiple files for your
OS/arch, i.e. "gnu", "musl", or "msvc". Note that this is only used when there is more than one
matching release filename for your OS/arch. If only one release asset matches your OS/arch,
then this will be ignored.

```toml
[tools]
"ubi:BurntSushi/ripgrep" = { version = "latest", matching = "musl" }
```

### `matching_regex`

Set a regular expression string that will be matched against release filenames before matching
against OS/arch. If the pattern yields a single match, that release will be selected. If no matches
are found, this will result in an error.

```toml
[tools]
"ubi:shader-slang/slang" = { version = "latest", matching_regex = "\\d+\\.tar" }
```

### `provider`

Set the provider type to use for fetching assets and release information. Either `github` or `gitlab` (default is `github`).
Ensure the `provider` is set to the correct type if you use `api_url` as the type probably cannot be derived correctly
from the URL.

```toml
[tools]
"ubi:gitlab-org/cli" = { version = "latest", exe = "glab", provider = "gitlab" }
```

### `api_url`

Set the URL for the provider's API. This is useful when using a self-hosted instance.

```toml
[tools]
"ubi:acme/my-tool" = {
  version = "latest",
  provider = "gitlab",
  api_url = "https://gitlab.acme.com/api/v4",
}
```

### `extract_all`

Set to `true` to extract all files in the tarball instead of just the "bin". Not compatible with `exe` nor `rename_exe`.

```toml
[tools]
"ubi:helix-editor/helix" = { version = "latest", extract_all = "true" }
```

### `bin_path`

The directory in the tarball where the binary(s) are located. This is useful when the binary is not in the root of the tarball.
This only makes sense when `extract_all` is set to `true`.

```toml
[tools]
"ubi:BurntSushi/ripgrep" = {
  version = "latest",
  extract_all = "true",
  bin_path = "target/release",
}
```

**Binary path lookup order:**

1. If `bin_path` is specified, use that directory
2. If `extract_all` is set to `true`, use the install path root
3. If `bin_path` is not set, look for a `bin/` directory in the install path
4. If no `bin/` directory exists, use the root of the extracted directory

### `tag_regex`

Set a regex to filter out tags that don't match the regex. This is useful when a vendor has a bunch of
releases for unrelated CLIs in the same repo. For example, `cargo-bins/cargo-binstall` has a bunch of
releases for unrelated CLIs that are not `cargo-binstall`. This option can be used to filter out those
releases.

```toml
[tools]
"ubi:cargo-bins/cargo-binstall" = { version = "latest", tag_regex = '^\d+\.' }
```

## Self-hosted GitHub/GitLab

If you are using a self-hosted GitHub/GitLab instance, you can set the `provider` and `api_url` tool options.
Additionally, you can set the `MISE_GITHUB_ENTERPRISE_TOKEN` or `MISE_GITLAB_ENTERPRISE_TOKEN` environment variable to
authenticate with the API.

## Supported Ubi Syntax

* **GitHub shorthand for latest release version:** `ubi:goreleaser/goreleaser`
* **GitHub shorthand for specific release version:** `ubi:goreleaser/goreleaser@1.25.1`
* **URL syntax:** `ubi:https://github.com/goreleaser/goreleaser/releases/download/v1.16.2/goreleaser_Darwin_arm64.tar.gz`

## Troubleshooting ubi

### `ubi` resolver can't find os/arch

Sometimes vendors use strange formats for their releases that ubi can't figure out, possibly for a
specific os/arch combination. For example this recently happened in [this ticket](https://github.com/houseabsolute/ubi/issues/79) because a vendor used
"mac" instead of the more common "macos" or "darwin" tags.

Try using ubi by itself to see if the issue is related to mise or ubi:

```sh
ubi -p jdx/mise
./bin/mise -v # yes this technically means you could do `mise use ubi:jdx/mise` though I don't know why you would
```

### `ubi` picks the wrong tarball

Another issue is that a GitHub release may have a bunch of tarballs, some that don't contain the CLI
you want, you can use the `matching` field in order to specify a string to match against the release.

```sh
mise use ubi:tamasfe/taplo[matching=full]
# or with ubi directly
ubi -p tamasfe/taplo -m full
```

### `ubi` can't find the binary in the tarball

ubi assumes that the repo name is the same as the binary name, however that is often not the case.
For example, BurntSushi/ripgrep gives us a binary named `rg` not `ripgrep`. In this case, you can
specify the binary name with the `exe` field:

```sh
mise use ubi:BurntSushi/ripgrep[exe=rg]
# or with ubi directly
ubi -p BurntSushi/ripgrep -e rg
```

### `ubi` uses weird versions

This issue is actually with mise and not with ubi. mise needs to be able to list the available versions
of the tools so that "latest" points to whatever is the actual latest release of the CLI. What sometimes
happens is vendors will have GitHub releases for unrelated things. For example, `cargo-bins/cargo-binstall`
is the repo for cargo-binstall, however it has a bunch of releases for unrelated CLIs that are not
cargo-binstall. We need to filter these out and that can be specified with the `tag_regex` tool option:

```sh
mise use 'ubi:cargo-bins/cargo-binstall[tag_regex=^\d+\.]'
```

Now when running `mise ls-remote ubi:cargo-bins/cargo-binstall[tag_regex=^\d+\.]` you should only see
versions starting with a number. Note that this command is cached so you likely will need to run `mise cache clear` first.

---

---
url: /url-replacements.md
---
# URL Replacements

mise does not include a built-in registry for downloading artifacts.
Instead, it retrieves remote registry manifests, which specify the URLs for downloading tools.

In some environments — such as enterprises or DMZs — these URLs may not be directly accessible and must be accessed through a proxy or internal mirror.

URL replacements allow you to modify or redirect any URL that mise attempts to access, making it possible to use internal proxies, mirrors, or alternative sources as needed.

## Configuration Examples

In mise.toml (single line):

```toml
[settings]
url_replacements = { "example.com" = "mirror.example.com" }
```

In mise.toml (multiline):

```toml
[settings.url_replacements]
"example.com" = "mirror.example.com"
"releases.hashicorp.com" = "hashicorp.example.com"
```

RegEx example:

```toml
[settings.url_replacements]
"regex:^http://(.+)" = "https://$1"
"regex:^https://github\\.com/([^/]+)/([^/]+)/releases/download/(.+)" = "https://hub.example.com/artifactory/github/$1/$2/$3"
```

## Simple Hostname Replacement

For simple hostname-based mirroring, the key is the original hostname/domain to replace,
and the value is the replacement string. The replacement happens by searching and replacing
the pattern anywhere in the full URL string (including protocol, hostname, path, and query parameters).

Examples:

* `github.com` -> `mirror.example.com` replaces GitHub hostnames
* `https://github.com` -> `https://mirror.example.com` with protocol excludes e.g. 'api.github.com'
* `https://github.com` -> `https://proxy.example.com/github-mirror` replaces GitHub with corporate proxy
* `http://example.net` -> `https://example.net` replaces protocol from HTTP to HTTPS

See [Security Considerations](#security-considerations) for important warnings about credential handling.

## Advanced Regex Replacement

For more complex URL transformations, you can use regex patterns. When a key starts with `regex:`,
it is treated as a regular expression pattern that can match and transform any part of the URL.
The value can use capture groups from the regex pattern.

### Regex Examples

#### 1. Protocol Conversion (HTTP to HTTPS)

```toml
[settings]
url_replacements = {
  "regex:^http://(.+)" = "https://$1"
}
```

This converts any HTTP URL to HTTPS by capturing everything after "http://" and replacing it with "https://".

#### 2. GitHub Release Mirroring with Path Restructuring

```toml
[settings]
url_replacements = {
  "regex:^https://github\\.com/([^/]+)/([^/]+)/releases/download/(.+)" =
    "https://hub.example.com/artifactory/github/$1/$2/$3"
}
```

Transforms `https://github.com/owner/repo/releases/download/v1.0.0/file.tar.gz`
to `https://hub.example.com/artifactory/github/owner/repo/v1.0.0/file.tar.gz`

#### 3. Subdomain to Path Conversion

```toml
[settings]
url_replacements = {
  "regex:^https://([^.]+)\\.cdn\\.example\\.com/(.+)" =
    "https://unified-cdn.example.com/$1/$2"
}
```

Converts subdomain-based URLs to path-based URLs on a unified CDN.

#### 4. Multiple Replacement Patterns (processed in order)

```toml
[settings]
url_replacements = {
  "regex:^https://github\\.com/microsoft/(.+)" =
    "https://internal.example.org/microsoft/$1",
  "regex:^https://github\\.com/(.+)" =
    "https://public.example.org/github/$1",
  "releases.hashicorp.com" = "hashicorp.example.net"
}
```

First regex catches Microsoft repositories specifically, second catches all other GitHub URLs,
and the simple replacement handles HashiCorp.

## Use Cases

1. **Corporate Mirrors**: Replace public download URLs with internal corporate mirrors
2. **Custom Registries**: Redirect package downloads to custom or private registries
3. **Geographic Optimization**: Route downloads to geographically closer mirrors
4. **Protocol Changes**: Convert HTTP URLs to HTTPS or vice versa

## Regex Syntax

mise uses Rust regex engine which supports:

* `^` and `$` for anchors (start/end of string)
* `(.+)` for capture groups (use `$1`, `$2`, etc. in replacement)
* `[^/]+` for character classes (matches any character except `/`)
* `\\.` for escaping special characters (note: double backslash required in TOML)
* `*`, `+`, `?` for quantifiers
* `|` for alternation

You can check on regex101.com if your regex works (see [example](https://regex101.com/r/rmcIE1/1)).
Full regex syntax documentation: <https://docs.rs/regex/latest/regex/#syntax>

## Precedence and Matching

* URL replacements are processed in the order they appear in the configuration (IndexMap insertion order)
* Both regex patterns (keys starting with `regex:`) and simple string replacements are processed in this same order
* The first matching pattern is used; subsequent patterns are ignored for that URL
* If no patterns match, the original URL is used unchanged

## Security Considerations

When using regex patterns, ensure your replacement URLs point to trusted sources,
as this feature can redirect tool downloads to arbitrary locations.

> \[!WARNING]
> **Credential Leaking**: When using `url_replacements`, any authentication headers (like `Authorization: Bearer <TOKEN>`) generated for the original URL (e.g., `api.github.com`) are **preserved** and sent to the replaced URL.
>
> This is by design to allow authentication with internal proxies that forward requests to upstream services (GitHub, GitLab, Forgejo, etc.). However, it means you must **only** replace URLs with trusted servers. Redirecting to an untrusted server will leak your credentials to that server.
>
> **Best Practice**: Use the `^` anchor in your regex patterns to ensure you are matching the start of the URL.
>
> **Bad**: `"regex:github\\.com"` (matches `evil-github.com`)
> **Good**: `"regex:^https://github\\.com"` (only matches actual GitHub URLs)

## Authentication

URL replacements can be used with `~/.netrc` (or `~/_netrc` on Windows) to authenticate with the replaced URL.
Replacements are applied *before* the netrc lookup, so you should use the hostname of the *replaced* URL in your netrc file.

For example, if you have this in `mise.toml`:

```toml
[settings]
url_replacements = { "regex:^https://github\\.com" = "https://nexus.example.com" }
```

> \[!NOTE]
> Credentials from `.netrc` take precedence over and will **overwrite** any default authentication headers (such as those from `MISE_GITHUB_TOKEN` or other environment variables).

You should have this in `~/.netrc`:

```netrc
machine nexus.example.com
  login myusername
  password mypassword
```

---

---
url: /plugin-usage.md
---
# Using Plugins

mise supports plugins that extend its functionality, allowing you to install tools that aren't available in the standard registry. This is particularly useful for:

* Installing tools from private repositories
* Using experimental or niche tools
* Creating custom tool installations for your team

## What Are Plugins?

Plugins are extensions that can install and manage tools not included in mise's built-in registry. They are written in Lua and come in two main types:

### Backend Plugins

Backend plugins use enhanced backend methods and support the `plugin:tool` format:

* **Multiple Tools**: A single plugin can manage multiple tools
* **Enhanced Methods**: Backend methods for listing, installing, and environment setup
* **Format**: Use the `plugin:tool` format (e.g., `vfox-npm:prettier`)

### Tool Plugins

Tool plugins use the traditional hook-based approach:

* **Single Tool**: Each plugin manages one tool
* **Hook-based**: Use hooks like `PreInstall`, `PostInstall`, `Available`, etc.
* **Format**: Use the tool name directly (e.g., `my-tool`)

Both types:

* Install tools from any source (npm packages, GitHub releases, custom builds)
* Set up environment variables and PATH entries
* Handle version management and listing
* Work across all platforms (Windows, macOS, Linux)

## Installing Plugins

### From a Git Repository

```bash
# Install a plugin from a repository
mise plugin install <plugin-name> <repository-url>

# Example: Installing the vfox-npm plugin
mise plugin install vfox-npm https://github.com/jdx/vfox-npm
```

### From Zip File

```bash
# Install a plugin from a zip file over HTTPS
mise plugin install <plugin-name> <zip-url>

# Example: Installing a plugin from a zip file
mise plugin install tiny https://github.com/mise-plugins/mise-tiny.git
```

### From Local Directory

```bash
# Link a local plugin for development
mise plugin link <plugin-name> /path/to/plugin/directory
```

## Using Plugins (Advanced)

Once a plugin is installed, you can use it with the `plugin:tool` format:

```bash
# Install a specific tool using the plugin
mise install vfox-npm:prettier@latest

# Use the tool
mise use vfox-npm:prettier@3.0.0

# Execute the tool
mise exec vfox-npm:prettier -- --version

# List available versions
mise ls-remote vfox-npm:prettier
```

## Plugin:Tool Format

The `plugin:tool` format allows a single plugin to manage multiple tools. This is particularly useful for:

* **Package managers**: Install different npm packages, Python packages, etc.
* **Tool families**: Manage related tools from the same ecosystem
* **Custom builds**: Install different variants of the same tool

### Example: npm packages

```bash
# Install different npm packages using the same plugin
mise install vfox-npm:prettier@latest
mise install vfox-npm:eslint@8.0.0
mise install vfox-npm:typescript@latest

# Use them in your project
mise use vfox-npm:prettier@latest vfox-npm:eslint@8.0.0
```

## Managing Plugins

### List installed plugins

```bash
# Show all plugins
mise plugins ls

# Show plugin URLs
mise plugins ls --urls
```

### Update plugins

```bash
# Update a specific plugin
mise plugin update vfox-npm

# Update all plugins
mise plugin update --all
```

### Remove plugins

```bash
# Remove a plugin
mise plugin remove vfox-npm

# This will also remove all tools installed by the plugin
```

## Configuration

Plugins can be configured in your `mise.toml` file:

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

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

## Finding Plugins

While mise doesn't have a centralized registry for community plugins, you can find them:

* **GitHub**: Search for repositories with "vfox-" prefix
* **Community**: Check mise community discussions and Discord
* **Company internal**: Your organization may have private plugins

## Plugin Examples

### vfox-npm (Example Plugin)

The `vfox-npm` plugin demonstrates how to create a plugin that installs npm packages:

```bash
# Install the plugin
mise plugin install vfox-npm https://github.com/jdx/vfox-npm

# Install tools
mise install vfox-npm:prettier@latest
mise install vfox-npm:eslint@latest

# Use them
mise use vfox-npm:prettier@latest
mise exec vfox-npm:prettier -- --check .
```

::: info
This is just an example plugin for testing. mise already has built-in npm support that you should use instead: `mise install npm:prettier@latest`
:::

## Backend Plugins (Advanced)

Backend plugins use enhanced backend methods that provide better performance and support for the `plugin:tool` format:

* **BackendListVersions**: Lists available versions of a tool
* **BackendInstall**: Installs a specific version
* **BackendExecEnv**: Sets up environment variables

This architecture allows plugins to manage multiple tools efficiently while providing a consistent interface.

## Tool Plugins (Advanced)

Tool plugins use the traditional hook-based approach:

* **Available**: Lists available versions
* **PreInstall/PostInstall**: Installation hooks
* **EnvKeys**: Environment variable setup
* **Parse**: Version parsing and validation

Both architectures provide a flexible plugin system that can handle diverse installation and management needs.

## Security Considerations

::: danger
When using plugins, be aware that:

* **Plugins execute arbitrary code** during installation and use
* **Only install plugins from trusted sources**
* **Review plugin code** before installation when possible
* **Use version pinning** to avoid unexpected updates like [`mise.lock`](/dev-tools/mise-lock.md)
  :::

## Troubleshooting

### Plugin installation fails

```bash
# Check if the repository URL is correct
mise plugin install vfox-npm https://github.com/jdx/vfox-npm

# Check plugin directory
ls ~/.local/share/mise/plugins/
```

### Tool installation fails

```bash
# Check plugin logs
mise install vfox-npm:prettier@latest --verbose

# Verify plugin is installed
mise plugins ls
```

### Environment issues

```bash
# Check if PATH is set correctly
mise exec vfox-npm:prettier env | grep PATH

# Verify tool is installed
ls ~/.local/share/mise/installs/vfox-npm/prettier/
```

## Next Steps

* [Learn how to create backend plugins](backend-plugin-development.md)
* [Learn how to create tool plugins](tool-plugin-development.md)
* [Explore built-in backends](dev-tools/backends/)
* [Check the community registry](registry.md)

---

---
url: /dev-tools/backends/vfox.md
---
# Vfox Backend

::: tip
Vfox is the recommended plugin system for mise. It provides cross-platform support, built-in modules, and a modern hook-based architecture.
:::

[Vfox](https://github.com/version-fox/vfox) plugins may be used in mise to install tools.

## Why vfox?

* **Cross-platform** — plugins work on Windows, macOS, and Linux without platform-specific code
* **Built-in modules** — HTTP, JSON, HTML parsing, archive extraction, semver comparison, and logging are all available out of the box, no external dependencies needed
* **Security** — supports attestation verification (cosign signatures, SLSA provenance) for downloaded artifacts
* **Modern architecture** — structured hooks with typed contexts, backend plugins for multi-tool management, rolling version checksums, and lock file support

The code for this is inside the mise repository at [`./src/backend/vfox.rs`](https://github.com/jdx/mise/blob/main/src/backend/vfox.rs).

## Dependencies

No dependencies are required for vfox. Vfox lua code is read via a lua interpreter built into mise.

## Usage

The following installs the latest version of cmake and sets it as the active version on PATH:

```sh
$ mise use -g vfox:version-fox/vfox-cmake
$ cmake --version
cmake version 3.21.3
```

The version will be set in `~/.config/mise/config.toml` with the following format:

```toml
[tools]
"vfox:version-fox/vfox-cmake" = "latest"
```

## Default plugin backend

On Windows, mise uses vfox plugins by default.
If you'd like to use plugins by default even on Linux/macOS, set the following settings:

```sh
mise settings add disable_backends asdf
```

Now you can list available plugins with `mise registry`:

```sh
$ mise registry | grep vfox:
clang                         vfox:mise-plugins/vfox-clang
cmake                         vfox:mise-plugins/vfox-cmake
crystal                       vfox:mise-plugins/vfox-crystal
dart                          vfox:mise-plugins/vfox-dart
dotnet                        vfox:mise-plugins/vfox-dotnet
etcd                          aqua:etcd-io/etcd vfox:mise-plugins/vfox-etcd
flutter                       vfox:mise-plugins/vfox-flutter
gradle                        aqua:gradle/gradle vfox:mise-plugins/vfox-gradle
groovy                        vfox:mise-plugins/vfox-groovy
kotlin                        vfox:mise-plugins/vfox-kotlin
maven                         aqua:apache/maven vfox:mise-plugins/vfox-maven
php                           vfox:mise-plugins/vfox-php
scala                         vfox:mise-plugins/vfox-scala
terraform                     aqua:hashicorp/terraform vfox:mise-plugins/vfox-terraform
vlang                         vfox:mise-plugins/vfox-vlang
```

And they will be installed when running commands such as `mise use -g cmake` without needing to
specify `vfox:cmake`.

## Plugins

In addition to the standard vfox plugins, mise supports modern plugins that can manage multiple tools using the `plugin:tool` format. These plugins are perfect for:

* Installing tools from private repositories
* Package managers (npm, pip, etc.)
* Custom tool families

### Example: Plugin Usage

```bash
# Install a plugin
mise plugin install my-plugin https://github.com/username/my-plugin

# Use the plugin:tool format
mise install my-plugin:some-tool@1.0.0
mise use my-plugin:some-tool@latest
```

### Install from Zip File

```bash
# Install a plugin from a zip file over HTTPS
mise plugin install <plugin-name> <zip-url>
# Example: Installing a plugin from a zip file
mise plugin install vfox-cmake https://github.com/mise-plugins/vfox-cmake/archive/refs/heads/main.zip
```

For more information, see:

* [Using Plugins](../../plugin-usage.md) - End-user guide
* [Plugin Development](../../tool-plugin-development.md) - Developer guide
* [Plugin Template](https://github.com/jdx/mise-tool-plugin-template) - Quick start template for creating plugins

---

---
url: /walkthrough.md
---
# Walkthrough

Once you've completed the [Getting Started](/getting-started) guide, you're ready to start using mise.
This document offers a quick overview on some initial things you may want to try out.

## Installing Dev Tools

The main command for working with tools in mise is [`mise u|use`](/cli/use). This does 2 main things:

* Installs tools (if not already installed)
* Adds the tool to the `mise.toml` configuration file—in mise I say the tool is "active" if it's in `mise.toml`

:::warning
Both of these are required to use a tool. If you simply install a tool via `mise install`, it won't be available in your shell.
It must also be added to `mise.toml`—which is why I promote using `mise use` since it does both.
:::

You use it like so (note that `mise` must be [activated](/getting-started.html#activate-mise) for this example to work):

```bash
mkdir example-project && cd example-project
mise use node@24
node -v
# v24.x.x
```

And you'll also note that you now have a `mise.toml` file with the following content:

```mise-toml [mise.toml]
[tools]
node = "24"
```

* If this file is in the root of a project, `node` will be installed whenever someone runs [`mise install|i`](/cli/install).
* This is the command you want to run when you first clone a project or when you want to update installed tools.

## `mise.toml` Configuration

You can create a `mise.toml` file manually or with the CLI.

> \[!TIP]
> Use `mise edit` to open an interactive editor for your configuration. It provides a TUI where you can navigate sections, add tools from the registry with fuzzy search, and configure settings with schema-aware autocompletion.

Use [`mise.toml`](/configuration#mise-toml) to share your tool configurations with others. This file should be committed to version control and contains the common toolset needed for your project.

For tools or settings you want to keep private, use [`mise.local.toml`](/configuration#mise-toml). This file should be added to `.gitignore` and is perfect for personal preferences or configurations.

`mise` supports nested configuration files that cascade from broad to specific settings:

1. `~/.config/mise/config.toml` - Global settings for all projects
2. `~/work/mise.toml` - Work-specific settings
3. `~/work/project/mise.toml` - Project-specific settings
4. `~/work/project/mise.local.toml` - Project-specific settings that should not be shared

`mise` will use all the parent directories together to determine the set of tools—overriding configuration as it goes lower in the hierarchy.

:::tip
Use [`mise config ls`](/cli/config/ls) to see the configuration files currently used by `mise`.
:::

In general, it's preferred to use loose versions like this in `mise` so that other people working
on a project don't have to worry about the exact version of a tool you're using. If you'd like to
pin the version to enforce a specific version, use `mise use --pin` or the [`lockfile`](/configuration/settings#lockfile) setting.

If you leave out the version, then mise will default to `node@latest`.

## Dev Tool Backends

Tools are installed with a variety of backends like `asdf`, `github`, or `vfox`. See [registry](/registry.html) for
the full list of shorthands like `node` you can use.

You can also use other backends like `npm` or `cargo`
which can install any package from their respective registries:

```bash
mise use npm:@antfu/ni
mise use cargo:starship
```

## Upgrading Dev Tools

Upgrading tool versions can be done with [`mise up|upgrade`](/cli/upgrade). By default, it will respect
the version prefix in `mise.toml`. If a [lockfile](/configuration/settings#lockfile) exists,
mise will update `mise.lock` to the latest version of the tool with the prefix from `mise.toml`.

So if you have `node = "24"` in `mise.toml`, then `mise upgrade node` will upgrade to the latest version of `node 24`.

If you'd like to upgrade to the latest version of node, you can use `mise upgrade --bump node`. It will set the version
at the same specificity as the current version, so if you have `node = "24"`, but use `mise upgrade --bump node` to update to
`node@26`, then it will set `node = "26"` in `mise.toml`.

*See [Dev Tools](/dev-tools/) for more information on working with tools.*

## Setting Environment Variables

mise can also be used to set environment variables for your project. You can set environment variables
with the CLI:

```bash
mise set MY_VAR=123
echo $MY_VAR
# 123
```

Or by directly modifying `mise.toml`:

```toml
[env]
MY_VAR = "123"
```

Some examples on where this can be used:

* Setting `NODE_ENV` for a Node.js project
* Setting `DATABASE_URL` for a database connection
* Setting `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` for AWS
* Setting `RUST_TEST_THREADS=1` to run cargo tests in series

You can also modify `PATH` with `mise.toml`.
This example makes CLIs installed with `npm` available:

```toml
[env]
_.path = "./node_modules/.bin"
```

This will add `./node_modules/.bin` to the PATH for the project—with "." here referring to the directory
the `mise.toml` file is in so if you enter a subdirectory, it will still work.

*See [Environments](/environments/) for more information on working with environment variables.*

## Tasks

Tasks are defined in a project to execute commands.

You can define tasks in a `mise.toml`:

```mise-toml [mise.toml]
[tasks]
build = "npm run build"
test = "npm test"
```

Or in a `mise-tasks` directory as a standalone file, such as `mise-tasks/build`:

```bash [mise-tasks/build]
#!/bin/bash
npm run build
```

Tasks are executed with [`mise r|run`](/cli/run):

```bash
mise run build
mise run test
```

:::tip
`mise run` sets up the "mise environment" before running the task (tools and environment variables).
So if you'd rather not activate mise in your shell, you can use `mise run` to run tasks, and it will
have the tools in PATH and the environment variables from `mise.toml` set.
:::

`mise` is paired with [usage](https://usage.jdx.dev) which provides lots of features for documenting and running tasks.

Here is an example of a task with usage spec:

```bash [mise-tasks/greet]
#!/usr/bin/env bash
set -e

#MISE description="Greet a user with a message"
#USAGE flag "-g --greeting <greeting>" help="The greeting word to use" {
#USAGE   choices "hi" "hello" "hey"
#USAGE }
#USAGE flag "-u --user <user>" help="The user to greet"
#USAGE flag "--dir <dir>" help="The directory to greet from" default="."
#USAGE complete "dir" run="find . -maxdepth 1 -type d"
#USAGE arg "<message>" help="Greeting message"

echo "all available options are in the env with the prefix 'usage_'"
env | grep usage_

echo "${usage_greeting?}, ${usage_user?}! Your message is: ${usage_message?}"
```

This task can be run like so:

```shell
mise run greet --user jdx -g "hey" "How are you?"
```

* The options will all be passed as environment variables prefixed with `usage_` like `usage_user`.
* Help is available with `mise run greet --help` and will show the options defined in the task.
* Completions are available like you'd expect, so typing `mise run greet --greeting <tag>` will show `hi`, `hello`, and `hey`
  as options.
* [Custom completion](https://usage.jdx.dev/spec/reference/complete) can be provided by a CLI. `mise run greet --dir <tab>` will execute `find . -maxdepth 1 -type d` to provide completions.

To get the autocompletion working, set up [mise autocompletions](/installing-mise.html#autocompletion).

*See [Tasks](/tasks/) for more information on working with tasks.*

## Common Commands

Since there are a lot of commands available in mise, here are what I consider the most important:

* [`mise completion`](/cli/completion) – Set up completions for your shell.
* [`mise cfg|config`](/cli/config) – A bunch of commands for working with `mise.toml` files via the CLI.
* [`mise x|exec`](/cli/exec) – Execute a command in the mise environment without activating mise.
* [`mise g|generate`](/cli/generate) – Generates things like git hooks, task documentation, GitHub actions, and more for your project.
* [`mise i|install`](/cli/install) – Install tools.
* [`mise link`](/cli/link) – Symlink a tool installed by some other means into the mise.
* [`mise ls-remote`](/cli/ls-remote) – List all available versions of a tool.
* [`mise ls`](/cli/ls) – Lists information about installed/active tools.
* [`mise outdated`](/cli/outdated) – Informs you of any tools with newer versions available.
* [`mise plugin`](/cli/plugins) – Plugins can extend mise with new functionality like extra tools or environment variable management. Commonly, these are simply asdf plugins or modern plugins.
* [`mise r|run`](/cli/run) – Run a task defined in `mise.toml` or `mise-tasks`.
* [`mise self-update`](/cli/self-update) – Update mise to the latest version. Don't use this if you installed mise via a package manager.
* [`mise settings`](/cli/settings) – CLI access to get/set configuration settings.
* [`mise rm|uninstall`](/cli/uninstall) – Uninstall a tool.
* [`mise up|upgrade`](/cli/upgrade) – Upgrade tool versions.
* [`mise u|use`](/cli/use) – Install and activate tools.
* [`mise w|watch`](/cli/watch) – Watch for changes in a project and run tasks when they occur.

## Final Thoughts

Dev tools, env vars, and tasks work together to make managing your development environment easier—especially
when working with others. The goal is to have a consistent UX to interface with projects regardless of the
programming languages or tools used on it.

For further reading:

* [Dev Tools](/dev-tools/) – A deeper overview of working with dev tools
* [Environments](/environments/) – A deeper overview of working with environment variables
* [Tasks](/tasks/) – A deeper overview of working with tasks
* [Configuration](/configuration) – More information on `mise.toml` files
* [Settings](/configuration/settings) – All the configuration settings available in mise
* [Backends](/dev-tools/backends/) – An index of all the backends available in mise
* [Registry](/registry) – Every "shorthand" available for tools in mise like `node`, `terraform`, or `watchexec` which point to `core:node`, `asdf:asdf-community/asdf-hashicorp`, and `aqua:watchexec/watchexec` respectively
* [CLI](/cli/) – The full list of commands available in mise

---

---
url: /lang/zig.md
---
# Zig

`mise` can be used to install and manage multiple versions of [zig](https://ziglang.org/) on the same system.

> The following are instructions for using the zig mise core plugin.

The code for this is inside the mise repository at
[`./src/plugins/core/zig.rs`](https://github.com/jdx/mise/blob/main/src/plugins/core/zig.rs).

## Usage

The following installs zig and makes it the global default:

```sh
mise use -g zig@0.14           # install zig 0.14.x
mise use -g zig@latest         # install latest zig release
mise use -g zig@master         # install latest nightly from master
mise use -g zig@2024.11.0-mach # install Mach nominated zig
mise use -g zig@mach-latest    # install latest Mach nominated zig
```

See available stable versions with `mise ls-remote zig`.

Note that [Mach](https://machengine.org/) versions
won't show in `mise ls-remote zig` due to workaround for
[version ordering bug](https://github.com/jdx/mise/discussions/5232).
Despite of that, you still can install Mach versions listed in
[Mach version index](https://machengine.org/zig/index.json). The following
command will list available Mach versions:

```sh
curl https://machengine.org/zig/index.json | yq 'keys'
```

## zig Language Server

The `zig` language server ([zls](https://github.com/zigtools/zls)) needs to be installed separately.
You can install it with `mise`:

```sh
mise use -g zls@0.14   # install zls 0.14.x
mise use -g zls@latest # install latest zls release
```

Note that a tagged release of `zig` should be used with
the same tagged release of `zls`. Currently there is no Mach version of `zls`.

## Settings