mise

name	mise
description	Use when setting up development toolchains with mise, managing tool versions, configuring project environments, or defining build/test/deploy tasks - covers both mise.toml for repos you control and mise.local.toml for repos you contribute to

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

Authoritative Resources

• mise Documentation
• Configuration Reference
• Task Runner
• Task Configuration
• Monorepo Tasks (experimental)
• CI/CD Integration