Install Tool

Arguments

$ARGUMENTS

Instructions

1. Identify the Tool

Parse the arguments for tool names and optional versions. If no version is specified, default to

@latest

2. Check If Already Installed

mise which <tool> 2>/dev/null || command -v <tool> 2>/dev/null

If the tool is already available, report its location and version. Stop unless the user explicitly wants a different version.

3. Search the Mise Registry

mise search <tool>
mise registry <tool>

• mise search

  — fuzzy-searches the registry for matching tools

• mise registry <tool>

  — shows the full backend path (e.g.,

  core:node

  ,

  aqua:jqlang/jq

  )

If no results, check alternate names or ask the user.

4. Choose Scope

CRITICAL: Global installs must happen in dotfiles

Before proceeding, determine if this is a global install:

• Arguments include

  --global

  or

  -g

• User explicitly asks for global install
• Tool is general-purpose (jq, ripgrep, etc.) and no local

  mise.toml

  exists

If global install is requested:

1. Check if we're in the chezmoi source directory:

chezmoi_source=$(chezmoi source-path 2>/dev/null)
current_dir=$(pwd)
# Check if current directory is within chezmoi source directory

2. If NOT in dotfiles (current dir not within

   chezmoi source-path

   ):
   • REFUSE the install
   • Tell the user: "Global tool installs must be done from your dotfiles repository to ensure they're tracked and reproducible. Please run

     chezmoi cd

     first, then run

     /install-tool

     again."
   • Stop execution

3. If in dotfiles:

   • Proceed with

     mise use --global

   • This will update

     home/dot_config/mise/config.toml

     (the chezmoi source file)
   • Remind user to apply changes:

     chezmoi apply ~/.config/mise/config.toml

Decision tree for project-local installs:

• Inside a project directory with

  mise.toml

  → project-local (default)
• No

  mise.toml

  exists → create one with

  mise use <tool>@<version>

5. Preview the Install

Always dry-run first:

mise use --dry-run <tool>@<version>

Report what will be installed and where the config will be written.

6. Execute

# Project-local (default)
mise use <tool>@<version>

# Global (only from within dotfiles)
mise use --global <tool>@<version>
# Then apply via chezmoi:
chezmoi apply ~/.config/mise/config.toml

# Pinned exact version (project-local)
mise use --pin <tool>@<version>

After global install, remind the user that the tool is now configured in their dotfiles and will be available everywhere after chezmoi apply.

7. Verify

mise which <tool>
<tool> --version  # or equivalent

Confirm the tool is available and report the installed version.

When Mise Cannot Provide the Tool

If

mise search

mise registry

1. Stop and tell the user — do not fall back to brew/apt/npm/pipx
2. Suggest alternatives:
   • Check if it's available via a different name
   • Use

     ubi

     backend:

     mise use ubi:owner/repo

   • Use

     aqua

     backend:

     mise use aqua:owner/repo

   • Use language-specific backend (see reference below)
3. If mise truly cannot provide it, ask the user for approval before using any other installer

Mise Discovery Subcommands

mise search <name>

mise registry <name>

mise registry --backend <be>

mise ls-remote <tool>

mise ls-remote <tool>@<prefix>

node@20

mise tool <name>

mise ls

mise backends ls

Mise Backends Reference

core:

mise use node@22

aqua:

mise use aqua:jqlang/jq

asdf:

mise use asdf:mise-plugins/mise-poetry

cargo:

mise use cargo:ripgrep

go:

mise use go:golang.org/x/tools/gopls

npm:

mise use npm:prettier

pipx:

mise use pipx:black

gem:

mise use gem:rubocop

ubi:

mise use ubi:BurntSushi/ripgrep

vfox:

mise use vfox:version-fox/vfox-node

conda:

mise use conda:scipy

dotnet:

mise use dotnet:fantomas

spm:

mise use spm:nicklockwood/SwiftFormat

http:

mise use http:https://example.com/tool.tar.gz

Backend Selection Guide

1. Check

   mise search

   first — most tools have a default backend
2. Core for major languages (node, python, ruby, go, java, etc.)
3. Aqua for most CLI tools distributed as GitHub releases
4. npm/pipx/cargo/go/gem for language-ecosystem packages
5. ubi as a fallback for any GitHub release not in aqua

Examples

/install-tool jq                      → search, preview, install jq
/install-tool node@22                 → install Node.js 22.x
/install-tool --global ripgrep        → install ripgrep globally
/install-tool terraform jq go         → install multiple tools
/install-tool cargo:stylua            → install via cargo backend
/install-tool ubi:BurntSushi/ripgrep  → install via ubi backend