Version: TOS 7

VMs CLI

简介

VMs CLI 是铁威马 VMs 虚拟化应用的命令行管理工具，提供与 Web 管理界面一致的查询与运维能力。CLI 通过本机 unix socket 与 VMs 服务通信，采用标准化的命令接口与 JSON 输出格式，可集成于脚本、自动化运维及二次开发工作流中。

主要特点

开箱即用：随 VMs 应用一同安装，无需额外安装
调用方式灵活：支持本地终端、远程 SSH、脚本、AI 工具等多种调用途径
交互与非交互双模式：既适合管理员日常维护，也适合脚本和自动化任务
JSON 输出支持：便于程序解析和自动化集成
本机通信：仅通过本机 unix socket 与 VMs 服务通信，不对外开放端口
危险操作二次确认：删除虚拟机、删除网络等操作默认要求确认

快速开始

# 在终端中执行（可通过本地终端、SSH、脚本、AI 工具等任意命令行途径）
vms --help

# 查看虚拟机列表
vms vm list

# 查看虚拟机详情
vms vm get <id>

# 以 JSON 格式输出（便于脚本解析）
vms vm list --json

vms vm list 输出示例：

NAME     GUEST ID                              STATUS    VCPU NUM  VRAM SIZE  IP
145      09fd98ee-4e2d-4c7a-a95c-8bacab80d322  shutdown  4         2097152    -
win10    9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1  shutdown  4         2097152    -
1454486  5a0391f2-c545-45eb-8eed-0a104972229b  shutdown  4         2097152    -
win101   32ee5a74-de8b-47a9-959d-1725c881ceab  shutdown  4         2097152    -

全局选项

以下选项适用于所有命令：

选项	简写	说明
`--help`	`-h`	显示命令帮助信息
`--version`	`-v`	显示版本号（可搭配 `--json` 输出结构化信息）
`--json`	-	输出 JSON 格式
`--yes`	`-y`	跳过危险操作的确认提示（非交互模式必须使用）
`--debug`	-	启用调试输出，显示详细执行过程
`--socket <path>`	-	VMs unix socket 路径，默认 `/var/api/VMs.sock`
`--timeout <duration>`	-	请求超时时间，默认 30s

版本信息示例

vms --version

vms CLI v1.0.058

vms --version --json

{
  "build": "20260911",
  "cli_version": "v1.0.058"
}

运行环境

VMs CLI 随 VMs 应用一同安装。应用启用时会把 CLI 链接到系统默认的 PATH 目录，登录 SSH 后可直接使用。

项目	说明
CLI 文件	`/Volume1/@apps/VMs/bin/vms`
命令路径	`/usr/local/sbin/vms`（已在系统 PATH 中）
通信方式	本机 unix socket，默认 `/var/api/VMs.sock`
适用对象	登录本机的管理员

注意事项：

CLI 用于管理本机虚拟机，不支持通过 CLI 远程管理其他设备。
后端始终返回 HTTP 200，命令是否成功以响应体中的 code 字段为准，CLI 会据此转换为退出码。
危险操作（删除虚拟机、删除网络、删除映像、删除存储空间）在交互模式下会请求确认，在非交互模式下必须显式传入 --yes。

命令汇总表

以下是所有 vms 命令的快速参考汇总：

父命令	子命令	功能说明	需确认	高风险
vms	--version	显示版本信息	否	否
vms vm	list	列出所有虚拟机	否	否
vms vm	get	查看指定虚拟机详情	否	否
vms vm	list-resource	列出创建虚拟机可用的资源	否	否
vms vm	logs	查看虚拟机的操作日志	否	否
vms vm	poweron	启动虚拟机	否	否
vms vm	poweroff	关闭虚拟机（正常关机）	是	否
vms vm	force-poweroff	强制关闭虚拟机	是	✅
vms vm	reboot	重新启动虚拟机	否	否
vms vm	pause	暂停虚拟机	否	否
vms vm	resume	恢复已暂停的虚拟机	否	否
vms vm	autorun	设置开机自启动	否	否
vms vm	clone	克隆虚拟机	否	否
vms vm	export	导出虚拟机为 OVA 文件	否	否
vms vm	delete	删除虚拟机	是	✅
vms vm disk	list	查看虚拟机的虚拟硬盘	否	否
vms vm snapshot	list	列出虚拟机的快照	否	否
vms vm snapshot	create	创建快照	否	否
vms vm snapshot	edit	编辑快照描述与锁定状态	否	否
vms vm snapshot	config	查看快照中保存的虚拟机配置	否	否
vms vm snapshot	consistency	预览快照一致性	否	否
vms vm	link	获取 VNC 控制台连接信息	否	否
vms network	list	列出虚拟网络	否	否
vms network	get	查看虚拟网络详情	否	否
vms network	create	创建虚拟网络	否	否
vms network	update	更新虚拟网络	否	否
vms network	delete	删除虚拟网络	是	✅
vms network	list-interfaces	列出指定类型的网络接口	否	否
vms network	list-vnics	列出网络上的虚拟网卡	否	否
vms network	ovsinfo	查看 OVS 是否启用	否	否
vms image	list	列出映像	否	否
vms image	edit	编辑映像信息	否	否
vms image	delete	删除映像	是	✅
vms image	list-vms	查看使用该映像的虚拟机	否	否
vms repo	list	列出存储空间	否	否
vms repo	get	查看存储空间详情	否	否
vms repo	update	更新存储空间配置	否	否
vms repo	delete	删除存储空间	是	✅
vms repo	list-volumes	列出可用的卷	否	否
vms repo	list-vms	列出存储空间内的虚拟机	否	否
vms repo	check-running	检查存储空间上正在运行的虚拟机	否	否
vms repo	whether-exist-data	检查存储空间内是否存在数据	否	否
vms setting	get	查看全局设置	否	否
vms collectd	hostinfo	查看主机监控信息	否	否
vms collectd	vminfo	查看虚拟机监控信息	否	否
vms collectd	storageinfo	查看存储监控信息	否	否

命令参考

命令中的 <id> 为虚拟机 ID，对应虚拟机列表输出中的 GUEST ID；<network_id>、<image_id>、<repo_id> 同理，可分别通过 vms network list、vms image list、vms repo list 获取。

关于输出示例：vms 的表格输出会对过长的字段值做固定宽度截断（以省略号结尾，且与终端宽度无关），例如虚拟机配置中的 VDISKS、VNICS、ISO IMAGES，以及映像名称。因此，本文档中涉及长字段的命令统一给出完整的 --json 输出示例，其余命令给出表格输出示例。脚本处理时也建议统一使用 --json。

一、虚拟机查询

vms vm list – 列出虚拟机

列出本机所有虚拟机及其基本状态。

vms vm list [--limit N] [--offset N] [--json]

--limit、--offset 为分页参数
输出列：名称、虚拟机 ID、运行状态、CPU 核数、内存大小（单位 KB）、IP 地址

输出示例：

NAME     GUEST ID                              STATUS    VCPU NUM  VRAM SIZE  IP
145      09fd98ee-4e2d-4c7a-a95c-8bacab80d322  shutdown  4         2097152    -
win10    9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1  shutdown  4         2097152    -
1454486  5a0391f2-c545-45eb-8eed-0a104972229b  shutdown  4         2097152    -
win101   32ee5a74-de8b-47a9-959d-1725c881ceab  shutdown  4         2097152    -

