Configure Mise

---
created: 2026-06-24
modified: 2026-10-05
reviewed: 2026-06-24
description: "mise runtime/tool version manager - mise.toml, backends (pipx/aqua/npm/cargo/go), tasks, env, lockfile. Use when setting up, pinning runtimes/CLI tools, or migrating from asdf/nvm/pyenv/brew/Make."
allowed-tools: Glob, Grep, Read, Write, Edit, Bash, AskUserQuestion, TodoWrite, WebSearch, WebFetch
args: "[--check-only] [--fix] [--global] [--migrate <asdf|nvm|pyenv|brew|makefile>]"
argument-hint: "[--check-only] [--fix] [--global] [--migrate <source>]"
name: configure-mise
---

# /configure:mise

Set up and audit [mise](https://mise.jdx.dev/) as the unified manager for language runtimes, CLI tools, environment variables, and project tasks. mise replaces asdf/nvm/pyenv (runtimes), `cargo install`/`brew install` (CLI binaries), and Make/just (tasks) behind one `mise.toml`.

## When to Use This Skill

| Use this skill when... | Use another approach when... |
|------------------------|------------------------------|
| Setting up `mise.toml` to pin a project's runtimes and CLI tools | Installing one tool ad-hoc — run `mise use <tool>@<ver>` directly |
| Picking the right backend for a tool (core / `pipx:` / `aqua:` / `npm:` / `cargo:` / `go:`) | The project only needs Python/JS *libraries* — use `/configure:package-management` (uv/bun) |
| Migrating from `.tool-versions`/asdf, `.nvmrc`, `.python-version`, Homebrew, or a Makefile | Defining build/test recipes only, no version management — use `/configure:justfile` or `/configure:makefile` |
| Adding `[tasks]`, `[env]`, secret loading, or a `mise.lock` for reproducible installs | Running a specific runtime version once — `mise exec <tool>@<ver> -- <cmd>` (see global rule `dependency-management`) |
| Auditing an existing mise setup for pinning, lockfile, trust, and backend correctness | Configuring CI runtime install — that consumes the `mise.toml` this skill produces (`jdx/mise-action`) |

## Context

- Project root: !`pwd`
- mise config (project): !`find . -maxdepth 2 \( -name 'mise.toml' -o -name '.mise.toml' -o -path './.config/mise.toml' -o -name 'mise.local.toml' \)`
- Lockfile: !`find . -maxdepth 1 -name 'mise.lock'`
- Legacy version files: !`find . -maxdepth 2 \( -name '.tool-versions' -o -name '.nvmrc' -o -name '.python-version' -o -name '.ruby-version' -o -name '.go-version' \)`
- Things mise can absorb: !`find . -maxdepth 1 \( -name 'Makefile' -o -name 'justfile' -o -name 'Brewfile' \)`

## Parameters

Parse from command arguments:

- `--check-only`: Audit and report; make no changes (CI/review mode).
- `--fix`: Apply the recommended config without prompting for each step.
- `--global`: Target the **global** config (`~/.config/mise/config.toml`) instead of a project `mise.toml`.
- `--migrate <source>`: Convert an existing setup into `mise.toml`. Sources: `asdf` (`.tool-versions`), `nvm` (`.nvmrc`), `pyenv` (`.python-version`), `brew` (Brewfile CLI tools), `makefile` (targets → `[tasks]`).

## Backend Selection (the core decision)

mise installs every tool through a *backend*. Picking the right one mirrors the user's tool-install priority (`dependency-management` rule): **mise first, with the most secure/fastest backend**.

Full backend table (syntax and rationale per tool kind): [references/backends.md](references/backends.md) — read it in Step 3.

Rule of thumb: **runtime → core; Python CLI → `pipx:`; everything else → `aqua:` first**, falling back to `npm:`/`cargo:`/`go:`/`github:` only when the aqua registry lacks the tool. Verify aqua availability at <https://github.com/aquaproj/aqua-registry>.

## Execution

### Step 1: Detect current state

From Context, classify the repo:

- **No mise, has legacy version files** (`.tool-versions`, `.nvmrc`, `.python-version`) → migration candidate.
- **No mise, has Makefile/Brewfile** → task/tool migration candidate.
- **Has `mise.toml`** → audit mode (Step 5).
- **Greenfield** → fresh `mise.toml`.

Detect which runtimes the project already implies: `pyproject.toml`/`.python-version` → Python; `package.json`/`.nvmrc` → Node; `go.mod` → Go; `Cargo.toml` → Rust.

### Step 2: Choose config target and naming

| Target | File | Committed? |
|--------|------|-----------|
| Project (default) | `mise.toml` at repo root | yes — pins the team to the same versions |
| Project, local overrides | `mise.local.toml` | no — add to `.gitignore` |
| Global (`--global`) | `~/.config/mise/config.toml` | n/a (dotfiles) |

Prefer the modern `mise.toml` name over legacy `.mise.toml`. Use `mise.local.toml` for machine-specific or secret-bearing overrides and ensure it is gitignored.

### Step 3: Build the `[tools]` block

Pin runtimes the project needs, then add CLI tools by backend (table above). Pin **as loosely as safe**: `python = "3.13"` (allow patch upgrades) for libraries; exact pins (`opentofu = "1.11.2"`) for tools where reproducibility matters. Detect latest stable versions with WebSearch/`mise ls-remote <tool>` before writing.

Minimal example:

```toml
[tools]
python = "3.13"
node = "lts"
"pipx:ruff" = "latest"
"pipx:pre-commit" = "latest"
"aqua:jqlang/jq" = "latest"
"aqua:cli/cli" = "latest"   # gh
```

### Step 4: Add `[env]`, `[tasks]`, `[settings]` as needed

- **`[env]`** — project env vars and PATH; load secrets from a gitignored file with `_.file = ".env.local"` (never inline secrets). See REFERENCE.md.
- **`[tasks]`** — migrate Makefile/just recipes here so `mise run <task>` replaces `make <target>`. Supports `depends`, `alias`, multi-line `run`. See REFERENCE.md for the full grammar.
- **`[settings]`** — set `pipx.uvx = true` whenever any `pipx:` tool is present (works around `jdx/mise#7477`); `experimental = true` for newer backends; `legacy_version_file = true` to keep honoring `.tool-versions`/`.nvmrc` during migration.

### Step 5: Audit (always; the whole job when `--check-only`)

Report a compliance table using the template in [references/audit-report.md](references/audit-report.md).

Checks: every runtime pinned; CLI tools prefer `aqua:` over `cargo:`/source builds; `pipx.uvx = true` present if any `pipx:` tool; `mise.lock` committed; `mise.local.toml` gitignored if present; config trusted (`mise trust`). If `--check-only`, stop here.

### Step 6: Apply (with `--fix` or on confirmation)

1. Write/patch the target config (Step 2 file).
2. `mise trust` the config (required before mise will use a new/edited file).
3. `mise install` to materialize tools.
4. `mise lock` to generate/refresh `mise.lock`, then track it (`git add mise.lock`).
5. If `mise.local.toml` exists, ensure `.gitignore` covers it.
6. `mise doctor` to verify the setup is healthy.

### Step 7: Migrations (`--migrate <source>`)

Per-source actions (`asdf`, `nvm`, `pyenv`, `brew`, `makefile`): [references/migrations.md](references/migrations.md) — read the row for the requested source.

Always verify with `mise install && mise doctor` before deleting the source file. See [REFERENCE.md](REFERENCE.md) for per-source mapping tables and worked examples.

### Step 8: CI integration (mention, don't duplicate)

A committed `mise.toml` + `mise.lock` is consumed in CI by `jdx/mise-action` (`mise install` then `mise run <task>`), giving local↔CI parity (the `local-ci-parity` rule). Point the user to `/configure:ci-workflows` rather than writing the workflow here.

## Agentic Optimizations

| Context | Command |
|---------|---------|
| Audit only | `/configure:mise --check-only` |
| Auto-configure | `/configure:mise --fix` |
| List installed tools (JSON) | `mise ls --json` |
| Show active versions | `mise current` |
| Available versions of a tool | `mise ls-remote <tool>` |
| Show outdated | `mise outdated` |
| Diagnose | `mise doctor` |
| Generate lockfile | `mise lock` |

## Flags

| Flag | Description |
|------|-------------|
| `--check-only` | Report status without modifying files |
| `--fix` | Apply the recommended config without per-step prompts |
| `--global` | Target `~/.config/mise/config.toml` instead of project `mise.toml` |
| `--migrate <source>` | Convert `asdf`/`nvm`/`pyenv`/`brew`/`makefile` into `mise.toml` |

## Examples

```bash
# Audit an existing setup
/configure:mise --check-only

# Set up mise.toml for the current project
/configure:mise

# Auto-configure, no prompts
/configure:mise --fix

# Migrate an asdf project
/configure:mise --migrate asdf

# Convert Makefile targets into mise tasks
/configure:mise --migrate makefile
```

## Error Handling

Fixes for mise-not-installed, untrusted config, `pipx:`/aqua resolution failures, tools that keep coming back, and node ≥26 `libatomic` on minimal Linux: [references/troubleshooting.md](references/troubleshooting.md) — read it when an install, trust, or resolve step fails.

## See Also

- `/configure:package-management` — uv/bun for Python/JS **libraries** (mise installs the runtimes; uv/bun manage deps)
- `/configure:justfile`, `/configure:makefile` — task runners mise's `[tasks]` can replace
- `/configure:ci-workflows` — CI that consumes `mise.toml` via `jdx/mise-action`
- Global rule: `dependency-management` (tool-install priority, `mise exec` vs `mise use`)
- [REFERENCE.md](REFERENCE.md) — full `[tasks]`/`[env]`/`[settings]` grammar, backend cheat-sheet, migration mapping tables
- **mise docs**: <https://mise.jdx.dev/> · **aqua registry**: <https://github.com/aquaproj/aqua-registry>