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

Common Mistakes

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

Configuration

Configuration File Locations

Mise reads configuration from multiple locations, merged in priority order:

Complete mise.toml Example

min_version = "2024.11.1"

[tools]
node = "22"
python = "3.12"
"npm:prettier" = "latest"

[env]
NODE_ENV = "development"
_.file = [".env", ".env.local"]
_.path = ["./node_modules/.bin"]

[tasks]
dev = "npm run dev"
build = "npm run build"
test = "npm test"
lint = "npm run lint"

[tasks.ci]
depends = ["lint", "test", "build"]

Shell Activation

Add mise activation to your shell profile for automatic tool switching on cd:

# ~/.bashrc or ~/.bash_profile
eval "$(mise activate bash)"

# ~/.zshrc
eval "$(mise activate zsh)"

# ~/.config/fish/config.fish
mise activate fish | source

Without activation, use mise exec to run commands with mise-managed tools:

mise exec -- node --version
mise exec -- python script.py

Settings

Configure mise behavior in ~/.config/mise/settings.toml:

[settings]
# Automatically install missing tools on cd
auto_install = true

# Use verbose output
verbose = false

# Number of parallel jobs for installations
jobs = 4

# Experimental features
experimental = false

# Legacy version file support (.nvmrc, .python-version, etc.)
legacy_version_file = true

# Always keep this many versions installed
always_keep_download = false

Legacy Version File Support

Mise can read existing version files from other managers:

Enable with:

[settings]
legacy_version_file = true

Diagnostics

# Check mise installation and configuration
mise doctor

# Show resolved configuration
mise settings

# Show which config files are active
mise config ls

# Show tool installation paths
mise where node

Minimum Version Pinning

Enforce a minimum mise version for your project:

min_version = "2024.11.1"

Team members with older versions get a clear error message to upgrade.

Project Initialization

# Create a new mise.toml with common defaults
mise init

# Or manually create mise.toml and add tools
mise use node@22
mise use python@3.12

Git Integration

Recommended .gitignore entries:

.mise.local.toml
.env.local
.env.*.local

Committed files:

mise.toml
.env

IDE Integration

Mise provides shims for IDE compatibility:

# Enable shims (for IDEs that don't support mise activate)
mise settings set shims_on_path true

# Reshim after installing new tools
mise reshim

Shims are located at ~/.local/share/mise/shims/. Add this to your IDE's PATH for tool discovery.

Environment Variables

Basic Environment Variables

Set environment variables in the [env] section of mise.toml. Variables activate automatically when you cd into the project directory:

[env]
NODE_ENV = "development"
DATABASE_URL = "postgres://localhost/mydb"
API_BASE_URL = "http://localhost:3000"

Loading .env Files

Load variables from dotenv files:

[env]
_.file = ".env"

Load multiple files (later files override earlier ones):

[env]
_.file = [".env", ".env.local"]

The .env.local file should be gitignored for developer-specific overrides and secrets.

Per-Environment Configuration

Use environment-specific config files with MISE_ENV:

# Activates mise.staging.toml
MISE_ENV=staging mise run deploy

Pin an environment in a local config:

mise use --env local node@22

This writes to .mise.local.toml, which should be gitignored.

Extending PATH

Add directories to the front of PATH:

[env]
_.path = ["./bin", "./node_modules/.bin", "./scripts"]

This prepends the listed directories to PATH when inside the project.

Sourcing Shell Scripts

Load environment variables from a shell script:

[env]
_.source = "./scripts/env.sh"

The script is sourced in a subshell and any exported variables are captured.

Required Variables

Mark variables as required without setting a value. Mise errors if they are not set in the environment:

[env]
DATABASE_URL = { required = true }
API_KEY = { required = true }

This is useful for documenting required secrets without committing their values.

Redacted Variables

Mark sensitive values as redacted to hide them from mise env output and logs:

[env]
API_KEY = { value = "sk-abc123", redact = true }

Variable Templates

Use templates to reference other variables or dynamic values:

[env]
PROJECT_ROOT = "{{cwd}}"
LOG_DIR = "{{cwd}}/logs"
PATH_ADDITION = "{{cwd}}/bin"

Debugging Environment

