mise — Gestor de versiones y entornos

Qué es

mise es un gestor de versiones políglota y runner de tareas. Reemplaza a nvm, pyenv, rbenv, asdf y Makefile/npm scripts en un solo binario escrito en Rust. Activa automáticamente las versiones correctas de cada herramienta al entrar a un directorio.

Por qué lo usamos en Wiedii

La razón central es reproducibilidad sin fricción: cada desarrollador, en cualquier máquina, ejecuta exactamente las mismas versiones de bun, node y python que el resto del equipo — sin pasos manuales, sin scripts de setup, sin documentos de "antes de empezar".

Además reemplaza tres herramientas separadas:

• nvm / pyenv / asdf → mise gestiona todos los runtimes en un solo lugar
• npm scripts / Makefile → las tasks de mise son el runner estándar
• dotenv / direnv → mise activa variables de entorno por directorio

Instalación

brew install mise

Activar en el shell (va en ~/.zprofile):

eval "$(mise activate zsh --shims)"

~/.zprofile se carga al abrir una terminal nueva (no en las ya abiertas). Después de editar este archivo, abre una terminal nueva para que tome efecto — o ejecuta exec zsh en el terminal actual.

---

Bondades clave

Activación automática por directorio

Al entrar a un directorio con mise.toml, mise activa las versiones declaradas sin ningún comando adicional. Al salir, las desactiva.

cd ~/Docker/proyecto-alpha
bun --version   # 1.2.5 — del mise.toml del proyecto

cd ~/Docker/proyecto-beta
bun --version   # 1.1.8 — diferente proyecto, diferente versión

cd ~
bun --version   # 1.3.14 — del config global

Esto funciona mediante shims: mise intercepta los binarios y redirige a la versión correcta según el directorio. No requiere eval en cada directorio ni hooks de cd.

📄 Documentación: Dev Tools

---

mise-lock — reproducibilidad exacta entre máquinas

Con lockfile = true en el config, mise genera un archivo mise.lock que fija las versiones resueltas exactas (incluyendo parches) de todas las herramientas. El lockfile se commitea al repo.

# ~/.config/mise/config.toml o mise.toml del proyecto
[settings]
lockfile = true

# mise.lock (generado automáticamente — commitear al repo)
[tools.bun]
version = "1.3.14"
backend = "aqua:nicholasgasior/bun"

Con el lockfile en git, mise install --yes en cualquier máquina instala exactamente la misma versión, sin posibilidad de drift entre desarrolladores.

📄 Documentación: mise-lock

---

mise exec — ejecutar con versiones específicas sin activar el entorno

mise exec (o mise x) ejecuta un comando con las herramientas de mise activas, incluso desde contextos donde el entorno no está inicializado: hooks de git, scripts de CI, cron jobs.

# Ejecutar un comando con las versiones del mise.toml actual
mise exec -- bun run build
mise exec -- python script.py

# Abreviado
mise x -- taplo fmt mise.toml
mise x -- hadolint Dockerfile

# Con versión específica sin mise.toml
mise exec bun@1.2.5 -- bun test

Esto es especialmente útil en lefthook.yaml para garantizar que los hooks usen las versiones del proyecto aunque el shell no tenga el entorno activado:

# lefthook.yaml
pre-commit:
  commands:
    toml:
      glob: '*.toml'
      run: mise exec -- taplo fmt {staged_files}
    hadolint:
      glob: 'Dockerfile'
      run: mise exec -- hadolint {staged_files}

📄 Documentación: mise exec

---

Tasks — runner de tareas integrado

mise incluye un runner de tareas que reemplaza npm run, Makefile y scripts de shell. Las tasks se declaran en mise.toml y son auto-documentadas.

# mise.toml
[tasks.setup]
run = [
  "mise trust",
  "mise install --yes",
  "bun install",
  "lefthook install"
]
description = "Configura el entorno completo del proyecto"

[tasks.dev]
run = "bun run dev"
description = "Arranca el servidor de desarrollo"

[tasks.test]
run = "bun test"
description = "Ejecuta los tests"

[tasks.lint]
run = "bun eslint . --cache"
description = "Lint del código fuente"

mise run setup    # configuración completa con un comando
mise run dev      # servidor de desarrollo
mise tasks        # lista todas las tasks disponibles con descripción

📄 Documentación: Tasks

---

mise trust — modelo de seguridad

mise no activa un mise.toml a menos que el desarrollador lo haya marcado explícitamente como confiable. Esto evita la ejecución automática de código malicioso al entrar en un directorio clonado.

