mise

What this skill does

# 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?

Current stable: v2026.3.15

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

```bash
# 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)
- **github** - GitHub release-asset installer (replaces deprecated ubi backend)
- **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)
- **gitlab** - Direct from GitLab repositories
- **http** - Direct HTTP downloads

#### Verifying Tool Names

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

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

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

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

### Discovering Available Tools with ls-remote

`mise ls-remote <backend>:<target>` returns all available versions for any backend. Run this BEFORE pinning a version in mise.toml to confirm the backend can actually see the tool.

```bash
# github backend — lists release tags from GitHub
$ mise ls-remote github:sharkdp/fd | head -5
7.0.0
7.1.0
7.2.0
7.3.0
7.4.0

# github backend — another tool
$ mise ls-remote github:goreleaser/goreleaser | head -5
2.8.1
2.8.2
2.9.0
2.10.0
2.10.1

# github backend — the GitHub CLI itself
$ mise ls-remote github:cli/cli | head -5
2.74.0
2.74.1
2.74.2
2.75.0
2.75.1

# cargo backend — lists versions from crates.io
$ mise ls-remote cargo:ripgrep | head -5
0.1.0
0.1.1
0.1.2
0.1.3
0.1.4

# go backend — requires Go installed (mise use go@latest)
$ mise ls-remote go:mvdan.cc/gofumpt | head -5
0.1.0
0.1.1
0.2.0
0.2.1
0.3.0

# npm backend — lists versions from the npm registry
$ mise ls-remote npm:typescript | head -5
0.8.0
0.8.1-1
0.8.1
0.8.2
0.8.3
```

**Failure mode — the tool lives in a different repo than you expect.** Sometimes the CLI binary is released from a different repository than the documentation or project homepage. Example:

```bash
# Returns no versions — wrong repo
$ mise ls-remote github:juxt/allium | head -5
(no output)

# Returns versions — correct repo for the CLI releases
$ mise ls-remote github:juxt/allium-tools | head -5
0.1.0
0.1.1
0.1.2
0.1.3
0.1.5
```

If `ls-remote` returns nothing, check whether the project publishes releases to a separate repository (e.g., a `-tools`, `-cli`, or `-releases` repo).

Don't pin a version you haven't verified ls-remote can see.

### Installing Tools

```bash
# List available tools in registry
mise registry

# Install from default backend
mise install [email protected]
mise install [email protected]
mise install [email protected]

# Install with specific backend
mise install cargo:ripgrep        # From Rust crates
mise install github: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

```bash
# 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 [email protected]   # 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 github: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

```bash
# 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

```bash
# Pin exact version
mise use --pin [email protected]        # 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

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

# Exact - locks to specific version
mise use --pin [email protected]        # 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

```toml
[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
"github:sharkdp/fd" = "latest"       # GitHub releases
"npm:typescript" = "latest"          # Requires node installed
"github:nushell/nushell" = "latest"  # Nushell (structured shell)

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

### GitHub Backend

The **github** backend installs tools directly from GitHub release assets without requiring plugins. It is built into mise, works cross-platform including Windows, and adds provenance verification and download progress over the older ubi backend.

Note: The `ubi:` prefix is deprecated (per upstream mise docs); migrate any existing `ubi:owner/repo` entries to `github:owner/repo`.

#### Basic GitHub Backend Usage

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

# Specific version
mise use -g github:goreleaser/[email protected]

# In .mise.toml
[tools]
"github:goreleaser/goreleaser" = "latest"
"github:sharkdp/fd" = "10.0.0"
```

#### GitHub Backend Advanced Options

Configu