Inspect the active environment:

# Show all environment variables mise would set
mise env

# Show env for a specific tool
mise env node

# Print as shell export statements
mise env --shell bash

# Check which config files are loaded
mise doctor

Environment Variable Precedence

Variables are resolved in this order (highest priority first):

1. Shell environment (already set before mise) 2. Task-level env overrides 3. mise.toml [env] section in current directory 4. mise.toml [env] in parent directories 5. _.file dotenv files 6. ~/.config/mise/config.toml global config

Practical Patterns

Development vs Production Separation

# mise.toml (committed)
[env]
NODE_ENV = "development"
LOG_LEVEL = "debug"
_.file = [".env", ".env.local"]

# .env (committed, safe defaults)
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=myapp_dev

# .env.local (gitignored, secrets)
DATABASE_PASSWORD=mysecretpassword
API_KEY=sk-live-abc123

Monorepo with Nested Configs

# apps/api/mise.toml
[env]
PORT = "3001"
SERVICE_NAME = "api"

# apps/web/mise.toml
[env]
PORT = "3000"
SERVICE_NAME = "web"
NEXT_PUBLIC_API_URL = "http://localhost:3001"

Each subdirectory gets its own environment when you cd into it.

Migration

From asdf

Mise is a drop-in replacement for asdf with full .tool-versions compatibility.

Direct Compatibility

Mise reads .tool-versions files natively:

node 22.11.0
python 3.12.1
ruby 3.3.0

No changes needed to start using mise with existing asdf projects.

Migration to mise.toml

Convert .tool-versions to mise.toml for access to tasks, env, and backends:

# Before (.tool-versions)
# node 22.11.0
# python 3.12.1

# After (mise.toml) - use mise to generate
mise use node@22.11.0
mise use python@3.12.1

Resulting mise.toml:

[tools]
node = "22.11.0"
python = "3.12.1"

Key Differences from asdf

Plugin Compatibility

Mise uses the same plugin system as asdf. Existing asdf plugins work with mise:

# asdf plugins work in mise
mise plugins install terraform
mise use terraform@1.7

From nvm

Replace nvm with mise for Node.js version management:

# nvm (before)
# .nvmrc contains: 22
nvm install
nvm use

# mise (after)
mise use node@22

Mise reads .nvmrc files automatically when legacy_version_file = true (enabled by default).

Remove nvm from your shell profile and replace with mise activation:

# Remove from .zshrc:
# export NVM_DIR="$HOME/.nvm"
# [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# Add to .zshrc:
eval "$(mise activate zsh)"

From pyenv

Replace pyenv with mise for Python version management:

# pyenv (before)
# .python-version contains: 3.12.1
pyenv install 3.12.1
pyenv local 3.12.1

# mise (after)
mise use python@3.12.1

Mise reads .python-version files automatically.

Remove pyenv from your shell profile:

# Remove from .zshrc:
# export PYENV_ROOT="$HOME/.pyenv"
# eval "$(pyenv init -)"

# Add to .zshrc (if not already added):
eval "$(mise activate zsh)"

From Makefiles

Replace Makefile targets with mise tasks:

# Makefile (before)
.PHONY: build test lint fmt ci

build:
    cargo build --release

test:
    cargo test

lint:
    cargo clippy -- -D warnings

fmt:
    cargo fmt

ci: fmt lint test build

# mise.toml (after)
[tasks]
build = "cargo build --release"
test = "cargo test"
lint = "cargo clippy -- -D warnings"
fmt = "cargo fmt"

[tasks.ci]
depends = ["fmt", "lint", "test", "build"]

Advantages Over Makefiles

From direnv

Mise replaces direnv for per-directory environment variables:

# .envrc (before, direnv)
export NODE_ENV=development
export DATABASE_URL=postgres://localhost/mydb
dotenv .env.local

# mise.toml (after)
[env]
NODE_ENV = "development"
DATABASE_URL = "postgres://localhost/mydb"
_.file = ".env.local"

Remove direnv from your shell profile if fully migrating to mise.

From Multiple Tools to One

A common migration consolidates several tools:

# Before: nvm + pyenv + direnv + Makefile
# .nvmrc, .python-version, .envrc, Makefile

