mise Tool Management

When to invoke

• Starting a new project and picking a version manager for binary CLI / build tools.
• Writing the first .mise.toml.
• Adding new binary tools (swiftlint, swiftformat, xcbeautify, gitleaks, lefthook, jq, yq, ...).
• Setting up CI (e.g. Xcode Cloud ci_scripts/) that needs to call tools.
• User asks "asdf vs mise", "why isn't Homebrew enough", "what about CI / local version drift".

Default decisions

• Adopt mise (mise.jdx.dev) to manage binary CLI / build tools.
• Dev machine and CI share the same .mise.toml, committed to git. Both .mise.toml and mise.toml (no leading dot) are valid config filenames — mise's own docs primarily spell it mise.toml — but this catalog's convention is the dotfile form.
• Plugin backend priority: core plugin → aqua: → github:/gitlab: (release assets) → asdf: (legacy). ubi: is deprecated — mise's own release-backend docs mark it "Legacy release installer (deprecated)".
• Xcode Cloud has no mise preinstalled — its build environment ships only Homebrew, so a ci_post_clone.sh that starts with a bare mise command fails with "command not found". Xcode Cloud also runs ci_post_clone.sh with ci_scripts/ as the working directory, so the script must cd "$CI_PRIMARY_REPOSITORY_PATH" first or ./bin/mise won't resolve. Commit a bootstrapped bin/mise (mise generate install-script --localize --write bin/mise — requires mise ≥ 2026.8.11; on older mise run mise self-update, or use the old mise generate bootstrap --localize --write bin/mise, which newer mise keeps as a deprecated alias scheduled for removal in mise 2027.9.0) and call it explicitly: after cd "$CI_PRIMARY_REPOSITORY_PATH", run ./bin/mise trust && ./bin/mise install; subsequent tool invocations always go through ./bin/mise exec -- <tool> <args> (see xcode-cloud-single-track-ci for the full hook). On a dev machine or any CI runner that already has mise on PATH, drop the ./bin/ prefix: mise exec -- <tool> <args>.
• A freshly cloned repo or a freshly created git worktree starts with .mise.toml untrusted. On mise < 2026.8.9, or in paranoid / safe mode, mise install / mise exec hard-error with Config files in <dir> are not trusted. Trust them with 'mise trust' until mise trust has run once in that directory; from mise 2026.8.9, normal mode implicitly trusts the active config for mise install / mise exec / mise run. A committed bin/mise pins its own mise version, so keep running mise trust before the first mise install/mise exec in every new agent worktree and CI checkout — harmless on new mise, required on old.

Rationale