Mise
Overview
Mise is a polyglot development tool manager that handles tool versions, environment variables, and task running in a single CLI. It replaces asdf, nvm, pyenv, direnv, and Makefiles with a unified mise.toml configuration per project.
When to use: Managing multiple language runtimes per project, defining reproducible dev environments, running project tasks with dependencies, replacing scattered .nvmrc/.python-version/.tool-versions files, automating CI pipelines.
When NOT to use: Container-only workflows where all tools live in Docker images, single-language projects already well-served by their native version manager, production runtime management (mise is a dev tool).
Version Resolution Order
Mise resolves tool versions by checking these sources in priority order:
MISE_<TOOL>_VERSION environment variablemise.toml in current directorymise.toml in parent directories (walks up the tree).tool-versions file (asdf compatibility)- Legacy files (
.nvmrc, .python-version, .ruby-version)
~/.config/mise/config.toml (global default)
Quick Reference
| Pattern |
Command / Config |
Key Points |
| Install tools |
mise install |
Reads mise.toml, installs all listed tools |
| Pin tool version |
mise use node@22 |
Writes to mise.toml in current directory |
| Pin globally |
mise use -g node@22 |
Writes to ~/.config/mise/config.toml |
| Run a task |
mise run build |
Runs task defined in mise.toml |
| Run with args |
mise run test -- --watch |
Passes args after -- to the task |
| Watch mode |
mise watch build |
Re-runs task when sources change |
| List tasks |
mise tasks |
Shows all available tasks |
| Set env vars |
[env] section in mise.toml |
Per-directory, auto-activated on cd |
| Load .env file |
_.file = ".env" |
Loads dotenv into environment |
| Extend PATH |
_.path = ["./bin"] |
Prepends directories to PATH |
| List installed |
mise ls |
Shows all installed tool versions |
| Outdated tools |
mise outdated |
Shows tools with newer versions |
| Upgrade tools |
mise upgrade |
Upgrades tools to latest within constraints |
| Trust config |
mise trust |
Trusts mise.toml in current directory |
| Tool backends |
"npm:prettier" / "cargo:cargo-machete" |
Install from npm, cargo, pipx, GitHub, etc. |
| Task dependencies |
depends = ["lint", "test"] |
Prerequisite tasks run first |
| Incremental build |
sources + outputs on task |
Skips task if outputs newer than sources |
| Exec without activate |
mise exec -- node app.js |
Runs command with mise-managed tools |
| Diagnostics |
mise doctor |
Check installation and config health |
| Prune unused |
mise prune |
Remove tool versions not in any config |
| Generate hook |
mise generate git-pre-commit |
Generate git pre-commit hook for tasks |
| Env-specific config |
.mise.staging.toml |
Activated via MISE_ENV=staging |
| Shims for IDEs |
mise settings set shims_on_path true |
PATH-based shims for IDE compatibility |
Common Mistakes
| Mistake |
Correct Pattern |
Using mise install node@22 without mise use |
mise use node@22 both installs and pins to mise.toml |
Editing .tool-versions manually with mise |
Use mise use to update; mise.toml is preferred over .tool-versions |
Forgetting mise trust on new project clone |
Run mise trust to activate untrusted config files |
Using depends key for task dependencies |
Current key is depends (array), not deps |
Running mise run without activating mise |
Run mise activate in shell profile or use mise exec |
| Putting secrets directly in mise.toml |
Use _.file = ".env.local" and gitignore the .env file |
Expecting env vars without cd-ing into project |
Mise activates env on directory change; use mise env to debug |
Using latest version in shared projects |
Pin specific major versions (node = "22") for reproducibility |
| Defining tasks in Makefile alongside mise |
Consolidate all tasks in mise.toml for one tool |
| Missing shebang in multi-line task scripts |
Add #!/usr/bin/env bash for explicit interpreter |
Not using sources/outputs for slow tasks |
Define source globs for incremental skipping and watch mode |
Using mise activate in non-interactive scripts |
Use mise exec or eval "$(mise env)" in scripts and CI |
Delegation
- Task pattern discovery: Use
Explore agent
- Configuration review: Use
Task agent
- CI pipeline integration: Use
Task agent
If the rust skill is available, delegate Rust toolchain management patterns to it.
If the python-uv skill is available, delegate Python version and virtual environment patterns to it.
If the github-actions skill is available, delegate CI workflow patterns to it.
If the docker skill is available, delegate containerized workflow patterns to it.
If the pino-logging skill is available, delegate logging configuration patterns to it.
If the sentry skill is available, delegate error monitoring setup patterns to it.
References
- Tool version management and backends
- Task definitions, dependencies, and scripts
- Environment variables and dotenv integration
- Configuration files and settings
- Common task patterns for projects
- Migration from asdf, nvm, and alternatives
1---2name: mise3description: Mise (formerly rtx) polyglot tool version manager, environment variable manager, and task runner. Covers tool version management (install, use, pin across Node/Python/Rust/Go/Java and more), mise.toml task definitions (scripts, dependencies, watch mode, incremental builds), environment variable management (.env integration, per-directory env, redaction), project-level tool pinning, backend system (asdf, npm, pipx, cargo, GitHub releases), and comparison with alternatives (asdf, nvm, pyenv, Makefiles). Use when configuring development tool versions, defining project tasks in mise.toml, managing per-project environment variables, setting up polyglot dev environments, migrating from asdf or nvm, or automating build/test/lint/deploy workflows with mise run.4license: MIT5---6
7# Mise
8
9## Overview
10
11Mise is a **polyglot development tool manager** that handles tool versions, environment variables, and task running in a single CLI. It replaces asdf, nvm, pyenv, direnv, and Makefiles with a unified `mise.toml` configuration per project.
12
13**When to use:** Managing multiple language runtimes per project, defining reproducible dev environments, running project tasks with dependencies, replacing scattered `.nvmrc`/`.python-version`/`.tool-versions` files, automating CI pipelines.
14
15**When NOT to use:** Container-only workflows where all tools live in Docker images, single-language projects already well-served by their native version manager, production runtime management (mise is a dev tool).
16
17## Version Resolution Order
18
19Mise resolves tool versions by checking these sources in priority order:
20
211. `MISE_<TOOL>_VERSION` environment variable
222. `mise.toml` in current directory
233. `mise.toml` in parent directories (walks up the tree)
244. `.tool-versions` file (asdf compatibility)
255. Legacy files (`.nvmrc`, `.python-version`, `.ruby-version`)
266. `~/.config/mise/config.toml` (global default)
27
28## Quick Reference
29
30| Pattern | Command / Config | Key Points |
31| --------------------- | ------------------------------------------ | ------------------------------------------- |
32| Install tools | `mise install` | Reads mise.toml, installs all listed tools |
33| Pin tool version | `mise use node@22` | Writes to mise.toml in current directory |
34| Pin globally | `mise use -g node@22` | Writes to ~/.config/mise/config.toml |
35| Run a task | `mise run build` | Runs task defined in mise.toml |
36| Run with args | `mise run test -- --watch` | Passes args after `--` to the task |
37| Watch mode | `mise watch build` | Re-runs task when sources change |
38| List tasks | `mise tasks` | Shows all available tasks |
39| Set env vars | `[env]` section in mise.toml | Per-directory, auto-activated on cd |
40| Load .env file | `_.file = ".env"` | Loads dotenv into environment |
41| Extend PATH | `_.path = ["./bin"]` | Prepends directories to PATH |
42| List installed | `mise ls` | Shows all installed tool versions |
43| Outdated tools | `mise outdated` | Shows tools with newer versions |
44| Upgrade tools | `mise upgrade` | Upgrades tools to latest within constraints |
45| Trust config | `mise trust` | Trusts mise.toml in current directory |
46| Tool backends | `"npm:prettier"` / `"cargo:cargo-machete"` | Install from npm, cargo, pipx, GitHub, etc. |
47| Task dependencies | `depends = ["lint", "test"]` | Prerequisite tasks run first |
48| Incremental build | `sources` + `outputs` on task | Skips task if outputs newer than sources |
49| Exec without activate | `mise exec -- node app.js` | Runs command with mise-managed tools |
50| Diagnostics | `mise doctor` | Check installation and config health |
51| Prune unused | `mise prune` | Remove tool versions not in any config |
52| Generate hook | `mise generate git-pre-commit` | Generate git pre-commit hook for tasks |
53| Env-specific config | `.mise.staging.toml` | Activated via `MISE_ENV=staging` |
54| Shims for IDEs | `mise settings set shims_on_path true` | PATH-based shims for IDE compatibility |
55
56## Common Mistakes
57
58| Mistake | Correct Pattern |
59| ------------------------------------------------ | -------------------------------------------------------------------- |
60| Using `mise install node@22` without `mise use` | `mise use node@22` both installs and pins to mise.toml |
61| Editing `.tool-versions` manually with mise | Use `mise use` to update; mise.toml is preferred over .tool-versions |
62| Forgetting `mise trust` on new project clone | Run `mise trust` to activate untrusted config files |
63| Using `depends` key for task dependencies | Current key is `depends` (array), not `deps` |
64| Running `mise run` without activating mise | Run `mise activate` in shell profile or use `mise exec` |
65| Putting secrets directly in mise.toml | Use `_.file = ".env.local"` and gitignore the .env file |
66| Expecting env vars without `cd`-ing into project | Mise activates env on directory change; use `mise env` to debug |
67| Using `latest` version in shared projects | Pin specific major versions (`node = "22"`) for reproducibility |
68| Defining tasks in Makefile alongside mise | Consolidate all tasks in mise.toml for one tool |
69| Missing shebang in multi-line task scripts | Add `#!/usr/bin/env bash` for explicit interpreter |
70| Not using `sources`/`outputs` for slow tasks | Define source globs for incremental skipping and watch mode |
71| Using `mise activate` in non-interactive scripts | Use `mise exec` or `eval "$(mise env)"` in scripts and CI |
72
73## Delegation
74
75- **Task pattern discovery**: Use `Explore` agent
76- **Configuration review**: Use `Task` agent
77- **CI pipeline integration**: Use `Task` agent
78
79> If the `rust` skill is available, delegate Rust toolchain management patterns to it.
80> If the `python-uv` skill is available, delegate Python version and virtual environment patterns to it.
81> If the `github-actions` skill is available, delegate CI workflow patterns to it.
82> If the `docker` skill is available, delegate containerized workflow patterns to it.
83> If the `pino-logging` skill is available, delegate logging configuration patterns to it.
84> If the `sentry` skill is available, delegate error monitoring setup patterns to it.
85
86## References
87
88- [Tool version management and backends](references/tool-management.md)
89- [Task definitions, dependencies, and scripts](references/task-runner.md)
90- [Environment variables and dotenv integration](references/environment-variables.md)
91- [Configuration files and settings](references/configuration.md)
92- [Common task patterns for projects](references/task-patterns.md)
93- [Migration from asdf, nvm, and alternatives](references/migration.md)
oakoss