### Mise Install Command Examples

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/02-backend-hooks.md

Examples demonstrating how to use the `mise install` command for various installation types, including standard packages, flake references, VSCode extensions, JetBrains plugins, and Neovim plugins.

```bash
# Standard package installation
mise install nix:hello@2.12.1

# Flake reference installation
mise install "nix:hello@github+nixos/nixpkgs"

# VSCode extension
mise install "nix:vscode+install=vscode-extensions.golang.go"

# JetBrains plugin
mise install "nix:jetbrains+install=jetbrains-plugins.x86_64-linux.idea-ultimate.2024.3.com.intellij.plugins.watcher"

# Neovim plugin
mise install "nix:neovim+install=vimPlugins.nvim-treesitter"
```

--------------------------------

### Neovim Plugin Installation Format

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/QUICKREF.md

Format for installing Neovim plugins using Mise Nix. Examples show the expected structure.

```text
neovim+install=vimPlugins.{plugin_name}

Examples:
  vimPlugins.nvim-treesitter
  vimPlugins.telescope-nvim
  vimPlugins.plenary-nvim
  vimPlugins.vim-surround
```

--------------------------------

### Copy Mode Example Directory Structure

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/08-configuration.md

Illustrates the directory structure created by Copy Mode, showing the full copy of Nix store output to the install path.

```text
~/.local/share/mise/installs/nix/hello/2.12/
  bin/
    hello
  share/
    ...
```

--------------------------------

### Symlink Mode Example Directory Structure

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/08-configuration.md

Illustrates the directory structure created by Symlink Mode, showing how install paths link to Nix store paths.

```text
~/.local/share/mise/installs/nix/hello/2.12/
  bin → /nix/store/abc123-hello/bin
  share → /nix/store/abc123-hello/share
```

--------------------------------

### Install a Tool Backend

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/QUICKREF.md

Entry point for installing a tool backend. Requires context with tool, version, and install path. Returns the installed version.

```lua
PLUGIN:BackendInstall(ctx)
  Parameters: ctx.tool, ctx.version, ctx.install_path
  Returns: { version = "X.Y.Z" }
```

--------------------------------

### List Versions for VSCode Extension

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/02-backend-hooks.md

Example command to list available versions for a VSCode extension, specifying the install format.

```bash
# List versions for VSCode extension
mise ls-remote "nix:vscode+install=vscode-extensions.golang.go"
```

--------------------------------

### Set Up Development with Live Reload

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/09-usage-patterns.md

Install development-specific tools like `watchexec` and Python using Mise. This setup is useful for projects that require watching for file changes and automatically rebuilding or restarting.

```bash
# Install development tools
mise install nix:watchexec
mise install nix:python

# Watch for changes and rebuild
mise exec nix:watchexec -- -e py './build.sh'
```

--------------------------------

### BackendInstall Return Value Example

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/02-backend-hooks.md

The BackendInstall function returns a table containing the actual installed version of the tool or package.

```lua
{
  version = "2.12.1"  -- Actual installed version
}
```

--------------------------------

### Local Development Configuration with mise.toml

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/09-usage-patterns.md

Example `mise.toml` file for local development setup. It specifies tool versions and environment variables, such as linking to a development profile for Nix.

```toml
[tools]
nix = "latest"
go = "1.21"
nodejs = "20"
python = "3.11"
vscode_go = "vscode+install=vscode-extensions.golang.go"

[env]
# Development profile for headers and build files
MISE_NIX_LINK_PROFILE = "dev"

# Allow unfree software if needed
# MISE_NIX_ALLOW_UNFREE = "true"
```

--------------------------------

### VSCode Extension Installation Format

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/QUICKREF.md

Format for installing VSCode extensions using Mise Nix. Examples show the expected structure.

```text
vscode+install=vscode-extensions.{publisher}.{extension}

Examples:
  vscode-extensions.golang.go
  vscode-extensions.ms-python.python
  vscode-extensions.rust-lang.rust-analyzer
```

--------------------------------

### Install from Nixhub

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/04-install-module.md

Installs a standard package from Nixhub, specifying the package name, version, and installation path.

```lua
-- Standard package installation (nixhub)
local result = install.from_nixhub("python3", "3.11.0", install_path)
print("Installed " .. result.version .. " at " .. result.store_path)
```

--------------------------------

### List and Install Versions of a Package

Source: https://github.com/jbadeau/mise-nix/blob/main/README.md

Demonstrates how to list available versions of a package and install a specific version using mise.

```sh
# List available versions
mise ls-remote nix:hello

# Install version
mise install nix:hello@2.12.1
```

--------------------------------

### Install Neovim Plugins with Mise

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/09-usage-patterns.md

Use `mise install` with the `nix:neovim+install=` prefix to install specific Neovim plugins. This command fetches and sets up the plugin for use with Neovim.

```bash
# Install nvim-treesitter
mise install "nix:neovim+install=vimPlugins.nvim-treesitter"

# Install telescope.nvim
mise install "nix:neovim+install=vimPlugins.telescope-nvim"

# Install plenary.nvim (common dependency)
mise install "nix:neovim+install=vimPlugins.plenary-nvim"

# Install other plugins
mise install "nix:neovim+install=vimPlugins.vim-surround"
mise install "nix:neovim+install=vimPlugins.vim-fugitive"
```

--------------------------------

### Get Install Mode

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/04-install-module.md

Retrieves the current installation mode, which can be 'symlink' or 'copy'. This is configured via the MISE_NIX_INSTALL_MODE environment variable.