STATUS 常见取值：

状态	说明
running	运行中
shutdown	已关机
saved	已暂停（运行状态已保存到磁盘）

vms vm get – 查看虚拟机详情

查看指定虚拟机的完整配置与运行状态。

vms vm get <id> --json

输出包含虚拟机的全部配置与运行状态字段
无描述、无 IP 等空值显示为空字符串
虚拟机不存在时命令返回错误并输出错误信息

输出示例：

{
  "iso_images": [
    "c93083a5-2b39-4f32-b19f-1ad97c6b4de4",
    "9b3f2fdd-9173-4611-a84c-0cc9ce88293c"
  ],
  "image_paths": [
    "",
    ""
  ],
  "autorun": 0,
  "boot_from": "cdrom",
  "bios": "bios",
  "kb_layout": "en-us",
  "serial_console": true,
  "usb_version": 2,
  "usb_device_name": [
    "USB - Integrated Technology Express, Inc. Disk 2.0"
  ],
  "usbs": [
    ":3:3:048d:1234"
  ],
  "use_ovmf": false,
  "vnics": [
    {
      "prefer_sriov": false,
      "vnic_type": 3,
      "mac": "1a:e2:ae:95:4a:51",
      "network_id": "b364a1ec-f60c-4971-9ea2-f7a002f09fa3",
      "virtual_interface_id": "fe972ef5-b066-4967-89fa-8e85e43c8808"
    }
  ],
  "operating_system_type": 0,
  "vdisks": [
    {
      "vdisk_mode": 1,
      "name": "",
      "unmap": false,
      "iops_enable": false,
      "dev_limit": 0,
      "dev_reservation": 0,
      "dev_weight": 3,
      "vdisk_size": 1024,
      "idx": 0,
      "vdisk_id": "f4ed4eae-1512-4273-963b-79ebd93a0932",
      "disk_image_type": "",
      "disk_image_id": ""
    }
  ],
  "name": "win10",
  "vcpu_num": 4,
  "vcpu_usage": 0,
  "vram_size": 2097152,
  "video_card": "vga",
  "machine_type": "1",
  "cpu_weight": 3,
  "ip": "",
  "desc": "",
  "cpu_passthru": false,
  "hyperv_enlighten": true,
  "cpu_pin_num": 0,
  "repo_id": "735ef7f7-5d8d-4102-9377-8a7b8c33cda6",
  "repo_name": "VM-Storage01",
  "poweron_after_create": false,
  "guest_id": "9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1",
  "increaseAllocatedSize": 0,
  "host_id": "15341593-7f43-49f4-9523-6ac750a63a8a",
  "host_name": "",
  "snap_num": 0,
  "has_guest_agent": false,
  "status": "shutdown",
  "status_code": 0,
  "status_desc": "",
  "host_ram_size": 0,
  "total_throughput": 0,
  "total_iops": 0,
  "total_io_latency": 0,
  "total_rx_bytes": 0,
  "total_tx_bytes": 0,
  "memory_usage": 0,
  "cpu_usage": 0,
  "vm_status_progress": 0
}

vms vm list-resource – 列出创建虚拟机可用的资源

查看主机可提供的固件类型、映像、CPU、内存、网络、存储空间、可直通设备等资源，用于创建虚拟机前评估。

vms vm list-resource --json

返回字段：max_cpu_num、max_ram_size、usbs、pci_devices、networks、repos、images、video_cards、firmware、keyboard_layout。

输出示例：

{
  "max_cpu_num": 4,
  "max_ram_size": 16503336960,
  "usbs": [
    {
      "product_name": "4-Port USB 2.0 Hub",
      "usb_id": ":3:3:0x0bda:0x5423",
      "version": ""
    },
    {
      "product_name": "4-Port USB 3.2 Hub",
      "usb_id": ":4:2:0x0bda:0x0423",
      "version": ""
    },
    {
      "product_name": "Flash Drive",
      "usb_id": ":3:2:0x058f:0x6387",
      "version": ""
    }
  ],
  "pci_devices": [
    {
      "device_name": "",
      "bdf": "0000:02:00.0",
      "vendor_id": "0x10ec",
      "product_id": "0x8126",
      "class_id": "0x020000",
      "iommu_group": 13,
      "iommu_group_bdfs": [
        "0x0000:0x02:0x00.0x0"
      ],
      "driver": "r8169",
      "type": "Network Controller"
    },
    {
      "device_name": "",
      "bdf": "0000:00:0d.0",
      "vendor_id": "0x8086",
      "product_id": "0x464e",
      "class_id": "0x0c0330",
      "iommu_group": 2,
      "iommu_group_bdfs": [
        "0x0000:0x00:0x0d.0x0"
      ],
      "driver": "xhci_hcd",
      "type": "USB Controller"
    },
    {
      "device_name": "",
      "bdf": "0000:03:00.0",
      "vendor_id": "0x10ec",
      "product_id": "0x8126",
      "class_id": "0x020000",
      "iommu_group": 14,
      "iommu_group_bdfs": [
        "0x0000:0x03:0x00.0x0"
      ],
      "driver": "r8169",
      "type": "Network Controller"
    },
    {
      "device_name": "",
      "bdf": "0000:00:14.0",
      "vendor_id": "0x8086",
      "product_id": "0x54ed",
      "class_id": "0x0c0330",
      "iommu_group": 3,
      "iommu_group_bdfs": [
        "0x0000:0x00:0x14.0x2",
        "0x0000:0x00:0x14.0x0"
      ],
      "driver": "xhci_hcd",
      "type": "USB Controller"
    },
    {
      "device_name": "",
      "bdf": "0000:00:14.2",
      "vendor_id": "0x8086",
      "product_id": "0x54ef",
      "class_id": "0x050000",
      "iommu_group": 3,
      "iommu_group_bdfs": [
        "0x0000:0x00:0x14.0x2",
        "0x0000:0x00:0x14.0x0"
      ],
      "driver": "",
      "type": "IOMMU Group Device"
    }
  ],
  "networks": [
    {
      "name": "VM-Network04",
      "network_id": "ce9807c9-47b3-4258-9a80-ea8db1fd785d",
      "support_sriov": false
    },
    {
      "name": "VM-Network05",
      "network_id": "b56c2f7b-e3f0-4b68-8a3b-245c90a8f8b5",
      "support_sriov": false
    },
    {
      "name": "VM-Network01",
      "network_id": "b364a1ec-f60c-4971-9ea2-f7a002f09fa3",
      "support_sriov": false
    },
    {
      "name": "VM-Network02",
      "network_id": "6c9fffd8-c7c4-4968-9b50-6890a640ec94",
      "support_sriov": false
    },
    {
      "name": "VM-Network03",
      "network_id": "4c05b2a2-dd49-4588-ac5c-64975c92d2d3",
      "support_sriov": false
    }
  ],
  "repos": [
    {
      "name": "VM-Storage01",
      "free_size": 941970767872,
      "repo_id": "735ef7f7-5d8d-4102-9377-8a7b8c33cda6",
      "volume_size": 1099511627776,
      "file_system": "btrfs",
      "status": ""
    },
    {
      "name": "VM-Storage02",
      "free_size": 445785296896,
      "repo_id": "517571ba-f7f7-49e1-9a62-7eb6ddfd9c78",
      "volume_size": 536870912000,
      "file_system": "btrfs",
      "status": ""
    }
  ],
  "images": [
    {
      "id": "c93083a5-2b39-4f32-b19f-1ad97c6b4de4",
      "name": "cn_windows_10_consumer_editions_version_1909_updated_jan_2020_x86_dvd_9c50652f",
      "status": "available",
      "type": "iso",
      "used_size": 3884539904
    },
    {
      "id": "9b3f2fdd-9173-4611-a84c-0cc9ce88293c",
      "name": "virtio-win-0.1.285pro",
      "status": "available",
      "type": "iso",
      "used_size": 789645312
    },
    {
      "id": "efd6da18-9475-44cf-8fb0-e2513421e68a",
      "name": "haos_ova-18.2",
      "status": "available",
      "type": "qcow2",
      "used_size": 1091698688,
      "virtual_size": 34359738368
    },
    {
      "id": "cb9d929a-d673-4e46-ac86-9488bbef19b9",
      "name": "cn_windows_11_consumer_editions_version_21h2_updated_july_2022_x64_dvd_50ad4acf",
      "status": "available",
      "type": "iso",
      "used_size": 5858816000
    }
  ],
  "video_cards": [
    "cirrus",
    "vga",
    "vmvga"
  ],
  "firmware": [
    "Legacy BIOS",
    "UEFI"
  ],
  "keyboard_layout": [
    "fr-be",
    "ar",
    "bepo",
    "cz",
    "da",
    "de",
    "de-ch",
    "en-gb",
    "en-us",
    "es",
    "et",
    "fo",
    "fr",
    "fr-be",
    "fr-ca",
    "fr-ch",
    "hr",
    "hu",
    "is",
    "it",
    "ja",
    "lt",
    "lv",
    "mk",
    "nl",
    "nl-be",
    "no",
    "pl",
    "pt",
    "pt-br",
    "ru",
    "sl",
    "sv",
    "th",
    "tr"
  ]
}

