mise - Development Environment Management

This skill activates when working with mise for managing tool versions, environment variables, and project tasks.

When to Use This Skill

Activate when:

• Setting up development environments
• Managing tool and runtime versions (Node.js, Python, Ruby, Go, etc.)
• Configuring environment variables and secrets
• Defining and running project tasks
• Creating reproducible development setups
• Working with monorepos or multiple projects

What is mise?

mise is a polyglot runtime manager and development environment tool that combines:

• Tool version management - Install and manage multiple versions of dev tools
• Environment configuration - Set environment variables per project
• Task automation - Define and run project tasks
• Cross-platform - Works on macOS, Linux, and Windows

Installation

# macOS/Linux (using curl)
curl https://mise.run | sh

# macOS (using Homebrew)
brew install mise

# Windows
# See https://mise.jdx.dev for Windows install instructions

# Activate mise in your shell
echo 'eval "$(mise activate bash)"' >> ~/.bashrc   # bash
echo 'eval "$(mise activate zsh)"' >> ~/.zshrc     # zsh
echo 'mise activate fish | source' >> ~/.config/fish/config.fish  # fish

Managing Tools

Tool Backends

mise uses different backends (package managers) to install tools. Understanding backends helps you install tools correctly.

Available Backends

• asdf - Traditional asdf plugins (default for many tools)
• ubi - Universal Binary Installer (GitHub/GitLab releases)
• cargo - Rust packages (requires Rust installed)
• npm - Node.js packages (requires Node installed)
• go - Go packages (requires Go installed)
• aqua - Package manager
• pipx - Python packages (requires Python installed)
• gem - Ruby packages (requires Ruby installed)
• github/gitlab - Direct from repositories
• http - Direct HTTP downloads

Verifying Tool Names

Always verify tool names using mise ls-remote before adding to configuration:

# Check if tool exists in registry
mise ls-remote node

# Check tool with specific backend
mise ls-remote cargo:ripgrep
mise ls-remote ubi:sharkdp/fd

# Search the registry
mise registry | grep <tool-name>

Installing Tools

# List available tools in registry
mise registry

# Install from default backend
mise install node@20.10.0
mise install python@3.12
mise install ruby@3.3

# Install with specific backend
mise install cargo:ripgrep        # From Rust crates
mise install ubi:sharkdp/fd       # From GitHub releases
mise install npm:typescript       # From npm

# Install latest version
mise install node@latest

# Install from .mise.toml or .tool-versions
mise install

Using Tools with mise use

The mise use command is the primary way to add tools to projects. It combines two operations:

1. Installs the tool (if not already installed)
2. Adds the tool to your configuration file

Key Difference: mise install only installs tools, while mise use installs AND configures them.

Basic Usage

# Interactive selection
mise use

# Add tool with fuzzy version (default)
mise use node@20              # Saves as "20" in mise.toml

# Add tool with exact version
mise use --pin node@20.10.0   # Saves as "20.10.0"

# Add latest version
mise use node@latest          # Saves as "latest"

# Add with specific backend
mise use cargo:ripgrep@latest
mise use ubi:sharkdp/fd

Configuration File Selection

mise use writes to configuration files in this priority order:

1. --global flag: ~/.config/mise/config.toml
2. --path <file> flag: Specified file path
3. --env <env> flag: .mise.<env>.toml
4. Default: mise.toml in current directory

# Global (all projects)
mise use --global node@20

# Local (current project)
mise use node@20              # Creates/updates ./mise.toml

# Environment-specific
mise use --env local node@20  # Creates .mise.local.toml

# Specific file
mise use --path ~/.config/mise/custom.toml node@20

Important Flags

# Pin exact version
mise use --pin node@20.10.0        # Saves "20.10.0"

# Fuzzy version (default)
mise use --fuzzy node@20           # Saves "20"

# Force reinstall
mise use --force node@20

# Dry run (preview changes)
mise use --dry-run node@20

# Remove tool from config
mise use --remove node

Version Pinning

# Fuzzy (recommended) - auto-updates within major version
mise use node@20                   # Uses latest 20.x.x

# Exact - locks to specific version
mise use --pin node@20.10.0        # Always uses 20.10.0

# Latest - always uses newest version
mise use node@latest               # Always updates to latest

Best Practice: Use fuzzy versions for flexibility, mise.lock for reproducibility.

Setting Tool Versions

The mise use command automatically sets tool versions by updating configuration files.

.mise.toml Configuration

[tools]
node = "20.10.0"
python = "3.12"
ruby = "3.3"
go = "1.21"

# Use latest version
terraform = "latest"

# Backends - use quotes for namespaced tools
"cargo:ripgrep" = "latest"        # Requires rust installed
"ubi:sharkdp/fd" = "latest"       # GitHub releases
"npm:typescript" = "latest"       # Requires node installed

# Version from file
node = { version = "lts", resolve = "latest-lts" }

UBI Backend (Universal Binary Installer)

The ubi backend installs tools directly from GitHub/GitLab releases without requiring plugins. It's built into mise and works cross-platform including Windows.

Basic UBI Usage

# Install from GitHub releases
mise use -g ubi:goreleaser/goreleaser
mise use -g ubi:sharkdp/fd
mise use -g ubi:BurntSushi/ripgrep

# Specific version
mise use -g ubi:goreleaser/goreleaser@1.25.1

# In .mise.toml
[tools]
"ubi:goreleaser/goreleaser" = "latest"
"ubi:sharkdp/fd" = "2.0.0"

UBI Advanced Options

Configure tool-specific options when binary names differ or filtering is needed:

[tools]
# When executable name differs from repo name
"ubi:BurntSushi/ripgrep" = { version = "latest", exe = "rg" }

# Filter releases with matching pattern
"ubi:some/tool" = { version = "latest", matching = "linux-gnu" }

# Use regex for complex filtering
"ubi:some/tool" = { version = "latest", matching_regex = ".*-linux-.*\\.tar\\.gz$" }

# Extract entire tarball
"ubi:some/tool" = { version = "latest", extract_all = true }

# Rename extracted executable
"ubi:some/tool" = { version = "latest", rename_exe = "my-tool" }

UBI Supported Syntax

Three installation formats:

• GitHub shorthand (latest): ubi:owner/repo
• GitHub shorthand (version): ubi:owner/repo@1.2.3
• Direct URL: ubi:https://github.com/owner/repo/releases/download/v1.2.3/...

Templates

The templates/ directory contains reusable configuration snippets for common mise patterns.

Multi-Architecture Tool Installation

When installing tools from GitHub releases that provide separate binaries for different platforms/architectures, use platform-specific asset patterns.

See templates/multi-arch.md for the pattern:

[tools."github:owner/repo"]
version = "latest"

[tools."github:owner/repo".platforms]
linux-x64 = { asset_pattern = "tool_*_linux_amd64.tar.gz" }
macos-arm64 = { asset_pattern = "tool_*_darwin_arm64.tar.gz" }

Platform Keys

Common platform keys for mise:

• linux-x64 - Linux on x86_64/amd64
• linux-arm64 - Linux on ARM64/aarch64
• macos-x64 - macOS on Intel (x86_64)
• macos-arm64 - macOS on Apple Silicon (M1/M2/M3)
• windows-x64 - Windows on x86_64

Asset Pattern Wildcards

Use * as a wildcard in asset patterns to match version numbers or other variable parts of release asset names.

Example for a tool with releases like beads_1.0.0_darwin_arm64.tar.gz:

asset_pattern = "beads_*_darwin_arm64.tar.gz"

Cargo Backend

The *cargo