```lua
local install = require("install")
local mode = install.get_install_mode()
-- Returns: "symlink" or "copy"
```

--------------------------------

### PLUGIN:BackendInstall

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/QUICKREF.md

Entry point for installing a backend tool. It takes a context object containing the tool name, version, and installation path, and returns the installed version.

```APIDOC
## PLUGIN:BackendInstall

### Description
Entry point for installing a backend tool. It takes a context object containing the tool name, version, and installation path, and returns the installed version.

### Parameters
#### Path Parameters
- **ctx** (object) - Required - Context object containing tool, version, and install_path.
  - **tool** (string) - Required - The name of the tool to install.
  - **version** (string) - Required - The version of the tool to install.
  - **install_path** (string) - Required - The path where the tool should be installed.

### Returns
- **version** (string) - The installed version of the tool.
```

--------------------------------

### BackendInstall Function Signature

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/02-backend-hooks.md

The main entry point for installation. It routes to the appropriate installation strategy based on the tool type. The context object provides details about the tool, version, and installation path.

```lua
function PLUGIN:BackendInstall(ctx)
  -- ctx.tool: string - Tool/package name
  -- ctx.version: string - Requested version
  -- ctx.install_path: string - Installation directory
  -- returns: { version = string }
end
```

--------------------------------

### Install Multi-Output Package

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/04-install-module.md

Installs a package that provides multiple outputs, such as a base package and its development files. Ensures the installation directory exists before proceeding.

```lua
-- Multi-output package
local install_path = "/path/to/install"
shell.mkdir_force(install_path)
local outputs = {"/nix/store/abc-foo", "/nix/store/def-foo-dev"}
install.multi_output_tool(outputs, install_path, "foo")
```

--------------------------------

### Install Standard Package

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/QUICKREF.md

Installs a standard package from Nixhub. Requires the 'install' module and a specified install path.

```lua
local install = require("install")
local result = install.from_nixhub("hello", "2.12.1", install_path)
-- Returns: { version="2.12.1", store_path="/nix/store/...", outputs={...} }
```

--------------------------------

### Plugin Routing Logic Diagram

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/QUICKREF.md

Illustrates the decision tree for determining the installation method of a plugin based on its type. This logic guides the backend installation process.

```text
BackendInstall determines type:
  └─ VSCode extension?     → vscode.install_extension()
  └─ JetBrains plugin?     → jetbrains.install_plugin_from_store()
  └─ Neovim plugin?        → neovim.install_plugin_from_store()
  └─ Flake reference?      → install.from_flake()
  └─ Standard package      → install.from_nixhub()
```

--------------------------------

### BackendInstall

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/02-backend-hooks.md

The main installation entry point for the mise-nix plugin. This function routes to the appropriate installation strategy based on the tool type provided in the context.

```APIDOC
## BackendInstall

### Description
Main installation entry point. Routes to appropriate installation strategy based on tool type.

### Method
Not Applicable (Lua function call)

### Endpoint
Not Applicable (Lua function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **ctx** (table) - Required - Context object from Mise
  - **ctx.tool** (string) - Required - Tool or package name to install
  - **ctx.version** (string) - Required - Requested version (empty string for latest)
  - **ctx.install_path** (string) - Required - Installation path managed by Mise

### Return Value
Returns table with installed version:
```lua
{
  version = "2.12.1"  // Actual installed version
}
```

### Behavior
The function routes to different installation strategies:

1. **VSCode Extensions** (`vscode+install=vscode-extensions.*`)
   - Detects via `vscode.is_extension(tool)`
   - Installs as VSIX package via VSCode CLI
   - Skips installation in CI environments

2. **JetBrains Plugins** (`jetbrains-plugins.*`)
   - Detects via `jetbrains.is_plugin(tool)`
   - Builds from nix-jetbrains-plugins flake
   - Installs to IDE-specific plugin directory

3. **Neovim Plugins** (`neovim+install=vimPlugins.*`)
   - Detects via `neovim.is_plugin(tool)`
   - Builds from nixpkgs vimPlugins
   - Symlinks to `~/.local/share/nvim/site/pack/nix/start/`

4. **Flake References** (direct `github:*`, `gitlab:*`, `git+*`)
   - Detects via `flake.is_reference(tool)` or `flake.is_reference(version)`
   - Builds and installs via `install.from_flake()`

5. **Standard Packages** (default)
   - Regular package names like `hello`, `python3`
   - Installs via `install.from_nixhub()`
   - Fetches from nixhub.io pre-built binaries

### Error Handling
- Throws error if Nix is not available (checked via `platform.check_nix_available()`)
- Throws error if package not found or build fails
- Invalid JetBrains plugin format raises error
- Returns success/failure via exception handling

### Request Example
```bash
# Standard package installation
mise install nix:hello@2.12.1

# Flake reference installation
mise install "nix:hello@github+nixos/nixpkgs"

# VSCode extension
mise install "nix:vscode+install=vscode-extensions.golang.go"

# JetBrains plugin
mise install "nix:jetbrains+install=jetbrains-plugins.x86_64-linux.idea-ultimate.2024.3.com.intellij.plugins.watcher"

# Neovim plugin
mise install "nix:neovim+install=vimPlugins.nvim-treesitter"
```
```

--------------------------------

### Install Standard Tool

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/04-install-module.md

Installs a standard package by either symlinking or copying from the Nix store. The behavior depends on the active installation mode (symlink or copy).