vms vm logs – 查看虚拟机操作日志

查看与指定虚拟机相关的操作日志（开关机、快照、编辑、导入导出等）。

vms vm logs <id> --json [--limit N] [--desc]

--limit 指定返回条数，默认 50
--desc 按时间倒序（默认开启）
每条日志包含时间、级别、分类、操作用户与事件描述，事件描述为完整文本
事件描述（event）由 VMs 服务按设备的系统语言本地化输出，本文档示例统一使用英文

输出示例：

[
  {
    "id": 0,
    "level": "Info",
    "time": "2026-09-02T11:44:09.176535374+08:00",
    "category": "vm",
    "user": "system",
    "event": "Virtual machine(win10) shutdown successfully"
  },
  {
    "id": 0,
    "level": "Info",
    "time": "2026-09-02T11:43:10.597187659+08:00",
    "category": "vm",
    "user": "system",
    "event": "Virtual machine(win10) started successfully"
  },
  {
    "id": 0,
    "level": "Info",
    "time": "2026-09-02T11:40:32.74904922+08:00",
    "category": "vm",
    "user": "system",
    "event": "Virtual machine(win10) shutdown successfully"
  },
  {
    "id": 0,
    "level": "Info",
    "time": "2026-09-02T11:39:55.916718004+08:00",
    "category": "vm",
    "user": "system",
    "event": "Virtual machine(win10) started successfully"
  },
  {
    "id": 0,
    "level": "Info",
    "time": "2026-09-02T11:39:43.341421576+08:00",
    "category": "vm",
    "user": "system",
    "event": "Virtual machine(win10) shutdown successfully"
  },
  {
    "id": 0,
    "level": "Info",
    "time": "2026-09-02T11:38:31.518259486+08:00",
    "category": "vm",
    "user": "system",
    "event": "Virtual machine(win10) shutdown successfully"
  },
  {
    "id": 0,
    "level": "Info",
    "time": "2026-09-02T11:38:07.98065689+08:00",
    "category": "vm",
    "user": "system",
    "event": "Virtual machine(win10) started successfully"
  },
  {
    "id": 0,
    "level": "Error",
    "time": "2026-09-02T11:32:35.01952111+08:00",
    "category": "vm",
    "user": "system",
    "event": "Virtual machine (win10) export failed (Error:stat : no such file or directory)"
  }
]

二、虚拟机电源管理

vms vm poweron – 启动虚拟机

vms vm poweron <id>

虚拟机必须处于已关机状态，否则返回状态冲突错误
输出：VM powered on: <id>

vms vm poweroff – 关闭虚拟机

向虚拟机发送正常关机请求，让系统优雅关闭。

vms vm poweroff <id> [--yes]

属于危险操作：交互模式会询问确认，非交互模式必须加 --yes
虚拟机必须处于运行中状态，否则返回状态冲突错误

交互模式确认提示：

This action will powered off VM "9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1". Do you want to continue? [y/N]: 

输出：VM powered off: <id>

vms vm force-poweroff – 强制关闭虚拟机（高风险）

强制关闭虚拟机，等同于直接断电。

vms vm force-poweroff <id> [--yes]

属于高风险操作：交互模式会询问确认，非交互模式必须加 --yes
可能导致虚拟机内的数据丢失，建议仅在虚拟机无响应时使用

交互模式确认提示：

This action will force powered off VM "9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1". Do you want to continue? [y/N]: 

输出：VM force powered off: <id>

vms vm reboot – 重新启动虚拟机

vms vm reboot <id>

输出：VM rebooted: <id>

vms vm pause – 暂停虚拟机

冻结虚拟机的运行状态，并将当前状态保存到磁盘。

vms vm pause <id>

虚拟机必须处于运行中状态，否则返回状态冲突错误
暂停后虚拟机状态显示为 saved
输出：VM paused: <id>

vms vm resume – 恢复虚拟机

将虚拟机从暂停状态恢复到运行状态。

vms vm resume <id>

虚拟机必须处于暂停状态，否则返回状态冲突错误
输出：VM resumed: <id>

vms vm autorun – 设置开机自启动

设置虚拟机是否随主机启动自动开机。

vms vm autorun <id> <true|false>

第二个参数必须为 true 或 false
命令会读取当前配置并仅修改自启动开关，其他配置不受影响
输出：Auto-start enabled for VM <id> 或 Auto-start disabled for VM <id>

三、虚拟机复制、导出与删除

vms vm clone – 克隆虚拟机

以现有虚拟机为模板复制出一台新的虚拟机。

vms vm clone --body '{"guest_id":"<source_id>","name":"my-clone"}'
vms vm clone --file clone.json

请求体中 guest_id 为源虚拟机 ID，name（或 guest_name）为新虚拟机名称
源虚拟机必须处于已关机状态
--body 直接以 JSON 字符串传入请求体，--file 从文件读取请求体

vms vm export – 导出虚拟机

将虚拟机导出为 OVA 文件，便于备份或迁移到其他虚拟化平台。

vms vm export --body '{"guest_id":"<source_id>","target_ova_path":"/Volume1/export/my-vm.ova"}'
vms vm export --file export.json

