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>_VERSIONenvironment variablemise.tomlin current directorymise.tomlin parent directories (walks up the tree).tool-versionsfile (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-watch" | 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
Exploreagent - Configuration review: Use
Taskagent - CI pipeline integration: Use
Taskagent
If therustskill is available, delegate Rust toolchain management patterns to it. If thepython-uvskill is available, delegate Python version and virtual environment patterns to it. If thegithub-actionsskill is available, delegate CI workflow patterns to it. If thedockerskill is available, delegate containerized workflow patterns to it. If thepino-loggingskill is available, delegate logging configuration patterns to it. If thesentryskill is available, delegate error monitoring setup patterns to it.