CLI plugins (Experimental)

Lima supports a plugin-like command aliasing system similar to git, kubectl, and docker. When you run a limactl command that doesn’t exist, Lima will automatically look for an external program named limactl-<command> in your system’s PATH and additional directories.

Plugin Discovery

Lima discovers plugins by scanning for executables named limactl-<plugin-name> in the following locations:

1. Directory containing the limactl binary (including symlink support)
2. All directories in your $PATH environment variable
3. <PREFIX>/libexec/lima - For plugins installed by package managers or distribution packages

Plugin discovery respects symlinks, ensuring that even if limactl is installed via Homebrew and points to a symlink, all plugins are correctly discovered.

Plugin Information

Available plugins are automatically displayed in:

• limactl --help - Shows all discovered plugins with descriptions in an “Available Plugins (Experimental)” section

Available Plugins (Experimental):
  ps                  Sample limactl-ps alias that shows running instances
  sh

• limactl info - Includes plugin information in the JSON output

{
   "plugins": [
      {
         "name": "ps",
         "path": "/opt/homebrew/bin/limactl-ps"
      },
      {
         "name": "sh",
         "path": "/opt/homebrew/bin/limactl-sh"
      }
   ]
}

Plugin Descriptions

Lima extracts plugin descriptions from script comments using the <limactl-desc> format. Include a description comment in your plugin script:

#!/bin/sh
# <limactl-desc>Docker wrapper that connects to Docker daemon running in Lima instance</limactl-desc>
set -eu

# Rest of your script...

Format Requirements:

• Only files beginning with a shebang (#!) are treated as scripts, and their <limactl-desc> lines will be extracted as the plugin description i.e Must contain exactly <limactl-desc>Description text</limactl-desc>
• The description text should be concise and descriptive

Limitations:

• Binary executables cannot have descriptions extracted and will appear in the help output without a description
• If no <limactl-desc> comment is found in a script, the plugin will appear in the help output without a description

创建自定义别名

要创建自定义别名，请创建一个名为 limactl-<alias> 的可执行脚本并将其放置在你的 PATH 中的某个位置。

示例：为列出实例创建 ps 别名 {#example-creating-a-ps-alias-for-listing-instances}

1. 创建一个名为 limactl-ps 的脚本：

   #!/bin/sh
   # 以紧凑格式显示实例
   limactl list --format table "$@"
   

2. 使其可执行并放置在你的 PATH 中：

   chmod +x limactl-ps
   sudo mv limactl-ps /usr/local/bin/
   

3. 现在你可以使用它：

   limactl ps                    # 以表格格式显示实例
   limactl ps --quiet            # 仅显示实例名称
   

示例：创建 sh 别名 {#example-creating-an-sh-alias}

#!/bin/sh
# limactl-sh - 连接到实例 shell
limactl shell "$@"

创建此别名后：

limactl sh default           # Equivalent to: limactl shell default
limactl sh myinstance bash   # Equivalent to: limactl shell myinstance bash
## How It Works

1. When you run `limactl <unknown-command>`, Lima first tries to find a built-in command
3. If found, Lima executes the external program and passes all remaining arguments to it
4. If not found, Lima shows the standard "unknown command" error

This system allows you to:
- Create personal shortcuts and aliases
- Extend Lima's functionality without modifying the core application
- Share custom commands with your team by distributing scripts
- Package plugins with Lima distributions in the `libexec/lima` directory

## Package Installation

Distribution packages and package managers can install plugins in `<PREFIX>/libexec/lima/` where `<PREFIX>` is typically `/usr/local` or `/opt/homebrew`. This allows plugins to be:
- Managed by the package manager
- Isolated from user's `$PATH`
- Automatically discovered by Lima

## Experimental Status

**Experimental Feature**: The CLI plugin system is currently experimental and may change in future versions. Breaking changes to the plugin API or discovery mechanism may occur without notice.