```lua
local install = require("install")
install.standard_tool("/nix/store/abc123-hello", "/home/user/.local/share/mise/installs/nix/hello/2.12", "hello")
```

--------------------------------

### Install from Nixhub

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/04-install-module.md

Installs a package from nixhub.io, resolving the version, building the flake, and routing to the appropriate installer (VSCode, JetBrains, or standard).

```lua
local install = require("install")
local result = install.from_nixhub("hello", "2.12.1", "/home/user/.local/share/mise/installs/nix/hello/2.12.1")
-- Returns: { version = "2.12.1", store_path = "/nix/store/...", outputs = {...} }
```

--------------------------------

### Install from Flake Reference

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/04-install-module.md

Installs a package from a Nix flake reference, suitable for standalone flake installations like home-manager.

```lua
-- Flake-based installation
local result = install.from_flake("github:nix-community/home-manager#standalone", "", install_path)
```

--------------------------------

### Install from Nix Flake

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/04-install-module.md

Installs a package from a Nix flake reference. Specify the flake reference, an optional version hint, and the desired installation path.

```lua
local install = require("install")
local result = install.from_flake("github:nixpkgs/nixpkgs#hello", "", "/home/user/.local/share/mise/installs/nix/hello/0a1b2c3")
-- Returns: { version = "0a1b2c3", store_path = "/nix/store/...", is_vscode = true }
```

--------------------------------

### GitLab CI Integration with Mise

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/09-usage-patterns.md

Example GitLab CI configuration showing how to set up Mise for dependency management. It includes installing Nix and Mise, caching, and running build commands.

```yaml
image: ubuntu:latest

variables:
  MISE_NIX_INSTALL_MODE: copy

cache:
  key: mise-nix-$CI_COMMIT_REF_SLUG
  paths:
    - ~/.local/share/mise/installs

stages:
  - build

build:
  before_script:
    - apt-get update && apt-get install -y curl nix-bin
    - curl -fsSL https://mise.jdx.dev/mise-latest-linux-x64 | 
      tee /usr/local/bin/mise && chmod +x /usr/local/bin/mise
    - mise install
  script:
    - mise exec -- make build
```

--------------------------------

### Install mise-nix Plugin

Source: https://github.com/jbadeau/mise-nix/blob/main/README.md

Installs the mise-nix plugin from a Git repository. Ensure Mise is installed and up to date.

```sh
mise plugin install nix https://github.com/jbadeau/mise-nix.git
```

--------------------------------

### GitHub Actions CI/CD Integration with Mise

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/09-usage-patterns.md

Example GitHub Actions workflow demonstrating how to integrate Mise for dependency installation and execution within a CI/CD pipeline. It includes caching for Mise installs.

```yaml
name: Build

env:
  MISE_NIX_INSTALL_MODE: copy

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: jdx/mise-action@v2
      
      - uses: actions/cache@v4
        with:
          path: ~/.local/share/mise/installs
          key: mise-nix-${{ hashFiles('mise.toml') }}
          restore-keys: mise-nix-
      
      - name: Install dependencies
        run: mise install
      
      - name: Run tests
        run: mise exec -- make test
```

--------------------------------

### Install Neovim plugin from Nix store

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/05-plugin-installers.md

Installs a Neovim plugin by creating a symlink in the Neovim pack directory to the specified Nix store path. Handles existing installations and CI skips.

```lua
local neovim = require("neovim")
neovim.install_plugin_from_store("/nix/store/abc123-nvim-treesitter", "neovim+install=vimPlugins.nvim-treesitter")
```

--------------------------------

### Install Neovim Plugins with Nix

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/05-plugin-installers.md

Installs Neovim plugins using Nix. Multiple plugins can be installed by running the command for each plugin.

```bash
# Neovim plugin installation
mise install "nix:neovim+install=vimPlugins.nvim-treesitter"
mise install "nix:neovim+install=vimPlugins.telescope-nvim"
```

--------------------------------

### from_nixhub(tool, requested_version, install_path)

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/04-install-module.md

Installs a standard package from nixhub.io, handling version resolution, flake building, and routing to the appropriate installer based on the package type (VSCode, JetBrains, or standard).

```APIDOC
## from_nixhub(tool, requested_version, install_path)

### Description
Installs a standard package from nixhub.io.

### Parameters
#### Path Parameters
- **tool** (string) - Yes - Package name
- **requested_version** (string) - Yes - Requested version (empty for latest)
- **install_path** (string) - Yes - Installation directory

### Returns
`table` - Information about the installed package.

#### Response Fields
- **version** (string) - Actual installed version
- **store_path** (string) - Primary Nix store path
- **outputs** (table) - Array of all build outputs
- **is_vscode** (boolean) - True if VSCode extension
- **is_jetbrains** (boolean) - True if JetBrains plugin

### Execution Flow
1. Resolves version via `require("version").resolve_version()`
2. Builds flake via `require("vsix").from_nixhub()`
3. Selects best output via `require("vsix").choose_best_output()`
4. Verifies build succeeded via `platform.verify_build()`
5. Routes to appropriate installer:
   - VSCode: `vscode.install_extension()`
   - JetBrains: `jetbrains.install_plugin_from_store()`
   - Standard: `standard_tool()` or `multi_output_tool()`
6. Caches dev environment via `nix_env.cache_dev_env()`

### Example
```lua
local install = require("install")
local result = install.from_nixhub("hello", "2.12.1", "/home/user/.local/share/mise/installs/nix/hello/2.12.1")
```
```