mise trust           # confiar en el mise.toml del directorio actual
mise trust --all     # confiar en todos los mise.toml del sistema (⚠️ úsalo solo en máquinas personales)

El workflow estándar en Wiedii:

git clone git@gitlab.wiedii.co:wiedii/proyecto.git
cd proyecto
mise trust           # explícitamente confiar en el proyecto
mise run setup       # ahora se puede ejecutar el setup

📄 Documentación: Trusted configs

---

Backends múltiples

mise instala herramientas desde múltiples fuentes. Antes de agregar cualquier herramienta, verificar su backend disponible en mise-versions.jdx.dev y elegir según esta prioridad:

Prioridad	Backend	Ejemplo	Cuándo usarlo
1º	aqua	terraform, golangci-lint	Preferido siempre. Registro curado de mise con checksums verificados.
2º	npm	mise use npm:@anthropic/claude-cli	CLIs de npm que no van en package.json del proyecto.
3º	pipx	mise use pipx:ruff	CLIs de Python que no van en pyproject.toml.
4º	cargo	mise use cargo:taplo-cli	CLIs Rust no disponibles en aqua.
5º	asdf	plugins heredados	Solo si ningún otro backend funciona.

Regla clave: herramientas que pertenecen al ecosistema del lenguaje van en su gestor nativo (prettier → package.json, ruff → pyproject.toml), no en mise. Excepción: CLIs de Go siempre van en mise.toml porque go.mod solo registra librerías importadas en código, nunca executables. Ver gestion-herramientas-brew-mise para el árbol de decisión completo y la tabla de ejemplos.

📄 Catálogo de herramientas y backends 📄 Documentación: Registry 📄 Documentación: Backends

---

Configuración estándar de Wiedii

Config global (~/.config/mise/config.toml)

[tools]
bun    = "1.3.14"
node   = "24.16.0"
pnpm   = "11.2.2"
python = "3.14.5"
uv     = "0.11.16"

[settings]
lockfile = true

Config de proyecto (mise.toml en la raíz del repo)

[tools]
bun      = "1.2.5"    # versión específica del proyecto — sobreescribe global
lefthook = "1.9.0"

[settings]
lockfile = true

[tasks.setup]
run = [
  "mise trust",
  "mise install --yes",
  "bun install",
  "lefthook install"
]
description = "Configura el entorno completo del proyecto"

---

Comandos clave

# Gestión de versiones
# Para el config global, debes estar en el directorio correcto:
cd ~/.config/mise && mise install --yes   # instalar runtimes globales
cd -

# Para instalar las herramientas del proyecto (desde la raíz del repo):
mise install --yes          # instalar herramientas del mise.toml del proyecto

mise use bun@1.3.14         # agregar herramienta al mise.toml del proyecto
mise use --global bun@1.3.14  # agregar al config global
mise ls                     # listar herramientas activas en el directorio
mise ls --current           # solo las herramientas activas ahora
mise outdated               # ver qué herramientas tienen versión más nueva

# Ejecución
mise run setup              # ejecutar task 'setup'
mise tasks                  # listar todas las tasks disponibles
mise exec -- <comando>      # ejecutar comando con el entorno de mise activo

# Config y confianza
mise trust                  # confiar en el mise.toml actual
mise config                 # ver config efectivo del directorio actual

📄 Referencia completa de CLI

---

Troubleshooting rápido

mise run setup falla con "not trusted":

mise trust && mise run setup

Herramienta no se activa al entrar al directorio:

mise ls          # verificar que está declarada en mise.toml
mise trust       # verificar que el directorio está en trusted
eval "$(mise activate zsh)"   # verificar que la activación está en el shell

Versión incorrecta (el global sobreescribe al proyecto):

# Los shims deben ir al FINAL de .zshrc para tener máxima prioridad
tail -3 ~/.zshrc   # debe terminar con: export PATH="$HOME/.local/share/mise/shims:$PATH"
# Si moviste la línea, recarga: exec zsh (en cada terminal abierta)

Conflicto con versión global:

mise ls --current   # ver qué versión está activa y de dónde viene

---

Referencias

• Documentación oficial mise
• mise-versions.jdx.dev — catálogo de herramientas y backends
• mise-lock — lockfiles
• mise exec — ejecutar con entorno
• Tasks — runner de tareas
• Trusted configs — seguridad
• Registry de herramientas
• Backends (aqua, npm, pipx, cargo, asdf)
• Referencia completa de CLI
• gestion-herramientas-brew-mise — arquitectura de 3 niveles
• guia-nuevo-dev — onboarding paso a paso
• mise-tooling — política detallada de mise.toml