请求体中 guest_id 为源虚拟机 ID，target_ova_path 为目标文件路径，ova_mode 为可选的 VMware 兼容模式
源虚拟机必须处于已关机状态
导出为耗时任务，大容量虚拟机导出时间较长

vms vm delete – 删除虚拟机（高风险）

永久删除虚拟机。

vms vm delete <id> [--yes]

属于高风险操作：交互模式会询问确认，非交互模式必须加 --yes
删除后无法恢复，请提前确认虚拟机内数据已备份

交互模式确认提示：

This action will permanently delete VM "5a0391f2-c545-45eb-8eed-0a104972229b". Do you want to continue? [y/N]: 

输出：VM deleted: <id>

四、虚拟硬盘

vms vm disk list – 查看虚拟硬盘

列出指定虚拟机的所有虚拟硬盘。

vms vm disk list <id> [--json]

输出示例：

NAME  VDISK ID                              VDISK SIZE  VDISK MODE  IDX
-     f4ed4eae-1512-4273-963b-79ebd93a0932  1024        1           0

VDISK MODE 为虚拟硬盘控制器类型编号，1 表示 IDE
未命名的虚拟硬盘在 NAME 列显示为 -

五、快照管理

vms vm snapshot list – 列出快照

vms vm snapshot list <id> [--json]

输出示例：

NAME                                    GUEST ID                              DESCRIPTION      LOCKED  CREATED AT                 VM STATE  ACTUAL CONSISTENCY
snapshot_2026-09-02T11-43-51.183703274  9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1  cli-test-edited  false   2026-09-02T11:43:51+08:00  running   crash
snapshot_2026-05-15T17-13-48.986448711  9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1  -                false   2026-05-15T17:13:48+08:00  shutdown  filesystem

VM STATE 为创建快照时虚拟机的运行状态
ACTUAL CONSISTENCY 为快照的一致性类型，filesystem 表示文件系统一致，crash 表示崩溃一致

vms vm snapshot create – 创建快照

为虚拟机创建快照，用于快速回滚或备份当前状态。

vms vm snapshot create <id>
vms vm snapshot create <id> --body '{"description":"before-upgrade","locked":false}'

请求体可选：description 为快照描述，locked 为是否锁定
快照名称由系统按创建时间自动生成
快照会占用存储空间，长期不清理可能撑满存储空间，建议定期整理

vms vm snapshot edit – 编辑快照

修改快照的描述或锁定状态。

vms vm snapshot edit <id> <snapshot_name> --body '{"description":"updated description"}'
vms vm snapshot edit <id> <snapshot_name> --body '{"locked":true}'

仅修改请求体中出现的字段，未出现的字段保持原值；只改描述不会改变锁定状态，反之亦然

输出示例：

PROPERTY            VALUE
ACTUAL CONSISTENCY  crash
CREATED AT          2026-09-02T11:43:51+08:00
DESCRIPTION         cli-test-edited
GUEST ID            9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1
LOCKED              false
NAME                snapshot_2026-09-02T11-43-51.183703274
VM STATE            running

vms vm snapshot config – 查看快照的虚拟机配置

查看快照中保存的虚拟机配置。

vms vm snapshot config <id> <snapshot_name>

<id> 为虚拟机 ID，<snapshot_name> 为快照名称，可通过 vms vm snapshot list <id> 获取。

输出示例：

PROPERTY                VALUE
CPU COMPATIBILITY MODE  true
CPU PASSTHRU            false
HYPERV ENLIGHTEN        true
REPO NAME               VM-Storage01
USB DEVICE NAME         ["USB - Integrated Technology Express, Inc. Disk 2.0"]
USB VERSION             2
USBS                    [":3:3:048d:1234"]
VCPU NUM                4
VDISK NUM               1
VDISK TOTAL SIZE        1024
VDISKS                  [{"name":"disk1","type":"ide","vdisk_size":1024}]
VIDEO CARD              vga
VRAM SIZE               2097152

vms vm snapshot consistency – 预览快照一致性

在创建快照前预览可能获得的一致性类型，帮助判断当前是否适合创建快照。

vms vm snapshot consistency <id>

输出示例：

PROPERTY          VALUE
CONSISTENCY TYPE  filesystem
REASON            vm_shutdown
VM STATE          shutdown

虚拟机关机状态下创建快照可获得文件系统一致的快照；运行状态下通常只能获得崩溃一致的快照。

六、远程控制台

vms vm link – 获取 VNC 连接信息

获取虚拟机 VNC 控制台的连接信息，用于在浏览器中打开远程控制台。

vms vm link <id> --json

虚拟机必须处于运行或暂停状态，否则返回状态冲突错误

输出示例：

{
  "url": "VMs/noVNC/vnc.html?autoconnect=true\u0026reconnect=true\u0026path=utils/websockify/?token=09fd98ee-4e2d-4c7a-a95c-8bacab80d322\u0026title=145",
  "port": 8181,
  "https": false
}

url 为相对于 NAS 管理地址的控制台路径，port 为控制台服务端口，https 表示是否需要通过 HTTPS 访问
JSON 输出中 URL 里的 & 会转义为 \u0026

七、虚拟网络管理

网络类型分为两种：

类型	说明
专用（private）	仅供本机虚拟机之间通信的内部网络，不绑定物理网卡
外部（external）	绑定到物理网卡的网络，虚拟机可通过该网络与外部通信

vms network list – 列出虚拟网络

vms network list [--limit N] [--offset N] [--json]

输出示例：

NAME          NETWORK ID                            TYPE      VLAN ID  NUM GUESTS  NUM HOSTS  NUM INTERFACES  HOST NAME
VM-Network04  ce9807c9-47b3-4258-9a80-ea8db1fd785d  external  0        0           1          1               A-eae4
VM-Network01  b364a1ec-f60c-4971-9ea2-f7a002f09fa3  external  0        2           1          1               A-eae4

NUM GUESTS 为接入该网络的虚拟机数量，NUM INTERFACES 为已选中的物理网卡数量

vms network get – 查看虚拟网络详情

vms network get <network_id> --json

输出示例：

{
  "metadata": {
    "createdAt": "2026-05-15T16:46:08.415062294+08:00",
    "updatedAt": "2026-05-15T16:46:08.415062415+08:00"
  },
  "network_id": "b364a1ec-f60c-4971-9ea2-f7a002f09fa3",
  "name": "VM-Network01",
  "host_id": "15341593-7f43-49f4-9523-6ac750a63a8a",
  "host_name": "A-eae4",
  "interfaces": {
    "15341593-7f43-49f4-9523-6ac750a63a8a": {
      "totalCount": 1,
      "items": [
        {
          "checked": false,
          "host_id": "15341593-7f43-49f4-9523-6ac750a63a8a",
          "host_name": "A-eae4",
          "interface_id": "/00000000-0000-0000-0000-6cbfb504eae5",
          "interface_name": "LAN 2",
          "ip": [
            "192.168.2.121"
          ],
          "mask": [
            "ffffff00"
          ],
          "speed_mbs": 1000,
          "status": "connected",
          "tx_kbps": 0,
          "rx_kbps": 0
        },
        {
          "checked": true,
          "host_id": "15341593-7f43-49f4-9523-6ac750a63a8a",
          "host_name": "A-eae4",
          "interface_id": "/00000000-0000-0000-0000-6cbfb504eae4",
          "interface_name": "LAN 1",
          "ip": [
            "10.18.8.95"
          ],
          "mask": [
            "ffffff00"
          ],
          "speed_mbs": 1000,
          "status": "connected",
          "tx_kbps": 2.5458984375,
          "rx_kbps": 11.45458984375
        }
      ]
    }
  },
  "num_guests": 0,
  "num_hosts": 1,
  "num_interfaces": 1,
  "type": "external",
  "vlan_id": 0
}