--------------------------------

### Using Development Profile for Installation

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/08-configuration.md

Set `MISE_NIX_LINK_PROFILE` to `dev` to install packages with development headers and pkg-config information. This is useful for libraries.

```bash
# Development profile (includes headers, pkg-config)
export MISE_NIX_LINK_PROFILE=dev
mise install nix:some-library
```

--------------------------------

### Install and Execute Polyglot Tools

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/09-usage-patterns.md

Install all tools defined in the configuration at once. Mise automatically sets up environment variables, making tools like Go, Python, and Node.js accessible for execution.

```bash
# Install all at once
mise install

# Each tool's env vars automatically set
mise exec -- bash -c 'go version && python --version && node --version'
```

--------------------------------

### standard_tool(nix_store_path, install_path, label)

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/04-install-module.md

Installs a standard package using either symlink or copy mode. It takes the Nix store path, the desired installation path, and a descriptive label as arguments.

```APIDOC
## standard_tool(nix_store_path, install_path, label)

### Description
Installs a standard package via symlink or copy.

### Parameters
#### Path Parameters
- **nix_store_path** (string) - Yes - Path in Nix store to install from
- **install_path** (string) - Yes - Destination path
- **label** (string) - Yes - Descriptive label for logging

### Behavior
**Symlink mode (default):**
1. Checks if symlink already exists and points to correct path (containerized optimization)
2. Removes existing target
3. Creates new symlink via `shell.symlink_force()`

**Copy mode:**
1. Removes existing install path
2. Copies entire Nix store path to install path
3. Used for CI environments where symlinks break after cache restore

### Example
```lua
local install = require("install")
install.standard_tool("/nix/store/abc123-hello", "/home/user/.local/share/mise/installs/nix/hello/2.12", "hello")
```
```

--------------------------------

### Install Neovim Plugins in CI

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/09-usage-patterns.md

Skip plugin installation in Continuous Integration environments by setting the `CI` environment variable to `1` before running `mise install`. This prevents unnecessary installations during CI runs.

```bash
# Installation skipped in CI
export CI=1
mise install "nix:neovim+install=vimPlugins.nvim-treesitter"
```

--------------------------------

### install_plugin_from_store(nix_store_path, tool_name)

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/05-plugin-installers.md

Installs a Neovim plugin by creating a symlink in the pack directory from a Nix store path.

```APIDOC
## install_plugin_from_store(nix_store_path, tool_name)

### Description
Installs Neovim plugin via symlink to pack directory.

### Parameters
#### Path Parameters
- **nix_store_path** (string) - Yes - Path in Nix store containing plugin
- **tool_name** (string) - Yes - Tool name for identification

### Returns
- **string** - Status: "installed", "already_installed", "skipped_in_ci"

### Installation flow
1. Validates tool name and extracts plugin name
2. Creates plugins directory if needed
3. Checks if plugin already symlinked correctly
4. Removes existing symlink/directory
5. Creates symlink: `${PLUGINS_DIR}/${plugin_name}` → `${NIX_STORE_PATH}`
6. In CI, skips symlink but logs plugin location

### Auto-loading
Plugins are automatically loaded by Neovim via `:h packages` mechanism (no init.lua configuration needed)
```

--------------------------------

### Verify Tool Installation and Environment

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/09-usage-patterns.md

Verify a tool installation by checking its directory and executing the tool. Also, inspect the environment variables like `PATH`, `JAVA_HOME`, and `GOROOT` to ensure they are correctly set.

```bash
# Check install directory
ls -la ~/.local/share/mise/installs/nix/hello/[version]/

# Test tool execution
mise exec nix:hello -- hello

# Check environment
mise exec nix:hello -- env | grep -E 'PATH|JAVA_HOME|GOROOT'
```

--------------------------------

### install_extension(nix_store_path, tool_name)

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/05-plugin-installers.md

Installs a VSCode extension from a specified Nix store path using its tool name for identification. This process involves creating a VSIX file and using the VSCode CLI for installation, with a CI-compatible behavior that skips actual installation.

```APIDOC
## install_extension(nix_store_path, tool_name)

### Description
Installs VSCode extension from Nix store path.

### Parameters
#### Path Parameters
- **nix_store_path** (string) - Yes - Path in Nix store containing extension
- **tool_name** (string) - Yes - Tool name for identification

### Returns
- **string** - Extension ID if successful, error thrown on failure

### Behavior:
1. Extracts extension ID from tool name
2. Locates extension directory in Nix store
3. Creates VSIX file in temporary directory
4. Installs VSIX via `code --install-extension`
5. Cleans up temporary directory

### CI Behavior:
Skips actual installation in CI environments (GITHUB_ACTIONS/CI env vars set), logs that extension is prepared

### Example
```lua
local vscode = require("vscode")
vscode.install_extension("/nix/store/abc123-vscode-go", "vscode-extensions.golang.go")
```
```

--------------------------------

### Create and Install VSCode Extension VSIX

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/05-plugin-installers.md

Creates a VSIX package from a given extension ID and Nix store path, then installs it. Returns success status, the VSIX path, and a status message.

```lua
local vscode = require("vscode")
local ok, vsix_path, status = vscode.create_and_install_vsix("golang.go", "/nix/store/...", "vscode-extensions.golang.go")
```

--------------------------------

### Install Build Tools with Mise

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/09-usage-patterns.md

Install necessary C build tools and libraries using Mise. These tools will be available within the `mise exec` environment.

