CLI 插件（实验性）

Lima 支持类似 git、kubectl 和 docker 的插件式命令别名系统。当你运行一个不存在的 limactl 命令时，Lima 会自动在系统 PATH 和附加目录中查找名为 limactl-<command> 的外部程序。

插件发现

Lima 通过扫描以下位置中名为 limactl-<plugin-name> 的可执行文件来发现插件：

1. 包含 limactl 二进制文件的目录（包括符号链接支持）
2. 你 $PATH 环境变量中的所有目录
3. <PREFIX>/libexec/lima - 用于包管理器或发行版包安装的插件

插件发现会遵循符号链接，确保即使通过 Homebrew 安装 limactl 并指向符号链接，所有插件都能被正确发现。

插件信息

可用的插件会自动显示在：

• limactl --help - 在 “Available Plugins (Experimental)” 部分显示所有已发现的插件及其描述

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

• limactl info - 在 JSON 输出中包含插件信息

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

插件描述

Lima 使用 <limactl-desc> 格式从脚本注释中提取插件描述。在你的插件脚本中包含描述注释：

#!/bin/sh
# <limactl-desc>连接到在 Lima 实例中运行的 Docker 守护进程的 Docker 包装器</limactl-desc>
set -eu

# 你的脚本其余部分...

格式要求：

• 只有以 shebang（#!）开头的文件被视为脚本，其 <limactl-desc> 行将被提取为插件描述，即必须完全包含 <limactl-desc>描述文本</limactl-desc>
• 描述文本应简洁明了

限制：

• 二进制可执行文件无法提取描述，并将在帮助输出中不显示描述
• 如果在脚本中找不到 <limactl-desc> 注释，插件将在帮助输出中不显示描述

创建自定义别名

要创建自定义别名，请创建一个名为 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           # 等同于: limactl shell default
limactl sh myinstance bash   # 等同于: limactl shell myinstance bash
## 工作原理

1. 当你运行 `limactl <unknown-command>` 时，Lima 首先尝试查找内置命令
3. 如果找到，Lima 执行外部程序并将所有剩余参数传递给它
4. 如果未找到，Lima 显示标准的"未知命令"错误

这个系统允许你：
- 创建个人快捷方式和别名
- 在不修改核心应用程序的情况下扩展 Lima 的功能
- 通过分发脚本与团队共享自定义命令
- 在 `libexec/lima` 目录中的 Lima 发行版中打包插件

## 包安装

发行版包和包管理器可以在 `<PREFIX>/libexec/lima/` 中安装插件，其中 `<PREFIX>` 通常是 `/usr/local` 或 `/opt/homebrew`。这允许插件：
- 由包管理器管理
- 与用户的 `$PATH` 隔离
- 由 Lima 自动发现

## 实验性状态

**实验性功能**：CLI 插件系统目前是实验性的，可能在未来的版本中发生变化。插件 API 或发现机制可能会发生破坏性更改而无需通知。