hsiangjenli/mise

Mise Environment Management

Use this skill whenever a task involves installing or switching versions of developer tools. Prefer mise unless the user explicitly requires another manager or the tool is not supported by mise.

Core Rules

1. Prefer mise over tool-specific managers such as nvm, pyenv, rbenv, sdkman, or manual tarball installers.
2. When a command fails because of a version mismatch, treat the runtime or CLI version as part of the root cause and fix it with mise.
3. For Python workflows, use mise to choose the Python version but use uv run ... to execute Python commands whenever the project uses uv.
4. Prefer project-local versions for repository work and global versions for workstation defaults.
5. If mise is not activated in the shell, use mise exec ... -- <command> for one-off runs instead of assuming the PATH is already correct.
6. When a language or CLI is not already covered by local examples, check the official docs at https://mise.jdx.dev/getting-started.html and the registry/backends pages before falling back to another installer.

Default Workflow

1. Verify mise

mise --version
mise doctor

If mise is not installed yet, use:

curl https://mise.run | sh
~/.local/bin/mise --version

If shell activation is needed for interactive use, add the snippet to the shell rc file and restart the shell:

# zsh
echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc

# bash
echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc

Without activation, use mise exec -- <command> for every invocation or prefix all commands with ~/.local/bin/mise exec --.

2. Decide scope

Use global scope for machine-wide defaults:

mise use --global node@22

Use local scope for a repository or project:

mise use node@22
mise install

This writes the tool version to the local mise.toml or the global config and makes the version choice explicit.

3. Run with the correct version

For one-off commands or shells that are not activated:

mise exec node@22 -- node -v
mise exec [email protected] -- uv run python --version

For an already configured project:

mise exec -- node -v
mise exec -- uv run python --version

If the repository already uses uv, prefer uv run pytest, uv run python -m ..., and similar forms over raw python execution.

Common Tasks

Install a runtime or language

Check available versions first when precision matters:

mise latest node
mise latest bun
mise ls-remote python

Install globally:

mise use --global java@openjdk-21
mise use --global rust@latest
mise use --global [email protected]
mise use --global node@22

After installation, verify with the real executable:

java --version
rustc --version
bun --version
node --version
which node

Rust may still resolve to binaries under .cargo/bin; that is expected for the Rust toolchain.

macOS: Java system integration (optional)

After installing Java, mise may suggest creating a symlink so that IDEs and /usr/libexec/java_home can discover the JDK:

sudo mkdir /Library/Java/JavaVirtualMachines/openjdk-21.0.2.jdk
sudo ln -s ~/.local/share/mise/installs/java/openjdk-21.0.2/Contents \
  /Library/Java/JavaVirtualMachines/openjdk-21.0.2.jdk/Contents

This is optional for command-line use but required for tools that rely on the system Java registry.

Fix a version mismatch

When a project expects a different version than the current shell:

1. Identify the required version from the error, project files, CI config, or lockfiles.
2. Set the version with mise use <tool>@<version> inside the repository.
3. Run mise install if the tool is not already installed.
4. Re-run the failing command through mise exec -- ... if shell activation is uncertain.

Example:

mise use [email protected]
mise install
mise exec -- uv run python -m pytest

If the shell is already activated and the repository is using uv, the equivalent command is:

uv run python -m pytest

Python-specific rule

For Python projects:

1. Use mise to pin the interpreter version.
2. Use uv to create and run the Python environment.
3. Prefer uv run <command> over calling python, pip, or pytest directly.
4. If packages need to be added, prefer uv add or the repository's existing uv workflow.

Example:

mise use [email protected]
mise install
uv run python --version
uv run pytest

Install CLIs from non-core backends

Use the backend prefix when the tool is distributed through npm, pipx, GitHub releases, aqua, or another backend.

mise use --global npm:@anthropic-ai/claude-code
mise use --global pipx:black
mise use --global github:BurntSushi/ripgrep

If you are not sure which backend to use, check the mise docs and registry before proposing another installer.

Troubleshooting

mise command not found

Use the full path first:

~/.local/bin/mise --version

Then configure shell activation or PATH according to the official docs.

Version still looks wrong

Run these checks:

mise current
mise which node
which node
mise exec -- node -v

If which and mise which disagree, the shell likely is not activated or another manager is earlier on PATH.

For Python, also verify through uv:

mise which python
uv run python --version
uv run which python

Project config trust prompt

If a checked-in mise.toml prompts for trust, review it and then run:

mise trust

Decision Guide

• Use mise use --global ... for personal machine defaults.
• Use mise use ... in a project when the repo needs a pinned version.
• Use mise exec ... -- ... for one-off commands, CI-like execution, or when PATH setup is uncertain.
• For Python projects that use uv, run Python commands with uv run ... after selecting the interpreter version with mise.
• Use mise install after editing or creating mise.toml manually.
• Use the official docs when a language, backend, activation flow, or plugin behavior is unclear.

Response Pattern

When helping a user, prefer this order:

1. Confirm whether the need is install, upgrade, downgrade, or version alignment.
2. Choose global or local scope.
3. Use mise commands to install or switch versions.
4. For Python, route execution through uv run ... after the version is pinned.
5. Verify the active version with the real executable.
6. Re-run the original command with mise exec -- ... if activation is uncertain.

Official References

• Getting started: https://mise.jdx.dev/getting-started.html
• Registry: https://mise.jdx.dev/registry.html
• Backends: https://mise.jdx.dev/dev-tools/backends/
• Tool versions index: https://mise-versions.jdx.dev/