```bash
# Install C build tools and libraries
mise install nix:gcc
mise install nix:gnumake
mise install nix:pkg-config
mise install nix:openssl@1.1

# All tools are available during mise exec
mise exec -- ./configure && make
```

--------------------------------

### Mise-Nix Installation Flow

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/00-index.md

Illustrates the process mise-nix follows to detect package types and install them, including specific logic for VSCode extensions, JetBrains plugins, Neovim plugins, and Flake references.

```text
BackendInstall(ctx)
├── Detect package type
│   ├── VSCode extension? → vscode.install_extension()
│   ├── JetBrains plugin? → jetbrains.install_plugin_from_store()
│   ├── Neovim plugin? → neovim.install_plugin_from_store()
│   └── Flake reference? → install.from_flake()
└── Standard package? → install.from_nixhub()
    ├── Resolve version via version.resolve_version()
    ├── Build via vsix.from_nixhub()
    ├── Select output via vsix.choose_best_output()
    ├── Verify build via platform.verify_build()
    ├── Install via standard_tool() or multi_output_tool()
    └── Cache env vars via nix_env.cache_dev_env()
```

--------------------------------

### List Versions for JetBrains Plugin

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/02-backend-hooks.md

Example command to list available versions for a JetBrains plugin, including platform and version details.

```bash
# List versions for JetBrains plugin
mise ls-remote "nix:jetbrains+install=jetbrains-plugins.x86_64-linux.idea-ultimate.2024.3.com.intellij.plugins.watcher"
```

--------------------------------

### from_flake

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/04-install-module.md

Installs a package from a Nix flake reference. It handles building the flake, selecting the best output, verifying the build, detecting the package type, and routing to the appropriate installer.

```APIDOC
## from_flake(flake_ref, version_hint, install_path)

### Description
Installs a package from a Nix flake reference. This function handles the entire process from building the flake to routing to the correct installer based on package type.

### Parameters
#### Path Parameters
- **flake_ref** (string) - Yes - Flake reference (github:, gitlab:, path:, etc.)
- **version_hint** (string) - No - Version hint for multi-version flakes
- **install_path** (string) - Yes - Installation directory

### Returns
`table` - Similar to `from_nixhub()`, containing installation details like version and store path.

### Example
```lua
local install = require("install")
local result = install.from_flake("github:nixos/nixpkgs#hello", "", "/home/user/.local/share/mise/installs/nix/hello/0a1b2c3")
-- Returns: { version = "0a1b2c3", store_path = "/nix/store/...", is_vscode = true }
```
```

--------------------------------

### PLUGIN:BackendExecEnv

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/QUICKREF.md

Sets up the environment for executing a backend tool. It takes a context object with installation details and returns environment variables.

```APIDOC
## PLUGIN:BackendExecEnv

### Description
Sets up the environment for executing a backend tool. It takes a context object with installation details and returns environment variables.

### Parameters
#### Path Parameters
- **ctx** (object) - Required - Context object containing installation path, tool, and version.
  - **install_path** (string) - Required - The installation path of the tool.
  - **tool** (string) - Required - The name of the tool.
  - **version** (string) - Required - The version of the tool.

### Returns
- **env_vars** (array of objects) - An array of environment variables, where each object has a 'key' and 'value' field.
```

--------------------------------

### Install Multi-Output Tool

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/04-install-module.md

Installs packages that have multiple outputs, such as runtime and development files. It links subpaths based on active link profiles like 'runtime' or 'dev'.

```lua
local install = require("install")
local outputs = {"/nix/store/abc123-foo", "/nix/store/def456-foo-dev"}
install.multi_output_tool(outputs, "/home/user/.local/share/mise/installs/nix/foo/1.0", "foo")
```

--------------------------------

### Install Nix Package from GitHub Flake (Standard Syntax)

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/09-usage-patterns.md

Installs a Nix package directly from a GitHub flake using standard Nix syntax. This allows leveraging Nixpkgs or other flake repositories for package management.

```bash
# Using standard Nix syntax
mise install "nix:hello@github:nixos/nixpkgs#hello"
```

--------------------------------

### Install Nix Package from Custom Git URL (HTTPS)

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/09-usage-patterns.md

Installs a Nix package from a flake hosted on a custom Git URL using HTTPS. This allows installation from any Git repository that supports flakes.

```bash
# HTTPS URL
mise install "nix:hello@https+github.com/nixos/nixpkgs.git#hello"
```

--------------------------------

### Install VSCode Extensions

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/09-usage-patterns.md

Installs specific VSCode extensions using their nixpkgs references. The process involves detecting the pattern, converting it to a nixpkgs reference, building from nixpkgs, creating a VSIX package, and installing via the VSCode CLI.

```bash
mise install "nix:vscode+install=vscode-extensions.golang.go"
mise install "nix:vscode+install=vscode-extensions.ms-python.python"
mise install "nix:vscode+install=vscode-extensions.rust-lang.rust-analyzer"
```

--------------------------------

### Install VSCode Extension from Nix Store

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/05-plugin-installers.md

Installs a VSCode extension by providing its path in the Nix store and its tool name. This function handles VSIX creation and installation via the VSCode CLI, with a special behavior for CI environments.

```lua
local vscode = require("vscode")
vscode.install_extension("/nix/store/abc123-vscode-go", "vscode-extensions.golang.go")
```

--------------------------------

### Use Copy Installation Mode for CI

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/QUICKREF.md

Set this environment variable to use the copy installation mode, suitable for CI environments.

