mise

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:

1. MISE_<TOOL>_VERSION environment variable
2. mise.toml in current directory
3. mise.toml in parent directories (walks up the tree)
4. .tool-versions file (asdf compatibility)
5. Legacy files (.nvmrc, .python-version, .ruby-version)
6. ~/.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