Mise

mise

Explain and apply mise options for toolchains, environment variables, tasks, and automation.

Core Workflow

1. Identify intent first: onboarding, adding a tool, task orchestration, env management, CI hardening, or troubleshooting.
2. Detect current setup before proposing changes.
3. Choose configuration scope and option set.
4. Apply changes with CLI-first commands.
5. Validate with health and behavior checks.

1) Identify Intent

Map the request to one of these paths:

• Tool versions and runtimes -> use tools flow.
• Project or shell env vars -> use environments flow.
• Build/test/deploy commands -> use tasks flow.
• Reproducible CI builds -> use lockfile and CI flow.
• "command not found" or PATH mismatch -> use troubleshooting flow.

For detailed decision tables and option references, read options-by-area.

2) Detect Current Setup

Inspect config files and trust state before editing:

ls -la mise.toml .mise.toml mise.local.toml .tool-versions 2>/dev/null
mise config
mise doctor

Prefer existing project conventions instead of introducing a new config format.

3) Choose Scope and File

• Team-wide, committed defaults: mise.toml
• Personal/local overrides (usually gitignored): mise.local.toml
• User-wide defaults: ~/.config/mise/config.toml

Decision rule:

• If the change must be shared with all contributors, use mise.toml.
• If the change is personal or machine-specific, use mise.local.toml or global config.

4) Apply CLI-First Changes

Prefer CLI over manual editing when possible:

# add or update project tools
mise use node@20

# add global defaults
mise use -g python@3.12

# install tools declared in config
mise install

# one-off execution without full shell activation
mise exec -- node -v

# run tasks with mise context (tools + env)
mise run <task>

Use explicit settings for behavior changes that affect automation or security.

5) Validate and Troubleshoot

Run a minimal validation set after edits:

mise doctor
mise ls --current
mise which <tool>
<tool> --version

If mise which <tool> differs from shell which/where, diagnose activation or PATH configuration.

Decision Points

• Activation vs shims: Use activation for interactive shells, shims for some CI or IDE contexts where shell init is limited.
• mise use vs manual TOML edits: Prefer mise use for tool additions and version changes.
• mise exec usage: Use for one-off/CI execution; do not treat it as a permanent workaround for broken activation.
• Locking strategy: Use loose versions in config plus lockfile for reproducibility.

Completion Checks

The workflow is complete when all checks pass:

• Correct config scope selected and documented.
• Tools resolve as expected in current directory.
• Tasks run with expected environment.
• CI-oriented settings (if requested) are explicitly configured and verified.
• No unresolved doctor warnings relevant to the change.

References

• Option catalog and branching logic: options-by-area