# After: just mise.toml

# mise.toml replaces all four
[tools]
node = "22"
python = "3.12"

[env]
NODE_ENV = "development"
_.file = ".env.local"

[tasks]
build = "npm run build"
test = "pytest -v"
lint = "eslint src/ && ruff check ."

[tasks.ci]
depends = ["lint", "test", "build"]

Task Patterns

Standard Task Set

A typical project defines these common tasks:

[tasks]
fmt = "prettier --write ."
"fmt:check" = "prettier --check ."
lint = "eslint src/"
"lint:fix" = "eslint src/ --fix"
test = "vitest run"
"test:watch" = "vitest"
"test:coverage" = "vitest run --coverage"
build = "tsc && vite build"
dev = "vite dev"
clean = "rm -rf dist node_modules/.cache"

CI Pipeline Task

Compose tasks into a CI pipeline using dependencies:

[tasks.ci]
description = "Run full CI pipeline"
depends = ["fmt:check", "lint", "test", "build"]

Run the entire pipeline:

mise run ci

Rust Project Tasks

[tools]
rust = "1.77"

[tasks]
fmt = "cargo fmt"
"fmt:check" = "cargo fmt --check"
lint = "cargo clippy -- -D warnings"
test = "cargo test"
build = "cargo build --release"
bench = "cargo bench"
clean = "cargo clean"

[tasks.ci]
depends = ["fmt:check", "lint", "test", "build"]

Python Project Tasks

[tools]
python = "3.12"
"pipx:ruff" = "latest"
"pipx:mypy" = "latest"

[tasks]
fmt = "ruff format ."
"fmt:check" = "ruff format --check ."
lint = "ruff check . && mypy src/"
"lint:fix" = "ruff check --fix ."
test = "pytest -v"
"test:coverage" = "pytest --cov=src --cov-report=html"
clean = "rm -rf dist __pycache__ .pytest_cache .mypy_cache"

[tasks.ci]
depends = ["fmt:check", "lint", "test"]

Go Project Tasks

[tools]
go = "1.22"
"go:mvdan.cc/gofumpt" = "latest"
"go:golang.org/x/lint/golint" = "latest"

[tasks]
fmt = "gofumpt -w ."
"fmt:check" = "gofumpt -d ."
lint = "go vet ./..."
test = "go test ./..."
"test:race" = "go test -race ./..."
build = "go build -o bin/app ./cmd/app"
bench = "go test -bench=. ./..."
clean = "rm -rf bin/"

[tasks.ci]
depends = ["fmt:check", "lint", "test:race", "build"]

Node.js/TypeScript Project Tasks

[tools]
node = "22"
"npm:prettier" = "latest"
"npm:eslint" = "9"

[tasks]
fmt = "prettier --write ."
"fmt:check" = "prettier --check ."
lint = "eslint src/"
"lint:fix" = "eslint src/ --fix"
typecheck = "tsc --noEmit"
test = "vitest run"
"test:watch" = "vitest"
build = "vite build"
dev = "vite dev"
clean = "rm -rf dist .cache node_modules/.vite"

[tasks.ci]
depends = ["fmt:check", "lint", "typecheck", "test", "build"]

Monorepo Tasks

[tasks."build:api"]
run = "npm run build"
dir = "apps/api"
sources = ["apps/api/src/**/*.ts"]
outputs = ["apps/api/dist/**/*.js"]

[tasks."build:web"]
run = "npm run build"
dir = "apps/web"
sources = ["apps/web/src/**/*.ts", "apps/web/src/**/*.tsx"]
outputs = ["apps/web/.next/**"]

[tasks.build]
depends = ["build:api", "build:web"]

[tasks."test:api"]
run = "npm test"
dir = "apps/api"

[tasks."test:web"]
run = "npm test"
dir = "apps/web"

[tasks.test]
depends = ["test:api", "test:web"]

Release and Deploy Tasks

[tasks.release]
description = "Create a new release"
confirm = "Ready to create a release?"
run = """
#!/usr/bin/env bash
set -euo pipefail
VERSION=$(git describe --tags --abbrev=0 | awk -F. '{$NF = $NF + 1;} 1' | sed 's/ /./g')
git tag -a "$VERSION" -m "Release $VERSION"
git push origin "$VERSION"
echo "Released $VERSION"
"""