interfaces 为该网络绑定的网卡信息，按主机 ID 组织，checked 表示该网卡是否已选中
metadata 记录网络的创建与更新时间

vms network create – 创建虚拟网络

vms network create --body '{"name":"net1","type":"private","host_name":"TNAS"}' --json
vms network create --body '{"name":"net1","type":"external","vlan_id":100,"host_name":"TNAS","interface_name":"LAN 1"}' --json

创建专用网络：

请求体需包含 name、type（private）、host_name 或 host_id，指定网络创建在哪个主机上
创建前可通过 vms network list-interfaces private 查看可用主机

创建外部网络：

请求体需包含 name、type（external）、vlan_id，并至少指定一块物理网卡
可通过 interface_name（如 LAN 1）或 interface_id 指定网卡，网卡名称在跨主机不唯一时需搭配 host_name 使用
创建前可通过 vms network list-interfaces external 查看可用网卡

输出为创建后的网络信息，与 vms network get 的结构一致：

{
  "metadata": {
    "createdAt": "2026-09-17T16:57:32.064720576+08:00",
    "updatedAt": "2026-09-17T16:57:32.064720634+08:00"
  },
  "network_id": "27047bd1-eeeb-4762-82ae-45094dea4854",
  "name": "cli-demo-net",
  "host_id": "15341593-7f43-49f4-9523-6ac750a63a8a",
  "host_name": "A-eae4",
  "interfaces": {
    "15341593-7f43-49f4-9523-6ac750a63a8a": {
      "totalCount": 1,
      "items": [
        {
          "checked": true,
          "host_id": "15341593-7f43-49f4-9523-6ac750a63a8a",
          "host_name": "A-eae4",
          "interface_id": "",
          "interface_name": "PNdea4854",
          "ip": null,
          "mask": null,
          "speed_mbs": 0,
          "status": ""
        }
      ]
    }
  },
  "num_guests": 0,
  "num_hosts": 1,
  "num_interfaces": 1,
  "type": "private",
  "vlan_id": 0
}

未指定网卡时命令会给出提示：

network create (type "external") requires selecting at least one interface; add "interface_name" (optionally scoped with "host_name") or "interface_id" to the body, e.g. {"name":"net1","type":"external","vlan_id":100,"host_name":"TNAS","interface_name":"LAN 1"}. Run "vms network list-interfaces external" to see available interfaces. Example available interface: LAN 2 on A-eae4 (host_id=15341593-7f43-49f4-9523-6ac750a63a8a, interface_id=/00000000-0000-0000-0000-6cbfb504eae5)

vms network update – 更新虚拟网络

只提交需要修改的字段，未提交的字段保持原值。

vms network update --body '{"network_id":"<network_id>","name":"renamed"}'
vms network update --body '{"network_id":"<network_id>","vlan_id":200}'

请求体必须包含 network_id
命令会先读取当前网络配置并合并提交的字段，网络名称与已选网卡不会被清空
输出为更新后的网络信息

vms network delete – 删除虚拟网络（高风险）

vms network delete <network_id> [--yes]

属于高风险操作：交互模式会询问确认，非交互模式必须加 --yes
删除网络会断开接入该网络的所有虚拟机
建议先通过 vms network list-vnics <network_id> 确认接入的虚拟机

交互模式确认提示：

This action will delete network "b364a1ec-f60c-4971-9ea2-f7a002f09fa3". Do you want to continue? [y/N]: 

输出：Network deleted: <network_id>

vms network list-interfaces – 列出网络接口

列出指定类型的网络接口。

vms network list-interfaces external [--limit N] [--offset N]
vms network list-interfaces private [--limit N] [--offset N]

external 返回主机上可用的物理网卡
private 返回可用于创建专用网络的主机信息

输出示例（external）：

INTERFACE NAME  INTERFACE ID                           HOST NAME  STATUS        IP              SPEED MBS
LAN 2           /00000000-0000-0000-0000-6cbfb504eae5  A-eae4     disconnected  -               -1
LAN 1           /00000000-0000-0000-0000-6cbfb504eae4  A-eae4     connected     ["10.18.8.73"]  1000

输出示例（private）：

INTERFACE NAME  INTERFACE ID  HOST NAME  STATUS  IP  SPEED MBS
-               -             A-eae4     -       -   0

vms network list-vnics – 列出网络上的虚拟网卡

vms network list-vnics <network_id> [--limit N] [--offset N] [--json]

输出示例：

GUEST NAME  GUEST ID                              MAC ADDRESS        VIRTUAL INTERFACE ID                  NETWORK NAME  STATUS  PREFER SRIOV
win10       9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1  1a:e2:ae:95:4a:51  fe972ef5-b066-4967-89fa-8e85e43c8808  VM-Network01  -       false
win101      32ee5a74-de8b-47a9-959d-1725c881ceab  1a:f6:db:fb:3d:79  f93bf16c-01ca-4b60-b164-8a3083fb5f03  VM-Network01  -       false

vms network ovsinfo – 查看 OVS 状态

确认 Open vSwitch 虚拟交换机是否已启用。

vms network ovsinfo [--json]

输出示例：

PROPERTY  VALUE
RESULT    true

VALUE 为 true 表示 OVS 已启用。

八、映像管理

vms image list – 列出映像

列出可用于创建虚拟机的系统映像文件。

vms image list --json

image_name 为映像名称，file_name 为对应的文件名
type 为映像格式，如 iso、qcow2
status 为映像状态，available 表示可用
repos 为该映像所在的存储空间
progress 为映像处理任务的进度，0 表示无进行中的任务

输出示例：