```bash
export MISE_NIX_INSTALL_MODE=copy
```

--------------------------------

### JetBrains Plugin Installation Format

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/QUICKREF.md

Format for installing JetBrains plugins using Mise Nix. Includes system, IDE, version, and plugin ID.

```text
jetbrains-plugins.{system}.{ide}.{version}.{plugin_id}

System: x86_64-linux, aarch64-darwin, aarch64-linux, x86_64-darwin
IDE: idea-ultimate, idea-community, goland, webstorm, phpstorm, etc.
Version: IDE version (e.g., 2024.3)
Plugin ID: From JetBrains Marketplace (e.g., com.intellij.plugins.watcher)

Example:
  jetbrains-plugins.x86_64-linux.idea-ultimate.2024.3.com.intellij.plugins.watcher
```

--------------------------------

### Install Standard Nix Packages

Source: https://github.com/jbadeau/mise-nix/blob/main/README.md

Installs standard Nix packages using nixhub.io for pre-built versions. Supports latest, specific versions, and stable aliases.

```sh
# Latest version
mise install nix:hello

# Specific version
mise install nix:hello@2.12.1

# Version aliases
mise install nix:hello@stable
```

--------------------------------

### Install Neovim Plugins via Nix

Source: https://github.com/jbadeau/mise-nix/blob/main/README.md

Installs Neovim plugins from nixpkgs vimPlugins. Plugins are automatically symlinked and auto-loaded by Neovim. No init.lua configuration is needed.

```sh
# Install nvim-treesitter
mise install "nix:neovim+install=vimPlugins.nvim-treesitter"

# Install plenary.nvim (common dependency)
mise install "nix:neovim+install=vimPlugins.plenary-nvim"

# Install telescope.nvim
mise install "nix:neovim+install=vimPlugins.telescope-nvim"
```

--------------------------------

### Install Latest Nix Package

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/09-usage-patterns.md

Installs the latest available version of a Nix package and then executes it. This is useful for quickly trying out the newest features.

```bash
mise install nix:hello
mise exec nix:hello -- hello
```

--------------------------------

### Dockerfile for mise-nix Environment

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/08-configuration.md

This Dockerfile sets up a Docker image with mise and Nix installed, preparing an environment for building projects with mise-nix. It includes installing dependencies and copying project configuration.

```dockerfile
FROM ubuntu:latest

RUN apt-get update && apt-get install -y \
    nix-bin \
    curl

RUN curl https://mise.jdx.dev/mise-latest-linux-x64 -o /usr/local/bin/mise && \
    chmod +x /usr/local/bin/mise

WORKDIR /app
COPY mise.toml ./

ENV MISE_NIX_INSTALL_MODE=copy
RUN mise install

CMD ["/bin/bash"]
```

--------------------------------

### Install VSCode Extension with Nix

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/05-plugin-installers.md

Installs a VSCode extension using Nix. Set `MISE_NIX_ALLOW_UNFREE=true` if the extension is unfree.

```bash
# VSCode extension installation
export MISE_NIX_ALLOW_UNFREE=true  # If extension is unfree
mise install "nix:vscode+install=vscode-extensions.golang.go"
```

--------------------------------

### Install Package with Runtime Profile

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/09-usage-patterns.md

Install a package using its default runtime profile, which typically includes binaries, shared libraries, and man pages. This is the default behavior when `MISE_NIX_LINK_PROFILE` is not set.

```bash
# Install with runtime profile (default)
MISE_NIX_LINK_PROFILE=runtime mise install nix:boost
# Provides: bin/, share/, lib/
```

--------------------------------

### Install Unfree Nix Packages

Source: https://github.com/jbadeau/mise-nix/blob/main/README.md

Installs unfree Nix packages by setting the MISE_NIX_ALLOW_UNFREE environment variable to true. This automatically sets NIXPKGS_ALLOW_UNFREE.

```sh
# Using MISE_NIX env var (recommended - auto-sets NIXPKGS_ALLOW_UNFREE)
export MISE_NIX_ALLOW_UNFREE=true
mise install nix:discord

# Or using native Nix env var directly
export NIXPKGS_ALLOW_UNFREE=1
mise install nix:discord
```

--------------------------------

### Install JetBrains Plugin with Nix

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/05-plugin-installers.md

Installs a JetBrains plugin using Nix. Ensure you use the correct plugin identifier and platform-specific package.

```bash
# JetBrains plugin installation
mise install "nix:jetbrains+install=jetbrains-plugins.x86_64-linux.idea-ultimate.2024.3.com.intellij.plugins.watcher"
```

--------------------------------

### Install JetBrains Plugins via Nix

Source: https://github.com/jbadeau/mise-nix/blob/main/README.md

Installs JetBrains plugins from the nix-jetbrains-plugins repository. Ensure the system architecture and IDE version match the plugin. Restart IDE to activate.

```sh
# Install File Watchers plugin for IntelliJ IDEA Ultimate (Linux)
mise install "nix:jetbrains+install=jetbrains-plugins.x86_64-linux.idea-ultimate.2024.3.com.intellij.plugins.watcher"

# Install File Watchers plugin for IntelliJ IDEA Ultimate (macOS)
mise install "nix:jetbrains+install=jetbrains-plugins.aarch64-darwin.idea-ultimate.2024.3.com.intellij.plugins.watcher"

# Install GitToolBox for GoLand
mise install "nix:jetbrains+install=jetbrains-plugins.x86_64-linux.goland.2024.3.zielu.gittoolbox"

# Install Database Tools for WebStorm
mise install "nix:jetbrains+install=jetbrains-plugins.x86_64-linux.webstorm.2024.3.com.intellij.database"
```

