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: mise
3description: |
4 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).
5
6 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.
7license: MIT
8metadata:
9 author: oakoss
10 version: '1.0'
11 source: 'https://mise.jdx.dev'
12user-invocable: false
13---
14
15# Mise
16
17## Overview
18
19Mise 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.
20
21**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.
22
23**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).
24
25## Version Resolution Order
26
27Mise resolves tool versions by checking these sources in priority order:
28
291. `MISE_<TOOL>_VERSION` environment variable
302. `mise.toml` in current directory
313. `mise.toml` in parent directories (walks up the tree)
324. `.tool-versions` file (asdf compatibility)
335. Legacy files (`.nvmrc`, `.python-version`, `.ruby-version`)
346. `~/.config/mise/config.toml` (global default)
35
36## Quick Reference
37
38| Pattern | Command / Config | Key Points |
39| --------------------- | ------------------------------------------ | ------------------------------------------- |
40| Install tools | `mise install` | Reads mise.toml, installs all listed tools |
41| Pin tool version | `mise use node@22` | Writes to mise.toml in current directory |
42| Pin globally | `mise use -g node@22` | Writes to ~/.config/mise/config.toml |
43| Run a task | `mise run build` | Runs task defined in mise.toml |
44| Run with args | `mise run test -- --watch` | Passes args after `--` to the task |
45| Watch mode | `mise watch build` | Re-runs task when sources change |
46| List tasks | `mise tasks` | Shows all available tasks |
47| Set env vars | `[env]` section in mise.toml | Per-directory, auto-activated on cd |
48| Load .env file | `_.file = ".env"` | Loads dotenv into environment |
49| Extend PATH | `_.path = ["./bin"]` | Prepends directories to PATH |
50| List installed | `mise ls` | Shows all installed tool versions |
51| Outdated tools | `mise outdated` | Shows tools with newer versions |
52| Upgrade tools | `mise upgrade` | Upgrades tools to latest within constraints |
53| Trust config | `mise trust` | Trusts mise.toml in current directory |
54| Tool backends | `"npm:prettier"` / `"cargo:cargo-machete"` | Install from npm, cargo, pipx, GitHub, etc. |
55| Task dependencies | `depends = ["lint", "test"]` | Prerequisite tasks run first |
56| Incremental build | `sources` + `outputs` on task | Skips task if outputs newer than sources |
57| Exec without activate | `mise exec -- node app.js` | Runs command with mise-managed tools |
58| Diagnostics | `mise doctor` | Check installation and config health |
59| Prune unused | `mise prune` | Remove tool versions not in any config |
60| Generate hook | `mise generate git-pre-commit` | Generate git pre-commit hook for tasks |
61| Env-specific config | `.mise.staging.toml` | Activated via `MISE_ENV=staging` |
62| Shims for IDEs | `mise settings set shims_on_path true` | PATH-based shims for IDE compatibility |
63
64## Common Mistakes
65
66| Mistake | Correct Pattern |
67| ------------------------------------------------ | -------------------------------------------------------------------- |
68| Using `mise install node@22` without `mise use` | `mise use node@22` both installs and pins to mise.toml |
69| Editing `.tool-versions` manually with mise | Use `mise use` to update; mise.toml is preferred over .tool-versions |
70| Forgetting `mise trust` on new project clone | Run `mise trust` to activate untrusted config files |
71| Using `depends` key for task dependencies | Current key is `depends` (array), not `deps` |
72| Running `mise run` without activating mise | Run `mise activate` in shell profile or use `mise exec` |
73| Putting secrets directly in mise.toml | Use `_.file = ".env.local"` and gitignore the .env file |
74| Expecting env vars without `cd`-ing into project | Mise activates env on directory change; use `mise env` to debug |
75| Using `latest` version in shared projects | Pin specific major versions (`node = "22"`) for reproducibility |
76| Defining tasks in Makefile alongside mise | Consolidate all tasks in mise.toml for one tool |
77| Missing shebang in multi-line task scripts | Add `#!/usr/bin/env bash` for explicit interpreter |
78| Not using `sources`/`outputs` for slow tasks | Define source globs for incremental skipping and watch mode |
79| Using `mise activate` in non-interactive scripts | Use `mise exec` or `eval "$(mise env)"` in scripts and CI |
80
81## Delegation
82
83- **Task pattern discovery**: Use `Explore` agent
84- **Configuration review**: Use `Task` agent
85- **CI pipeline integration**: Use `Task` agent
86
87> If the `rust` skill is available, delegate Rust toolchain management patterns to it.
88> If the `python-uv` skill is available, delegate Python version and virtual environment patterns to it.
89> If the `github-actions` skill is available, delegate CI workflow patterns to it.
90> If the `docker` skill is available, delegate containerized workflow patterns to it.
91> If the `pino-logging` skill is available, delegate logging configuration patterns to it.
92> If the `sentry` skill is available, delegate error monitoring setup patterns to it.
93
94## References
95
96- [Tool version management and backends](references/tool-management.md)
97- [Task definitions, dependencies, and scripts](references/task-runner.md)
98- [Environment variables and dotenv integration](references/environment-variables.md)
99- [Configuration files and settings](references/configuration.md)
100- [Common task patterns for projects](references/task-patterns.md)
101- [Migration from asdf, nvm, and alternatives](references/migration.md)
oakoss