[tasks.deploy]
description = "Deploy to production"
depends = ["ci"]
confirm = "Deploy to production?"
run = "./scripts/deploy.sh"
env = { NODE_ENV = "production" }

Pre-commit Hook Integration

Generate a git pre-commit hook that runs mise tasks:

mise generate git-pre-commit --write --task=pre-commit

[tasks.pre-commit]
description = "Pre-commit checks"
depends = ["fmt:check", "lint", "typecheck"]

Database Tasks

[tasks."db:migrate"]
run = "npx prisma migrate dev"
description = "Run database migrations"

[tasks."db:seed"]
run = "npx prisma db seed"
depends = ["db:migrate"]

[tasks."db:reset"]
run = "npx prisma migrate reset --force"
confirm = "This will reset the database. Continue?"

[tasks."db:studio"]
run = "npx prisma studio"
description = "Open database GUI"

Task Runner

Inline Tasks

Simple tasks can be defined as key-value pairs:

[tasks]
build = "cargo build --release"
test = "cargo test"
lint = "eslint src/"
hello = "echo 'Hello World'"

Run with:

mise run build
mise run test

Task Configuration

Full task configuration supports descriptions, aliases, environment overrides, and working directories:

[tasks.build]
description = "Build the project for production"
alias = "b"
run = "cargo build --release"
dir = "{{cwd}}"
env = { RUST_BACKTRACE = "1" }

Dependencies Between Tasks

Tasks can depend on other tasks that run first:

[tasks.build]
run = "cargo build --release"

[tasks.test]
run = "cargo test"
depends = ["build"]

[tasks.ci]
description = "Run full CI pipeline"
depends = ["lint", "test", "build"]

The depends array ensures prerequisite tasks complete before the current task starts. When a task has only dependencies and no run, it acts as a task group.

Multi-line Scripts

Use triple-quoted strings for multi-line scripts:

[tasks.deploy]
description = "Deploy to production"
run = """
#!/usr/bin/env bash
set -euo pipefail
echo "Building..."
cargo build --release
echo "Deploying..."
./scripts/deploy.sh
"""

Multiple Commands

Run multiple commands sequentially with an array:

[tasks.setup]
run = [
    "mise install",
    "npm install",
    "npm run db:migrate"
]

Different Interpreters

Specify a shebang or shell override to use non-bash interpreters:

[tasks.analyze]
run = """
#!/usr/bin/env python3
import json
with open("data.json") as f:
    data = json.load(f)
print(f"Records: {len(data)}")
"""

[tasks.script]
shell = "node -e"
run = "console.log('Hello from Node!')"

Task Arguments

Pass arguments to tasks after --:

mise run test -- --watch --verbose

For structured arguments, use the usage field:

[tasks.greet]
usage = '''
arg "<name>" help="Name to greet" default="World"
flag "-l --loud" help="Shout the greeting"
'''
run = """
#!/usr/bin/env bash
if [ "$usage_loud" = "true" ]; then
    echo "HELLO ${usage_name^^}!"
else
    echo "Hello $usage_name!"
fi
"""

Watch Mode

Re-run tasks automatically when source files change:

mise watch build
mise watch test

Watch mode uses the sources field to determine which files to monitor. Define sources on the task:

[tasks.build]
run = "tsc"
sources = ["src/**/*.ts", "tsconfig.json"]

Incremental Builds (Sources and Outputs)

Skip tasks when source files have not changed since the last run:

[tasks.compile]
description = "Compile TypeScript"
run = "tsc"
sources = ["src/**/*.ts", "tsconfig.json"]
outputs = ["dist/**/*.js"]

If all outputs are newer than all sources, the task is skipped. Use --force to override:

mise run compile --force

External Script Files

Reference standalone scripts instead of inline commands:

[tasks.release]
file = "scripts/release.sh"
description = "Cut a new release"

Confirmation Prompts

Require confirmation before running destructive tasks:

[tasks.deploy]
run = "./scripts/deploy.sh"
confirm = "Are you sure you want to deploy to production?"

Task Output Modes

Control how task output is displayed:

