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

mise