--------------------------------

### Set Up Execution Environment

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/QUICKREF.md

Sets up the environment variables for executing a tool. Requires context with install path, tool, and version. Returns a list of environment variables.

```lua
PLUGIN:BackendExecEnv(ctx)
  Parameters: ctx.install_path, ctx.tool, ctx.version
  Returns: { env_vars = { {key="VAR", value="..."}, ... } }
```

--------------------------------

### Install Nix Package from Local Flake

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/09-usage-patterns.md

Installs a Nix package from a local flake directory. Requires enabling local flake access via an environment variable for security.

```bash
export MISE_NIX_ALLOW_LOCAL_FLAKES=true
mise install "nix:mytool@./my-flake"
mise install "nix:mytool@../shared-flake"
```

--------------------------------

### Install Nix Packages from Flake References

Source: https://github.com/jbadeau/mise-nix/blob/main/README.md

Installs Nix packages using various flake reference formats, including GitHub, GitLab, and direct Git URLs. Ensure flake references are correctly formatted.

```sh
# GitHub
mise install "nix:hello@github+nixos/nixpkgs"
mise install "nix:hello@nixos/nixpkgs#hello"

# GitLab
mise install "nix:mytool@gitlab+group/project"

# Git HTTPS URLs
mise install "nix:hello@https+github.com/nixos/nixpkgs.git#hello"

# Git SSH URLs
mise install "nix:mytool@ssh+git@github.com/owner/repo.git#default"
```

--------------------------------

### Install Nix Packages from Local Flakes

Source: https://github.com/jbadeau/mise-nix/blob/main/README.md

Installs Nix packages from a local flake reference. Requires setting the MISE_NIX_ALLOW_LOCAL_FLAKES environment variable to true.

```sh
export MISE_NIX_ALLOW_LOCAL_FLAKES=true
mise install "nix:mytool@./my-project"
```

--------------------------------

### List Versions for Standard Package

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/02-backend-hooks.md

Example command to list available versions for a standard package using the `mise ls-remote` command.

```bash
# List versions for standard package
mise ls-remote nix:hello
```

--------------------------------

### Install Nix Package from GitHub Flake (Mise Syntax)

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/09-usage-patterns.md

Installs a Nix package from a GitHub flake using Mise-compatible syntax, replacing colons with plus signs. This is an alternative way to reference flakes hosted on GitHub.

```bash
# Using Mise-compatible syntax (colon to plus)
mise install "nix:hello@github+nixos/nixpkgs#hello"
```

--------------------------------

### Link Subpaths from Multiple Outputs

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/07-utility-modules.md

Links specified subpaths from all provided Nix store outputs into a given installation path. It creates the install path if it doesn't exist and logs the total entries linked per subpath.

```lua
local output_join = require("output_join")
local linked = output_join.link_outputs(outputs, install_path)
```

--------------------------------

### Install Nix Package from GitHub Flake (Specific Branch)

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/09-usage-patterns.md

Installs a Nix package from a specific branch of a GitHub flake. This is useful for testing or using development versions of packages.

```bash
# With specific branch
mise install "nix:hello@github+nixos/nixpkgs/nixos-unstable#hello"
```

--------------------------------

### Mise-Nix Environment Setup Flow

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/00-index.md

Explains the logic for setting up the development environment, including checking cache, computing environment variables via `nix print-dev-env`, and fallback mechanisms.

```text
BackendExecEnv(ctx)
├── Try nix_env.for_context(ctx)
│   ├── Check cache at install_path/.nix-env.json
│   └── If missing, compute via nix print-dev-env
├── If success → return cached env vars
├── If fail and MISE_NIX_ENV_MODE=dev-env → error
└── Fallback → PATH only
```

--------------------------------

### Install Nix Package from Custom Git URL (SSH)

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/09-usage-patterns.md

Installs a Nix package from a flake hosted on a custom Git URL using SSH. This is useful for private repositories or when SSH authentication is preferred.

```bash
# SSH URL
mise install "nix:hello@ssh+git@github.com:nixos/nixpkgs.git#hello"
```

--------------------------------

### create_and_install_vsix(ext_id, nix_store_path, tool_name)

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/05-plugin-installers.md

Creates a VSIX package from extension files in the Nix store and then installs it. It returns a success status, the path to the created VSIX, and a status message.

```APIDOC
## create_and_install_vsix(ext_id, nix_store_path, tool_name)

### Description
Creates VSIX package and installs it.

### Parameters
#### Path Parameters
- **ext_id** (string) - Yes - Extension ID
- **nix_store_path** (string) - Yes - Path in Nix store
- **tool_name** (string) - Yes - Tool name for naming

### Returns
- **boolean, string, string** - (success, vsix_path, status)

### VSIX Structure:
- `[Content_Types].xml` - File type mappings
- `extension.vsixmanifest` - Extension metadata
- `extension/` - Extension files from Nix store

### Example
```lua
local vscode = require("vscode")
local ok, vsix_path, status = vscode.create_and_install_vsix("golang.go", "/nix/store/...", "vscode-extensions.golang.go")
```
```

--------------------------------

### Get IDE-specific JetBrains plugins directory

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/05-plugin-installers.md

Retrieves the platform-specific directory path where JetBrains IDE plugins are stored. This is essential for locating or managing plugin installations.