# Default: prefix each line with task name
mise run ci

# Interleave output from parallel tasks
mise run ci --output interleave

# Silent mode (errors only)
mise run ci --output silent

# Quiet mode (minimal output)
mise run ci --quiet

Parallel Task Execution

Independent tasks in a dependency graph run in parallel by default. Control parallelism with --jobs:

mise run ci --jobs 4

Listing Tasks

# Show all available tasks
mise tasks

# Show tasks with descriptions
mise tasks --extended

# Dry run (show execution plan without running)
mise run ci --dry-run

File-based Tasks

Tasks can be defined as executable files in a .mise/tasks/ directory:

# .mise/tasks/build
#!/usr/bin/env bash
set -euo pipefail
cargo build --release

# .mise/tasks/test
#!/usr/bin/env python3
import subprocess
subprocess.run(["pytest", "-v"], check=True)

File-based tasks are discovered automatically. The filename becomes the task name.

Tool Management

Installing and Pinning Tools

The mise use command installs a tool and writes it to mise.toml:

mise use node@22
mise use python@3.12
mise use go@1.22
mise use terraform@1.7

Pin an exact version (disables fuzzy matching):

mise use --pin node@22.11.0

Pin globally (applies to all projects without local config):

mise use -g node@22

Install all tools from existing mise.toml without modifying the file:

mise install

Tool Version Syntax

[tools]
# Fuzzy version - resolves to latest 22.x.x
node = "22"

# Exact version
python = "3.12.1"

# Latest available
go = "latest"

# LTS (for tools that support it)
node = "lts"

# Multiple versions (first is default)
python = ["3.12", "3.11"]

# Prefix match
ruby = "3.3"

Backends

Mise supports multiple backends for installing tools beyond the default asdf plugin registry:

[tools]
# Core tools (built-in, no plugin needed)
node = "22"
python = "3.12"
go = "1.22"
java = "21"
ruby = "3.3"
rust = "1.77"

# npm packages
"npm:prettier" = "latest"
"npm:eslint" = "9"
"npm:tsx" = "4"

# Python packages via pipx
"pipx:black" = "24"
"pipx:ruff" = "latest"

# Cargo crates
"cargo:cargo-watch" = "latest"
"cargo:ripgrep" = "14"

# GitHub releases
"github:BurntSushi/ripgrep" = "latest"
"github:sharkdp/fd" = "10"

# Go packages
"go:mvdan.cc/gofumpt" = "latest"

# Ubi (universal binary installer)
"ubi:cli/cli" = "latest"

Tool Options

Tools can include additional configuration:

[tools]
# Postinstall hook
node = { version = "22", postinstall = "corepack enable" }

# OS-specific tools
ripgrep = { version = "latest", os = ["linux", "macos"] }

# Architecture-specific
sometool = { version = "1.0", arch = ["x86_64"] }

Listing and Managing Versions

# List all installed tools and their versions
mise ls

# List installed versions of a specific tool
mise ls node

# Show outdated tools
mise outdated

# Upgrade tools to latest within constraints
mise upgrade

# Upgrade a specific tool
mise upgrade node

# Remove a tool version
mise uninstall node@20

# Prune unused tool versions
mise prune

# Show where a tool is installed
mise where node@22

# Show the active version of a tool
mise current node

Version Resolution Order

Mise resolves tool versions in this priority order:

1. MISE_<TOOL>_VERSION environment variable 2. mise.toml in current directory 3. mise.toml in parent directories (walks up) 4. .tool-versions file (asdf compatibility) 5. ~/.config/mise/config.toml (global default)

Config File Formats

# mise.toml (preferred)
[tools]
node = "22"
python = "3.12"

Legacy format (.tool-versions, asdf-compatible):

node 22
python 3.12

Mise reads both formats. The mise.toml format supports all features (tasks, env, backends). The .tool-versions format only supports tool versions.

Trust and Security

Mise requires explicit trust for config files from untrusted sources:

# Trust the config in current directory
mise trust

# Trust a specific file
mise trust mise.toml

# Revoke trust
mise trust --untrust

Untrusted configs are ignored until trusted. This prevents malicious mise.toml files from executing arbitrary code when you clone a repository.