Skip to content

3. Adoption of Mise for Tool and Task Management

Date: 2025-08-20

Status

Accepted

Context

A modern development environment requires managing dozens of CLI tools (40+ in this project), each with specific versions. Traditional approaches include:

  1. System package managers — Tools drift out of sync, version conflicts across projects
  2. Manual installation — Unsustainable maintenance burden
  3. asdf — Popular polyglot version manager with plugin ecosystem

The project originally used direct installations but needed a declarative, reproducible tool management system.

Decision

We have adopted Mise (formerly rtx) as the unified tool and task management system, replacing asdf.

Consequences

Positive

  • Performance — Written in Rust, significantly faster than bash-based asdf (cold start: ~10ms vs ~100ms)
  • Single Binary — No separate plugin installations, simpler CI setup
  • Built-in Task Runner — Replaces make, just, or custom scripts with mise run <task>
  • Environment Management — Native .env file support and environment variable injection
  • Better UX — Clearer error messages, faster mise install, intuitive CLI
  • Backward Compatible — Reads .tool-versions files, smooth migration from asdf

Negative

  • Newer Project — Less mature ecosystem than asdf (mitigated by rapid development and active maintainer)
  • Plugin Ecosystem — Smaller than asdf's, but growing quickly and all critical tools are available

Trade-offs

  • Speed vs Maturity — Chose performance and modern architecture over asdf's longer track record
  • Task Runner Consolidation — Gained task management but added dependency on mise-specific task format

Implementation Details

  • Configuration: mise.toml — Declarative tool versions and task definitions
  • Tasks Location: mise-tasks/ directory for complex multi-line tasks
  • Global Installation: Installed via system package manager (pacman/apt) or direct download
  • Shell Integration: Automatic PATH and environment variable injection via mise activate

Key Features Used

  1. Tool Management: 40+ CLI tools (bat, eza, fzf, fd, ripgrep, zoxide, etc.)
  2. Task Runner: install, doctor, test, backup, uninstall, rotate-secrets
  3. Environment Variables: Centralized in mise.toml [env] section

Migration Notes

Migration from asdf was straightforward:

  • Converted .tool-versions to mise.toml
  • Replaced custom bash scripts with mise tasks
  • Removed asdf-specific shell hooks

References