```lua
local jetbrains = require("jetbrains")
local dir = jetbrains.get_plugins_dir("idea-ultimate", "2024.3")
-- On Linux: "$HOME/.local/share/JetBrains/IntelliJIdea2024.3/plugins"
-- On macOS: "$HOME/Library/Application Support/JetBrains/IntelliJIdea2024.3/plugins"
```

--------------------------------

### Install JetBrains plugin from Nix store

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/05-plugin-installers.md

Installs a JetBrains plugin located in the Nix store to the appropriate IDE plugin directory. The function handles locating plugin files and copying them, with special behavior for CI environments.

```lua
local jetbrains = require("jetbrains")
jetbrains.install_plugin_from_store("/nix/store/abc123-idea-ultimate-plugin", "jetbrains-plugins.x86_64-linux.idea-ultimate.2024.3.com.intellij.plugins.watcher")
```

--------------------------------

### Enable Unfree Packages

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/QUICKREF.md

Set this environment variable to allow the installation of unfree packages.

```bash
export MISE_NIX_ALLOW_UNFREE=true
```

--------------------------------

### Allowing Unfree Packages

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/08-configuration.md

To install unfree packages, set the environment variable `MISE_NIX_ALLOW_UNFREE` to `true` or configure `allow-unfree = true` in `nix.conf`.

```shell
# Set: export MISE_NIX_ALLOW_UNFREE=true
# Or in nix.conf: allow-unfree = true
```

--------------------------------

### Install Package from Flake

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/QUICKREF.md

Installs a package from a specified flake. Requires the 'install' module and an install path.

```lua
local install = require("install")
local result = install.from_flake("github:nixos/nixpkgs#hello", "", install_path)
-- Returns: { version="...", store_path="/nix/store/...", outputs={...} }
```

--------------------------------

### Enable Debug Output for Installation

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/09-usage-patterns.md

Enable debug logging for Mise installations by setting the `MISE_DEBUG` environment variable. This is helpful for diagnosing issues during tool installation.

```bash
# Enable debug output
export MISE_DEBUG=1
mise install nix:hello

# Check what was cached
cat ~/.local/share/mise/installs/nix/hello/[version]/.nix-env.json
```

--------------------------------

### Install JetBrains Plugins

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/09-usage-patterns.md

Installs JetBrains plugins for various IDEs and systems. The format specifies the system, IDE, version, and plugin ID, allowing for precise installation of desired plugins.

```bash
# File Watchers plugin for IntelliJ IDEA (Linux)
mise install "nix:jetbrains+install=jetbrains-plugins.x86_64-linux.idea-ultimate.2024.3.com.intellij.plugins.watcher"

# File Watchers for IntelliJ (macOS)
mise install "nix:jetbrains+install=jetbrains-plugins.aarch64-darwin.idea-ultimate.2024.3.com.intellij.plugins.watcher"

# GitToolBox for GoLand
mise install "nix:jetbrains+install=jetbrains-plugins.x86_64-linux.goland.2024.3.zielu.gittoolbox"

# Database Tools for WebStorm
mise install "nix:jetbrains+install=jetbrains-plugins.x86_64-linux.webstorm.2024.3.com.intellij.database"
```

--------------------------------

### Install Nix Package Using Version Aliases

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/09-usage-patterns.md

Installs Nix packages using predefined aliases like 'stable' for the latest non-prerelease version or 'latest' for the most recent version. This simplifies installation when specific version numbers are not required.

```bash
mise install nix:hello@stable  # Latest non-prerelease
mise install nix:python@latest  # Explicit latest
```

--------------------------------

### Mise Exec Examples for BackendExecEnv Modes

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/02-backend-hooks.md

Demonstrates how to use `mise exec` with different `MISE_NIX_ENV_MODE` settings to control environment variable resolution for backend tools.

```bash
# Automatic env var caching and retrieval
mise exec nix:java -- java -version

# Force strict dev-env mode
export MISE_NIX_ENV_MODE=dev-env
mise exec nix:python -- python --version

# Path-only mode
export MISE_NIX_ENV_MODE=path-only
mise exec nix:node -- node -v
```

--------------------------------

### System Detection and Build Configuration

Source: https://github.com/jbadeau/mise-nix/blob/main/_autodocs/06-build-modules.md

Detects the system, retrieves Nixpkgs repository URL, and checks if impure mode is needed for building. Includes logic for using a build prefix if required.

```lua
-- Detect system and build appropriately
local platform = require("platform")
local system = platform.get_nix_system()
local nixpkgs_url = platform.get_nixpkgs_repo_url()

-- Build with impure flag if needed
if platform.needs_impure_mode() then
  local prefix = platform.get_nix_build_prefix()
  -- Use prefix in nix build command
end

-- Select best output
local vsix = require("vsix")
local outputs = {...}
local best = vsix.choose_best_output(outputs, "mypackage")
```

--------------------------------

### Install Insecure Nix Packages

Source: https://github.com/jbadeau/mise-nix/blob/main/README.md

Installs insecure Nix packages by setting the MISE_NIX_ALLOW_INSECURE environment variable to true. This automatically sets NIXPKGS_ALLOW_INSECURE.

```sh
# Using MISE_NIX env var (recommended - auto-sets NIXPKGS_ALLOW_INSECURE)
export MISE_NIX_ALLOW_INSECURE=true
mise install nix:some-package

# Or using native Nix env var directly
export NIXPKGS_ALLOW_INSECURE=1
mise install nix:some-package
```