mise Toolchain Management
Overview
mise manages development tool versions, environment configuration, and project tasks. Use it to ensure consistent toolchains across team members and CI, and to define build/test/deploy workflows alongside your toolchain.
Core principle: Two modes — mise.toml for repos you control (committed), mise.local.toml for repos you contribute to (gitignored).
Quick Reference - What to Load
| If you're... | Load |
|---|---|
| Adopting mise in an existing project | Use mise:onboard-project skill instead |
| Setting up mise.toml, understanding precedence | references/configuration.md |
| Defining tasks, running builds, watch mode | references/tasks.md |
| Declaring task-specific tool requirements | references/tasks.md |
| Organizing tasks across packages in a monorepo | references/monorepo-tasks.md |
| Decomposing a flat taskfile into per-component definitions | references/monorepo-tasks.md |
| Seeing "command not found", activation issues | references/troubleshooting.md |
| Setting up GitHub Actions, lockfiles | references/ci-cd.md |
When to Use Each Config
| Scenario | Config File | Committed? |
|---|---|---|
| Your project, team-wide tools | mise.toml | Yes |
| Contributing to someone else's repo | mise.local.toml | No (gitignored) |
| User-wide defaults | ~/.config/mise/config.toml | N/A |
Core Principles
mise.toml for Team Configuration: When you control the repo, use mise.toml to define the project's required toolchain. Commit it. Everyone gets the same versions.
mise.local.toml for Personal Tools: When contributing to repos you don't control, use mise.local.toml for your personal tool preferences. It's gitignored by convention.
Always Run mise install: After cloning a project with mise.toml, run mise install to provision the tools. This is not automatic.
Prefer Activation over Shims: Use mise activate in your shell rc file for full feature support. Shims work but have limitations (no environment variable updates except on tool invocation).
Commit mise.lock for Reproducibility: The lockfile ensures everyone gets identical tool versions and avoids rate limiting issues.
STOP — Anti-Rationalization Table
Before writing code that matches these patterns, STOP and reconsider.
| You're about to... | Common rationalization | What to do instead |
|---|---|---|
Add mise activate to CI script | "It works locally" | CI is non-interactive. Use mise x -- command or shims. Load references/ci-cd.md. |
Skip mise.lock in the repo | "We're using 'latest'" | 'Latest' changes. Commit the lockfile for reproducibility. Load references/ci-cd.md. |
| Remove mise from CI after rate limit | "It's blocking deploys" | Set GITHUB_TOKEN for higher limits. Removing mise just moves the problem. Load references/troubleshooting.md. |
Commit mise.local.toml | "Team should have these tools too" | That's what mise.toml is for. Local files are personal. |
Use .bash_profile for activation | "It's where I put PATH" | Activation only works in .bashrc/.zshrc. Load references/troubleshooting.md. |
| Pin exact patch versions everywhere | "Maximum reproducibility" | Use mise.lock instead. Pins in config make updates tedious. |
Add a tool to project [tools] that only one task needs | "It's easier" / "Everyone might use it" | Put it in tasks.<name>.tools. Contributors who never run that task skip the install. Load references/tasks.md. |
| Put all tasks in the root mise.toml for a multi-package project | "It's simpler" / "One file to check" | Each package should own its tasks in its own mise.toml. Root orchestrates. Load references/monorepo-tasks.md. |
Define task_templates in an intermediate group config | "Templates should live near the packages that use them" | Templates ONLY resolve from root mise.toml. Move all templates to root. Load references/monorepo-tasks.md. |
Use TOML array syntax in usage field (choices=["a","b"]) | "It's a TOML file" | usage content is KDL, not TOML. Use choices "a" "b" inside a block. Load references/tasks.md. |
Pass env inside {task = "...", env = {...}} delegation | "Dependencies support it" | Delegation objects only support task/tasks keys. Use inline args or task-level env. Load references/tasks.md. |
Common Tool Configurations
Rust
[tools]
rust = { version = "latest", components = "clippy,rustfmt" }
"cargo:cargo-nextest" = "latest"
"cargo:cargo-watch" = "latest"Node.js
[tools]
node = "lts"
"npm:pnpm" = "latest"Python
[tools]
python = "3.12"
"pipx:poetry" = "latest"Common Mistakes
| Mistake | Fix |
|---|---|
Committing mise.local.toml | Add to .gitignore |
Using mise.local.toml in your own repo | Use mise.toml — let contributors benefit |
Forgetting mise install after cloning | Add to project setup docs |
Missing GITHUB_TOKEN in CI | Set token for API rate limits |
Activation in .bash_profile | Use .bashrc or .zshrc instead |