jdx · Oct 5, 2026 · Oct 5, 2026 · Oct 5, 2026 · Oct 5, 2026 · Oct 5, 2026
diff --git a/docs/.vitepress/cli-reference.ts b/docs/.vitepress/cli-reference.ts
@@ -29,6 +29,7 @@ const guides: Record<string, [string, string]> = {
   set: ["Environment variables", "/environments/"],
   unset: ["Environment variables", "/environments/"],
   exec: ["Running tools", "/dev-tools/"],
+  installs: ["Install layout", "/dev-tools/install-layout.html"],
   backends: ["Choosing backends", "/dev-tools/backends/"],
   config: ["Configuration", "/configuration.html"],
   edit: ["Configuration", "/configuration.html"],
@@ -145,7 +146,7 @@ const guides: Record<string, [string, string]> = {
 const categories = [
   [
     "Install and inspect tools",
-    "use install install-into uninstall unuse upgrade outdated lock latest ls ls-remote tool where which bin-paths registry search backends link sync prune reshim tool-stub packslip",
+    "use install install-into installs uninstall unuse upgrade outdated lock latest ls ls-remote tool where which bin-paths registry search backends link sync prune reshim tool-stub packslip",
   ],
   [
     "Shell and environment",

diff --git a/docs/.vitepress/cli_commands.ts b/docs/.vitepress/cli_commands.ts
@@ -697,6 +697,17 @@ export const commands: { [key: string]: Command } = {
   "install-into": {
     hide: false,
   },
+  installs: {
+    hide: false,
+    subcommands: {
+      ls: {
+        hide: false,
+      },
+      select: {
+        hide: false,
+      },
+    },
+  },
   latest: {
     hide: false,
   },

diff --git a/docs/cli/index.md b/docs/cli/index.md
@@ -65,6 +65,7 @@ Choose a command family below. Its page lists the available subcommands.
 - [`mise use`](/cli/use.html) — Install a tool and add it to configuration
 - [`mise install`](/cli/install.html) — Install a tool version
 - [`mise install-into`](/cli/install-into.html) — Install a tool version to a specific path
+- [`mise installs`](/cli/installs.html) — [experimental] Inspect and choose installations of the identity install layout
 - [`mise uninstall`](/cli/uninstall.html) — Remove installed tool versions
 - [`mise unuse`](/cli/unuse.html) — Remove tool requests from configuration and prune unused installations
 - [`mise upgrade`](/cli/upgrade.html) — Upgrade outdated tools

diff --git a/docs/cli/installs.md b/docs/cli/installs.md
@@ -0,0 +1,34 @@
+---
+description: "[experimental] Inspect and choose installations of the identity install layout"
+---
+
+<!-- @generated by usage-cli from usage spec -->
+# `mise installs`
+
+- **Usage:** `mise installs [SUBCOMMAND]`
+- **Effect:** read-only
+- **Source code:** [`src/cli/installs/mod.rs`](https://github.com/jdx/mise/blob/main/src/cli/installs/mod.rs)
+
+[experimental] Inspect and choose installations of the identity install layout
+
+With `install_layout = "identity"`, each installation lives in its own
+`<label>-<hash>` directory, and several installations of one version can
+exist side by side (different options, platforms, pinned artifacts, or a
+refreshed copy). These commands list them and choose which one requests
+without a lockfile use.
+
+## Flags
+- **`-h --help`** — Print help
+
+## Subcommands
+
+- [`mise installs ls [-J --json] [--no-header] [TOOL]…`](/cli/installs/ls.html)
+- [`mise installs select <INSTALLATION>`](/cli/installs/select.html)
+
+<!-- generated reference navigation -->
+
+## Related documentation
+
+- [Install layout](/dev-tools/install-layout.html).
+- [All commands](/cli/).
+- [Global flags and argument syntax](/cli/#global-flags).
diff --git a/docs/cli/installs/ls.md b/docs/cli/installs/ls.md
@@ -0,0 +1,49 @@
+---
+description: "List the installations of the identity install layout"
+---
+
+<!-- @generated by usage-cli from usage spec -->
+# `mise installs ls`
+
+- **Usage:** `mise installs ls [-J --json] [--no-header] [TOOL]…`
+- **Aliases:** `list`
+- **Effect:** read-only
+- **Source code:** [`src/cli/installs/ls.rs`](https://github.com/jdx/mise/blob/main/src/cli/installs/ls.rs)
+
+List the installations of the identity install layout
+
+Every installation is listed separately, so variants of one version (made
+with different options, or pinned to different artifacts by lockfiles) can
+be told apart. The status column says which installation requests without
+a lockfile use (`selected`), which a lockfile adopted (`pinned`), and which
+live in a read-only shared installs directory (`shared`).
+
+## Arguments
+- **`[TOOL]…`** — Only show the installations of these tools
+
+## Flags
+- **`-J --json`** — Output in JSON format
+- **`--no-header`** — Don't display headers
+- **`-h --help`** — Print help
+
+## Examples
+
+Every installation in the identity layout
+
+```
+mise installs ls
+```
+
+The installations of node, as JSON
+
+```
+mise installs ls node --json
+```
+
+<!-- generated reference navigation -->
+
+## Related documentation
+
+- [Install layout](/dev-tools/install-layout.html).
+- [`mise installs [SUBCOMMAND]`](/cli/installs.html).
+- [Global flags and argument syntax](/cli/#global-flags).
diff --git a/docs/cli/installs/select.md b/docs/cli/installs/select.md
@@ -0,0 +1,46 @@
+---
+description: "Choose the installation that requests without a lockfile use"
+---
+
+<!-- @generated by usage-cli from usage spec -->
+# `mise installs select`
+
+- **Usage:** `mise installs select <INSTALLATION>`
+- **Effect:** modifies state
+- **Source code:** [`src/cli/installs/select.rs`](https://github.com/jdx/mise/blob/main/src/cli/installs/select.rs)
+
+Choose the installation that requests without a lockfile use
+
+Several installations can answer the same request: a refresh that could not
+replace a lockfile's installation in place, or installations made for
+different lockfiles. Requests without a lockfile entry use the one selected
+for their tool, version, platform and options, and when none is selected and
+several match, mise stops and asks for this command.
+
+The selection is shared by every project on this machine that makes the same
+request without a lockfile. Projects whose lockfile pins an artifact keep the
+installation of that artifact. The version link (`installs/<tool>/<version>`)
+is pointed at the selected installation.
+
+## Arguments
+- **`<INSTALLATION>`** — The installation to select: its directory name, or its path
+
+## Flags
+- **`-h --help`** — Print help
+
+## Examples
+
+Find jq's installations, then choose one
+
+```
+mise installs ls jq
+mise installs select jq-hm3qa4vb
+```
+
+<!-- generated reference navigation -->
+
+## Related documentation
+
+- [Install layout](/dev-tools/install-layout.html).
+- [`mise installs [SUBCOMMAND]`](/cli/installs.html).
+- [Global flags and argument syntax](/cli/#global-flags).
diff --git a/docs/dev-tools/install-layout.md b/docs/dev-tools/install-layout.md
@@ -273,6 +273,54 @@ one project does not retarget what another project's unlocked request selects.
 Unlocked selections are local to your machine. To carry a particular choice to
 other machines or teammates, commit a lockfile.
 
+## Choosing an installation: `mise installs`
+
+Several installations can answer one unlocked request: a forced refresh that
+could not replace a lockfile's installation in place, or installations that
+lockfiles in other projects made. `mise installs ls` lists every installation
+and says which one each request uses:
+
+```sh
+mise installs ls jq
+# Installation  Tool  Version  Platform   Status
+# jq-hm3qa4vb   jq    1.7.1    linux-x64  selected
+# jq-ezjqmxa4   jq    1.7.1    linux-x64  pinned
+```
+
+`selected` is the installation requests without a lockfile use, `pinned` means a
+lockfile adopted it, and `shared` means it is in a read-only shared installs
+directory. Add `--json` for the full identity, including options and the
+artifact checksum.
+
+`mise installs select` makes another installation the selected one, and points
+the version link (`installs/jq/1.7.1`) at it:
+
+```sh
+mise installs select jq-ezjqmxa4
+```
+
+The selection applies to every project on the machine that asks for the same
+tool, version, platform and options without a lockfile. Projects whose lockfile
+pins an artifact keep that artifact's installation. To select an installation in
+a shared installs directory, pass its path; the selection is kept in your own
+installs directory, and nothing is written to the shared one.
+
+**When nothing is selected.** The first unlocked install of a request selects
+the installation it made. If the selection is lost (the catalog was rebuilt from
+receipts, for example), or the request was only ever installed by lockfiles,
+mise looks at the installations that answer it. With exactly one, mise uses and
+selects it. With several, mise stops instead of guessing, and lists them:
+
+```text
+mise ERROR jq@1.7.1 matches several installations and none is selected:
+  jq-hm3qa4vb
+  jq-ezjqmxa4 (a lockfile pins it)
+Choose one with `mise installs select <dir>`, or install a fresh one with `mise install --force jq@1.7.1`
+```
+
+If the selected installation has since been pruned, installing restores it in
+the same directory rather than choosing another one.
+
 ## Pruning and uninstalling
 
 Both work on one installation directory at a time.
@@ -283,7 +331,9 @@ Both work on one installation directory at a time.
   the install store that has neither a receipt nor a reservation in the
   catalog. Removing one variant leaves the others in place.
 - Removing an installation keeps its catalog record, so installing the same
-  identity again lands in the same directory.
+  identity again lands in the same directory. `mise uninstall` also forgets the
+  selection that named it, so the requests it answered choose again; a pruned
+  installation keeps its selection and is restored in place.
 - `mise prune` keeps an installation while a tracked config needs it. An unlocked
   request needs the installation it selects. A tracked lockfile entry needs the
   installations of its backend and version, narrowed to the pinned artifact when

diff --git a/docs/public/llms.txt b/docs/public/llms.txt
@@ -349,6 +349,9 @@
 - [mise implode](https://mise.jdx.dev/cli/implode.html): Remove the mise CLI and all related data
 - [mise install](https://mise.jdx.dev/cli/install.html): Install a tool version
 - [mise install-into](https://mise.jdx.dev/cli/install-into.html): Install a tool version to a specific path
+- [mise installs](https://mise.jdx.dev/cli/installs.html): [experimental] Inspect and choose installations of the identity install layout
+- [mise installs ls](https://mise.jdx.dev/cli/installs/ls.html): List the installations of the identity install layout
+- [mise installs select](https://mise.jdx.dev/cli/installs/select.html): Choose the installation that requests without a lockfile use
 - [mise latest](https://mise.jdx.dev/cli/latest.html): Resolve the latest matching version request for a tool
 - [mise link](https://mise.jdx.dev/cli/link.html): Symlink a tool version into mise
 - [mise lock](https://mise.jdx.dev/cli/lock.html): Create or refresh lockfile versions, checksums, and download URLs