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 variable
mise.toml in current directory
mise.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-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 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.