{
  "totalCount": 4,
  "items": [
    {
      "image_name": "cn_windows_10_consumer_editions_version_1909_updated_jan_2020_x86_dvd_9c50652f",
      "image_id": "c93083a5-2b39-4f32-b19f-1ad97c6b4de4",
      "file_name": "cn_windows_10_consumer_editions_version_1909_updated_jan_2020_x86_dvd_9c50652f.iso",
      "type": "iso",
      "file_size": 3884539904,
      "status": "available",
      "status_code": 0,
      "status_reason": "",
      "create_time": 1778835784,
      "repos": [
        {
          "repo_name": "VM-Storage01",
          "repo_id": "735ef7f7-5d8d-4102-9377-8a7b8c33cda6"
        }
      ],
      "progress": 0,
      "task_id": 0,
      "virtual_size": 0
    },
    {
      "image_name": "cn_windows_11_consumer_editions_version_21h2_updated_july_2022_x64_dvd_50ad4acf",
      "image_id": "cb9d929a-d673-4e46-ac86-9488bbef19b9",
      "file_name": "cn_windows_11_consumer_editions_version_21h2_updated_july_2022_x64_dvd_50ad4acf.iso",
      "type": "iso",
      "file_size": 5858816000,
      "status": "available",
      "status_code": 0,
      "status_reason": "",
      "create_time": 1778835784,
      "repos": [
        {
          "repo_name": "VM-Storage01",
          "repo_id": "735ef7f7-5d8d-4102-9377-8a7b8c33cda6"
        }
      ],
      "progress": 0,
      "task_id": 0,
      "virtual_size": 0
    },
    {
      "image_name": "virtio-win-0.1.285pro",
      "image_id": "9b3f2fdd-9173-4611-a84c-0cc9ce88293c",
      "file_name": "virtio-win-0.1.285.iso",
      "type": "iso",
      "file_size": 789645312,
      "status": "available",
      "status_code": 0,
      "status_reason": "",
      "create_time": 1778836128,
      "repos": [
        {
          "repo_name": "VM-Storage01",
          "repo_id": "735ef7f7-5d8d-4102-9377-8a7b8c33cda6"
        }
      ],
      "progress": 0,
      "task_id": 0,
      "virtual_size": 0
    },
    {
      "image_name": "haos_ova-18.2",
      "image_id": "efd6da18-9475-44cf-8fb0-e2513421e68a",
      "file_name": "haos_ova-18.2.qcow2",
      "type": "qcow2",
      "file_size": 1091698688,
      "status": "available",
      "status_code": 0,
      "status_reason": "",
      "create_time": 1787191833,
      "repos": [
        {
          "repo_name": "VM-Storage02",
          "repo_id": "517571ba-f7f7-49e1-9a62-7eb6ddfd9c78"
        }
      ],
      "progress": 0,
      "task_id": 0,
      "virtual_size": 0
    }
  ]
}

vms image edit – 编辑映像

修改映像名称，或调整映像所在的存储空间。

vms image edit --body '{"image_id":"<image_id>","repos":["<repo_id>"]}'
vms image edit --body '{"image_id":"<image_id>","repos":["<repo_id_1>","<repo_id_2>"],"image_name":"renamed.iso"}'

请求体必须包含 image_id 与 repos，repos 为该映像完整的目标存储空间列表，不能为空
image_name、file_name、type、file_size 为可选字段，未提供时沿用当前值
repos 为空会导致映像被移出所有存储空间，命令会在执行前拒绝该请求
输出：Image updated

vms image delete – 删除映像（高风险）

vms image delete --image-id <image_id> [--yes]

--image-id 为必填项
属于高风险操作：交互模式会询问确认，非交互模式必须加 --yes
删除映像不影响已创建的虚拟机，但会影响后续基于该映像创建虚拟机
建议先通过 vms image list-vms --image-id <image_id> 确认使用情况

交互模式确认提示：

This action will permanently delete image "efd6da18-9475-44cf-8fb0-e2513421e68a". Do you want to continue? [y/N]: 

输出：Image deleted: <image_id>

vms image list-vms – 查看使用该映像的虚拟机

vms image list-vms --image-id <image_id> [--json]

输出示例：

GUEST NAME
1454486

删除映像前可先执行该命令确认影响范围；无虚拟机使用该映像时输出为空。

九、存储空间管理

vms repo list – 列出存储空间

vms repo list [--json]

输出示例：

NAME          REPO ID                               STATUS  USED          PERCENT USED        TOTAL SIZE     FILE SYSTEM  HOST NAME
VM-Storage01  735ef7f7-5d8d-4102-9377-8a7b8c33cda6  -       155583651840  14.150249481201172  1097552691200  btrfs        -
VM-Storage02  517571ba-f7f7-49e1-9a62-7eb6ddfd9c78  normal  89361494016   16.64487648010254   535146790912   btrfs        A-eae4

vms repo get – 查看存储空间详情

vms repo get <repo_id> [--json]

输出示例：

PROPERTY              VALUE
ENABLE LOWER NOTIFY   false
FILE SYSTEM           btrfs
HARD LIMIT            2
HOST ID               15341593-7f43-49f4-9523-6ac750a63a8a
HOST NAME             A-eae4
LAST NOTIFY TRESHOLD  -
LOCATION VOLUME       /Volume2
NAME                  VM-Storage02
REPO ID               517571ba-f7f7-49e1-9a62-7eb6ddfd9c78
SOFT LIMIT            10
STATUS                normal
TOTAL SIZE            534760128512

LOCATION VOLUME 为存储空间所在的卷
SOFT LIMIT、HARD LIMIT 为容量告警阈值（百分比）
ENABLE LOWER NOTIFY 为是否启用容量不足提醒

vms repo update – 更新存储空间

只提交需要修改的字段，未提交的字段保持原值。

vms repo update --body '{"repo_id":"<repo_id>","name":"new-name"}'
vms repo update --body '{"repoId":"<repo_id>","enable_lower_notify":true}'

存储空间 ID 可通过 repo_id 或 repoId 传入
命令会先读取当前配置并合并提交的字段，其他设置不会丢失
输出为更新后的存储空间信息

vms repo delete – 删除存储空间（高风险）

vms repo delete <repo_id> <true|false> [--yes]

第二个参数为 need_save_data：true 表示保留磁盘上的数据文件，false 表示连同数据一起删除
属于高风险操作：交互模式会询问确认，非交互模式必须加 --yes
存储空间删除会同时移除其中的虚拟机与映像，建议先执行 vms repo check-running 与 vms repo whether-exist-data 确认影响范围

交互模式确认提示：

This action will delete repository "735ef7f7-5d8d-4102-9377-8a7b8c33cda6" (save data: true). Do you want to continue? [y/N]: 

输出：Repository deleted: <repo_id>

vms repo list-volumes – 列出可用的卷

列出可用于创建存储空间的卷。

vms repo list-volumes [--json]

输出示例：

NAME  UUID                                  DEVICE               FILESYSTEM  STATUS  VOLUME TYPE  TOTAL                            USED                           AVAILABLE                        USAGE
lv3   00000004-2608-1311-3025-6cbfb504eae4  /dev/mapper/vg0-lv3  ext4        -       -            {"unit":"KB","value":102626232}  {"unit":"KB","value":52}       {"unit":"KB","value":101561220}  0.000051200619070623694
lv2   00000003-2606-2215-3256-6cbfb504eae4  /dev/mapper/vg0-lv2  btrfs       -       -            {"unit":"KB","value":104857600}  {"unit":"KB","value":9715824}  {"unit":"KB","value":93096464}   9.450061066630479

vms repo list-vms – 列出存储空间内的虚拟机

vms repo list-vms --body '{"repo_id":"<repo_id>"}'

存储空间 ID 可通过 repo_id 或 repoId 传入
命令会先获取存储空间对象再查询其虚拟机，结果更可靠

vms repo check-running – 检查存储空间上正在运行的虚拟机

vms repo check-running <repo_id> [--json]

删除存储空间前执行，确认没有虚拟机正在运行；无运行中的虚拟机时输出为空。

vms repo whether-exist-data – 检查存储空间内是否有数据

vms repo whether-exist-data --body '{"repo_id":"<repo_id>"}'

删除存储空间前执行，确认存储空间内是否还有数据；与 Web 界面删除存储空间前的预检查一致。

十、全局设置

vms setting get – 查看全局设置

查看 VMs 应用的全局配置。

vms setting get [--json]

输出示例：

PROPERTY                VALUE
HOST SHUTDOWN BEHAVIOR  1
KB LAYOUT               en-us
SHOW VIRTIO BLK VDISK   false

HOST SHUTDOWN BEHAVIOR 为主机关机时对虚拟机的处理方式
KB LAYOUT 为虚拟机的键盘布局

十一、监控信息查询

vms collectd hostinfo – 查看主机监控信息

vms collectd hostinfo [--limit N] [--offset N] [--json]

输出示例：

NAME    ID  STATUS   TYPE     CPU USAGE  RAM USAGE  DESC
A-eae4  -   running  healthy  2.53       15.66      Info

vms collectd vminfo – 查看虚拟机监控信息

vms collectd vminfo [--limit N] [--offset N] [--json]

输出示例：

NAME     ID                                    STATUS    TYPE     CPU USAGE  RAM USAGE  DESC
145      09fd98ee-4e2d-4c7a-a95c-8bacab80d322  shutdown  healthy  0          0          info
win10   9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1  shutdown  healthy  0          0          info
win101   32ee5a74-de8b-47a9-959d-1725c881ceab  shutdown  healthy  0          0          info

vms collectd storageinfo – 查看存储监控信息

vms collectd storageinfo [--limit N] [--offset N] [--json]

输出示例：

NAME          ID                                    HOST NAME  STATUS  TYPE     SIZE           USED          PERCENT USED        PERCENT FREE
VM-Storage01  735ef7f7-5d8d-4102-9377-8a7b8c33cda6  A-eae4     none    healthy  1097552691200  155583651840  14.328414916992188  85.67158508300781
VM-Storage02  517571ba-f7f7-49e1-9a62-7eb6ddfd9c78  A-eae4     none    healthy  535146790912   89361494016   16.966018676757812  83.03398132324219

交互模式与非交互模式

CLI 会判断当前是否在终端环境运行，并采用不同的行为：

交互模式（终端环境）

危险操作显示确认提示，默认选项为 No
输入 y 或 Y 继续执行，输入 n 或直接回车取消
取消操作时输出 Operation cancelled，退出码为 99

非交互模式（脚本/自动化）

危险操作必须使用 --yes 跳过确认，否则命令直接报错并返回退出码 1
无终端环境时不会等待输入，适合脚本与定时任务调用
建议在脚本中显式处理退出码，以区分成功、失败与状态冲突

JSON 输出格式

查询类命令支持 --json 参数，输出规范化的 JSON 数据，便于程序解析。

格式约定：

字段名使用 snake_case
布尔值为 true/false
时间使用 ISO 8601 格式，含纳秒精度与东八区偏移（如 2026-09-02T11:43:51.176535374+08:00）
JSON 输出到 stdout，错误信息输出到 stderr
表格输出中被截断的长字段，在 JSON 输出中为完整值

示例：

vms setting get --json

{
  "host_shutdown_behavior": 1,
  "kb_layout": "en-us",
  "show_virtio_blk_vdisk": false
}

不同命令的 JSON 结构略有差异：vms vm list、vms vm snapshot list、vms vm logs 直接输出数组；其余列表类命令输出包含 totalCount 与数据字段的对象，数据字段名随资源而异（如 items、hosts、vms、storage）。例如 vms repo list --json：

{
  "totalCount": 2,
  "items": {
    "517571ba-f7f7-49e1-9a62-7eb6ddfd9c78": {
      "name": "VM-Storage02",
      "repo_id": "517571ba-f7f7-49e1-9a62-7eb6ddfd9c78",
      "status": "normal",
      "used": 89361494016,
      "percent_used": 16.64487648010254,
      "location_volume": "/Volume2",
      "total_size": 535146790912,
      "hard_limit": 2,
      "soft_limit": 10,
      "enable_lower_notify": false,
      "file_system": "btrfs"
    }
  }
}

部分命令的 JSON 输出为简单值，例如 vms network ovsinfo --json 输出 true，vms vm pause --json 输出 null。

退出码说明

退出码	含义	典型场景
0	成功	命令正常完成
1	参数错误	缺少必填参数、参数格式错误、未加 `--yes`
3	资源不存在	命令的前置校验未通过，例如指定的映像不存在
4	状态冲突	虚拟机当前状态不允许该操作（如对已关机的虚拟机执行关机）
6	连接错误	无法连接到 VMs 服务，或 socket 路径不正确
7	超时	请求超时，可通过 `--timeout` 调整
9	执行错误	后端返回错误（错误信息中包含 code_num 与错误描述）
99	用户取消	交互确认时选择 No 或直接回车

示例：

# 退出码 1（参数错误）
vms vm poweroff <id>
# Confirmation required. Re-run with --yes to continue.

# 退出码 4（状态冲突）
vms vm pause <id>
# cannot pause a virtual machine: VM must be running (current status: shutdown)

# 退出码 9（执行错误）
vms vm get <id>
# vm check configure error: vdisk check - vm not exist: key not found (code_num=2001, vm check configure error)

# 退出码 6（连接错误）
vms vm list --socket /tmp/nope.sock
# failed to connect to VMs daemon (socket /tmp/nope.sock): dial unix /tmp/nope.sock: connect: no such file or directory

使用场景示例

日常运维

# 查看所有虚拟机状态
vms vm list

# 查看某台虚拟机的配置与运行状态
vms vm get <id>

# 查看虚拟机的操作日志
vms vm logs <id> --limit 20

# 开机、关机与重启
vms vm poweron <id>
vms vm poweroff <id> --yes
vms vm reboot <id>

脚本批量操作

# 批量启动所有已关机的虚拟机
vms vm list --json | jq -r '.[] | select(.status == "shutdown") | .guest_id' | while read -r id; do
    vms vm poweron "$id"
done

# 批量关闭所有运行中的虚拟机
vms vm list --json | jq -r '.[] | select(.status == "running") | .guest_id' | while read -r id; do
    vms vm poweroff "$id" --yes
done

# 存储空间容量检查，超过 80% 时输出告警
vms collectd storageinfo --json | jq -r '.storage[] | select(.percent_used > 80) | .name'

备份与巡检

# 关机后为虚拟机创建快照
vms vm poweroff <id> --yes
vms vm snapshot consistency <id>
vms vm snapshot create <id> --body '{"description":"weekly-backup"}'

# 查看快照列表与详情
vms vm snapshot list <id>
vms vm snapshot config <id> <snapshot_name>

# 导出虚拟机为 OVA 文件，用于异地备份
vms vm export --body '{"guest_id":"<id>","target_ova_path":"/Volume1/backup/my-vm.ova"}'

删除前检查

# 删除存储空间前，先确认是否有虚拟机正在运行、是否存在数据
vms repo check-running <repo_id>
vms repo whether-exist-data --body '{"repo_id":"<repo_id>"}'

# 删除映像前，先确认有哪些虚拟机在使用
vms image list-vms --image-id <image_id>

# 删除网络前，先确认接入的虚拟机
vms network list-vnics <network_id>

AI 工具调用

# AI 工具可通过命令行调用 vms 命令
# 例如：获取虚拟机与宿主机状态供 AI 分析
vms vm list --json
vms collectd hostinfo --json

# AI 可解析 JSON 输出并作出决策
vms vm list-resource --json

内部开发与系统集成

# 开发人员可通过 CLI 封装内部运维工具
# 示例：封装虚拟机健康检查函数
check_vm_health() {
    vms collectd vminfo --json | jq -r '.vms[] | select(.status != "running") | .name'
}

# 将 CLI 集成到内部监控平台
vms collectd storageinfo --json | curl -X POST https://monitor.example.com/api/report -d @-

常见问题

Q：CLI 需要额外安装吗？

不需要。CLI 随 VMs 应用一同安装，应用启用后直接执行 vms 命令即可使用。

Q：CLI 必须通过 SSH 使用吗？

不是。CLI 可通过任何命令行终端调用，包括本地终端、远程 SSH、脚本、AI 工具等。

Q：CLI 可以管理其他设备上的虚拟机吗？

不可以。CLI 通过本机 unix socket 与 VMs 服务通信，只用于管理本机虚拟机。

Q：为什么有些命令会提示确认，有些不会？

删除虚拟机、删除网络、删除映像、删除存储空间以及关机（poweroff、force-poweroff）等操作会影响数据或服务，因此默认要求确认；启动、重启、暂停、恢复与查询类命令没有此类限制。

Q：非交互模式下如何确认危险操作？

所有危险操作必须添加 --yes 参数，否则命令会报错退出（退出码 1）。

Q：脚本中如何判断命令是否执行成功？

通过退出码判断：0 表示成功，非 0 表示失败。也可以解析 --json 的输出内容。

Q：为什么 --json 输出的列表是一个对象？

部分命令的 JSON 输出按 ID 组织为对象，并附带 totalCount 字段，便于按 ID 直接取用。

简介​

主要特点​

快速开始​

全局选项​

版本信息示例​

运行环境​

命令汇总表​

命令参考​

一、虚拟机查询​

vms vm list – 列出虚拟机​

vms vm get – 查看虚拟机详情​

vms vm list-resource – 列出创建虚拟机可用的资源​

vms vm logs – 查看虚拟机操作日志​

二、虚拟机电源管理​

vms vm poweron – 启动虚拟机​

vms vm poweroff – 关闭虚拟机​

vms vm force-poweroff – 强制关闭虚拟机（高风险）​

vms vm reboot – 重新启动虚拟机​

vms vm pause – 暂停虚拟机​

vms vm resume – 恢复虚拟机​

vms vm autorun – 设置开机自启动​

三、虚拟机复制、导出与删除​

vms vm clone – 克隆虚拟机​

vms vm export – 导出虚拟机​

vms vm delete – 删除虚拟机（高风险）​

四、虚拟硬盘​

vms vm disk list – 查看虚拟硬盘​

五、快照管理​

vms vm snapshot list – 列出快照​

vms vm snapshot create – 创建快照​

vms vm snapshot edit – 编辑快照​

vms vm snapshot config – 查看快照的虚拟机配置​

vms vm snapshot consistency – 预览快照一致性​

六、远程控制台​

vms vm link – 获取 VNC 连接信息​

七、虚拟网络管理​

vms network list – 列出虚拟网络​

vms network get – 查看虚拟网络详情​

vms network create – 创建虚拟网络​

vms network update – 更新虚拟网络​

vms network delete – 删除虚拟网络（高风险）​

vms network list-interfaces – 列出网络接口​

vms network list-vnics – 列出网络上的虚拟网卡​

vms network ovsinfo – 查看 OVS 状态​

八、映像管理​

vms image list – 列出映像​

vms image edit – 编辑映像​

vms image delete – 删除映像（高风险）​

vms image list-vms – 查看使用该映像的虚拟机​

九、存储空间管理​

vms repo list – 列出存储空间​

vms repo get – 查看存储空间详情​

vms repo update – 更新存储空间​

vms repo delete – 删除存储空间（高风险）​

vms repo list-volumes – 列出可用的卷​

vms repo list-vms – 列出存储空间内的虚拟机​

vms repo check-running – 检查存储空间上正在运行的虚拟机​

vms repo whether-exist-data – 检查存储空间内是否有数据​

十、全局设置​

vms setting get – 查看全局设置​

十一、监控信息查询​

vms collectd hostinfo – 查看主机监控信息​

vms collectd vminfo – 查看虚拟机监控信息​

vms collectd storageinfo – 查看存储监控信息​

交互模式与非交互模式​

交互模式（终端环境）​

非交互模式（脚本/自动化）​

JSON 输出格式​

退出码说明​

使用场景示例​

日常运维​

脚本批量操作​

备份与巡检​

删除前检查​

AI 工具调用​

内部开发与系统集成​

常见问题​

更多帮助​

简介

主要特点

快速开始

全局选项

版本信息示例

运行环境

命令汇总表

命令参考

一、虚拟机查询

vms vm list – 列出虚拟机

vms vm get – 查看虚拟机详情

vms vm list-resource – 列出创建虚拟机可用的资源

vms vm logs – 查看虚拟机操作日志

二、虚拟机电源管理

vms vm poweron – 启动虚拟机

vms vm poweroff – 关闭虚拟机

vms vm force-poweroff – 强制关闭虚拟机（高风险）

vms vm reboot – 重新启动虚拟机

vms vm pause – 暂停虚拟机

vms vm resume – 恢复虚拟机

vms vm autorun – 设置开机自启动

三、虚拟机复制、导出与删除

vms vm clone – 克隆虚拟机

vms vm export – 导出虚拟机

vms vm delete – 删除虚拟机（高风险）

四、虚拟硬盘

vms vm disk list – 查看虚拟硬盘

五、快照管理

vms vm snapshot list – 列出快照

vms vm snapshot create – 创建快照

vms vm snapshot edit – 编辑快照

vms vm snapshot config – 查看快照的虚拟机配置

vms vm snapshot consistency – 预览快照一致性

六、远程控制台

vms vm link – 获取 VNC 连接信息

七、虚拟网络管理

vms network list – 列出虚拟网络

vms network get – 查看虚拟网络详情

vms network create – 创建虚拟网络

vms network update – 更新虚拟网络

vms network delete – 删除虚拟网络（高风险）

vms network list-interfaces – 列出网络接口

vms network list-vnics – 列出网络上的虚拟网卡

vms network ovsinfo – 查看 OVS 状态

八、映像管理

vms image list – 列出映像

vms image edit – 编辑映像

vms image delete – 删除映像（高风险）

vms image list-vms – 查看使用该映像的虚拟机

九、存储空间管理

vms repo list – 列出存储空间

vms repo get – 查看存储空间详情

vms repo update – 更新存储空间

vms repo delete – 删除存储空间（高风险）

vms repo list-volumes – 列出可用的卷

vms repo list-vms – 列出存储空间内的虚拟机

vms repo check-running – 检查存储空间上正在运行的虚拟机

vms repo whether-exist-data – 检查存储空间内是否有数据

十、全局设置

vms setting get – 查看全局设置

十一、监控信息查询

vms collectd hostinfo – 查看主机监控信息

vms collectd vminfo – 查看虚拟机监控信息

vms collectd storageinfo – 查看存储监控信息

交互模式与非交互模式

交互模式（终端环境）

非交互模式（脚本/自动化）

JSON 输出格式

退出码说明

使用场景示例

日常运维

脚本批量操作

备份与巡检

删除前检查

AI 工具调用

内部开发与系统集成

常见问题

更多帮助