Version: TOS 7

VMs CLI

Introduction

VMs CLI is the command-line management tool for the TerraMaster VMs virtualization application, providing query and operations capabilities consistent with the web management interface. The CLI communicates with the VMs service through a local unix socket, adopts a standardized command interface and JSON output format, and can be integrated into scripts, automated operations, and secondary development workflows.

Key Features

Ready to use: installed together with the VMs application, no additional installation required
Flexible invocation: supports local terminals, remote SSH, scripts, AI tools, and many other invocation channels
Dual interactive and non-interactive modes: suitable both for administrators' daily maintenance and for scripts and automated tasks
JSON output support: convenient for program parsing and automated integration
Local communication: communicates with the VMs service only through a local unix socket, and does not expose ports externally
Secondary confirmation for dangerous operations: operations such as deleting a virtual machine or deleting a network require confirmation by default

Quick Start

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

# 查看虚拟机列表
vms vm list

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

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

vms vm list output example:

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    -

Global Options

The following options apply to all commands:

Option	Abbreviation	Description
`--help`	`-h`	Display command help information
`--version`	`-v`	Display the version number (can be combined with `--json` to output structured information)
`--json`	-	Output in JSON format
`--yes`	`-y`	Skip the confirmation prompt for dangerous operations (must be used in non-interactive mode)
`--debug`	-	Enable debug output, displaying the detailed execution process
`--socket <path>`	-	VMs unix socket path, default `/var/api/VMs.sock`
`--timeout <duration>`	-	Request timeout, default 30s

Version Information Example

vms --version

vms CLI v1.0.058

vms --version --json

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

Runtime Environment

VMs CLI is installed together with the VMs application. When the application is enabled, it links the CLI into the system's default PATH directory, so it can be used directly after logging in via SSH.

Item	Description
CLI file	`/Volume1/@apps/VMs/bin/vms`
Command path	`/usr/local/sbin/vms` (already in the system PATH)
Communication method	Local unix socket, default `/var/api/VMs.sock`
Intended for	Administrators logged in to the local machine

Notes:

The CLI is used to manage virtual machines on the local machine and does not support remotely managing other devices via the CLI.
The backend always returns HTTP 200; whether a command succeeds is determined by the code field in the response body, based on which the CLI converts it into an exit code.
Dangerous operations (deleting a virtual machine, deleting a network, deleting an image, deleting a repository) request confirmation in interactive mode, and in non-interactive mode --yes must be passed explicitly.

Command Summary Table

The following is a quick reference summary of all vms commands:

Parent command	Subcommand	Function description	Confirmation required	High risk
vms	--version	Display version information	No	No
vms vm	list	List all virtual machines	No	No
vms vm	get	View the details of a specified virtual machine	No	No
vms vm	list-resource	List the resources available for creating a virtual machine	No	No
vms vm	logs	View the operation logs of a virtual machine	No	No
vms vm	poweron	Start a virtual machine	No	No
vms vm	poweroff	Shut down a virtual machine (normal shutdown)	Yes	No
vms vm	force-poweroff	Force shut down a virtual machine	Yes	✅
vms vm	reboot	Reboot a virtual machine	No	No
vms vm	pause	Pause a virtual machine	No	No
vms vm	resume	Resume a paused virtual machine	No	No
vms vm	autorun	Set auto-start on boot	No	No
vms vm	clone	Clone a virtual machine	No	No
vms vm	export	Export a virtual machine as an OVA file	No	No
vms vm	delete	Delete a virtual machine	Yes	✅
vms vm disk	list	View the virtual disks of a virtual machine	No	No
vms vm snapshot	list	List the snapshots of a virtual machine	No	No
vms vm snapshot	create	Create a snapshot	No	No
vms vm snapshot	edit	Edit the snapshot description and lock status	No	No
vms vm snapshot	config	View the virtual machine configuration saved in a snapshot	No	No
vms vm snapshot	consistency	Preview snapshot consistency	No	No
vms vm	link	Obtain VNC console connection information	No	No
vms network	list	List virtual networks	No	No
vms network	get	View virtual network details	No	No
vms network	create	Create a virtual network	No	No
vms network	update	Update a virtual network	No	No
vms network	delete	Delete a virtual network	Yes	✅
vms network	list-interfaces	List network interfaces of a specified type	No	No
vms network	list-vnics	List the virtual NICs on a network	No	No
vms network	ovsinfo	View whether OVS is enabled	No	No
vms image	list	List images	No	No
vms image	edit	Edit image information	No	No
vms image	delete	Delete an image	Yes	✅
vms image	list-vms	View the virtual machines using the image	No	No
vms repo	list	List repositories	No	No
vms repo	get	View repository details	No	No
vms repo	update	Update the repository configuration	No	No
vms repo	delete	Delete a repository	Yes	✅
vms repo	list-volumes	List the available volumes	No	No
vms repo	list-vms	List the virtual machines in a repository	No	No
vms repo	check-running	Check the virtual machines running on a repository	No	No
vms repo	whether-exist-data	Check whether data exists in a repository	No	No
vms setting	get	View global settings	No	No
vms collectd	hostinfo	View host monitoring information	No	No
vms collectd	vminfo	View virtual machine monitoring information	No	No
vms collectd	storageinfo	View storage monitoring information	No	No

Command Reference

In the commands, <id> is the virtual machine ID, corresponding to the GUEST ID in the virtual machine list output; <network_id>, <image_id>, and <repo_id> are similar, and can be obtained through vms network list, vms image list, and vms repo list respectively.

About output examples: The table output of vms truncates overly long field values to a fixed width (ending with an ellipsis, and unrelated to the terminal width), for example VDISKS, VNICS, ISO IMAGES in the virtual machine configuration, as well as image names. Therefore, in this document, commands involving long fields uniformly provide a complete --json output example, while the remaining commands provide table output examples. When processing with scripts, it is also recommended to uniformly use --json.

I. Virtual Machine Query

vms vm list – List virtual machines

List all virtual machines on the local machine and their basic status.

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

--limit and --offset are pagination parameters
Output columns: name, virtual machine ID, running status, number of CPU cores, memory size (in KB), IP address

Output example:

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    -

Common STATUS values:

Status	Description
running	Running
shutdown	Shut down
saved	Paused (the running state has been saved to disk)

vms vm get – View virtual machine details

View the complete configuration and running status of a specified virtual machine.

vms vm get <id> --json

The output contains all configuration and running status fields of the virtual machine
Empty values such as no description or no IP are displayed as empty strings
When the virtual machine does not exist, the command returns an error and outputs error information

Output example:

{
  "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 – List the resources available for creating a virtual machine

View the resources the host can provide, such as firmware types, images, CPU, memory, networks, repositories, and passthrough-capable devices, for evaluation before creating a virtual machine.

vms vm list-resource --json

Returned fields: max_cpu_num, max_ram_size, usbs, pci_devices, networks, repos, images, video_cards, firmware, keyboard_layout.

Output example:

{
  "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 – View virtual machine operation logs

View the operation logs related to a specified virtual machine (power on/off, snapshots, editing, import/export, etc.).

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

--limit specifies the number of returned entries, default 50
--desc sorts in reverse chronological order (enabled by default)
Each log entry contains the time, level, category, operating user, and event description; the event description is the complete text
The event description (event) is output localized by the VMs service according to the device's system language; the examples in this document uniformly use English

Output example:

[
  {
    "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)"
  }
]

II. Virtual Machine Power Management

vms vm poweron – Start a virtual machine

vms vm poweron <id>

The virtual machine must be in the shut down state, otherwise a status conflict error is returned
Output: VM powered on: <id>

vms vm poweroff – Shut down a virtual machine

Send a normal shutdown request to the virtual machine, letting the system shut down gracefully.

vms vm poweroff <id> [--yes]

This is a dangerous operation: interactive mode asks for confirmation, and non-interactive mode must add --yes
The virtual machine must be in the running state, otherwise a status conflict error is returned

Interactive mode confirmation prompt:

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

Output: VM powered off: <id>

vms vm force-poweroff – Force shut down a virtual machine (high risk)

Force shut down the virtual machine, equivalent to cutting the power directly.

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

This is a high-risk operation: interactive mode asks for confirmation, and non-interactive mode must add --yes
It may cause data loss inside the virtual machine; it is recommended to use it only when the virtual machine is unresponsive

Interactive mode confirmation prompt:

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

Output: VM force powered off: <id>

vms vm reboot – Reboot a virtual machine

vms vm reboot <id>

Output: VM rebooted: <id>

vms vm pause – Pause a virtual machine

Freeze the running state of the virtual machine and save the current state to disk.

vms vm pause <id>

The virtual machine must be in the running state, otherwise a status conflict error is returned
After pausing, the virtual machine status is displayed as saved
Output: VM paused: <id>

vms vm resume – Resume a virtual machine

Restore the virtual machine from the paused state to the running state.

vms vm resume <id>

The virtual machine must be in the paused state, otherwise a status conflict error is returned
Output: VM resumed: <id>

vms vm autorun – Set auto-start on boot

Set whether the virtual machine automatically powers on when the host starts.

vms vm autorun <id> <true|false>

The second parameter must be true or false
The command reads the current configuration and only modifies the auto-start switch; other configurations are not affected
Output: Auto-start enabled for VM <id> or Auto-start disabled for VM <id>

III. Virtual Machine Clone, Export, and Delete

vms vm clone – Clone a virtual machine

Create a new virtual machine by copying an existing virtual machine as a template.

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

In the request body, guest_id is the source virtual machine ID, and name (or guest_name) is the new virtual machine name
The source virtual machine must be in the shut down state
--body passes the request body directly as a JSON string, and --file reads the request body from a file

vms vm export – Export a virtual machine

Export the virtual machine as an OVA file, for backup or migration to other virtualization platforms.

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

In the request body, guest_id is the source virtual machine ID, target_ova_path is the target file path, and ova_mode is an optional VMware compatibility mode
The source virtual machine must be in the shut down state
Export is a time-consuming task; exporting a large-capacity virtual machine takes a long time

vms vm delete – Delete a virtual machine (high risk)

Permanently delete a virtual machine.

vms vm delete <id> [--yes]

This is a high-risk operation: interactive mode asks for confirmation, and non-interactive mode must add --yes
It cannot be recovered after deletion; please confirm in advance that the data inside the virtual machine has been backed up

Interactive mode confirmation prompt:

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

Output: VM deleted: <id>

IV. Virtual Disks

vms vm disk list – View virtual disks

List all virtual disks of a specified virtual machine.

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

Output example:

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

VDISK MODE is the virtual disk controller type number; 1 indicates IDE
An unnamed virtual disk is displayed as - in the NAME column

V. Snapshot Management

vms vm snapshot list – List snapshots

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

Output example:

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 is the running state of the virtual machine at the time the snapshot was created
ACTUAL CONSISTENCY is the consistency type of the snapshot; filesystem indicates file system consistency, and crash indicates crash consistency

vms vm snapshot create – Create a snapshot

Create a snapshot for a virtual machine, for quickly rolling back or backing up the current state.

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

The request body is optional: description is the snapshot description, and locked is whether to lock
The snapshot name is automatically generated by the system according to the creation time
Snapshots occupy storage space; if not cleaned up for a long time, they may fill up the storage space, so regular cleanup is recommended

vms vm snapshot edit – Edit a snapshot

Modify the description or lock status of a snapshot.

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

Only the fields present in the request body are modified; fields not present retain their original values; changing only the description does not change the lock status, and vice versa

Output example:

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 – View the virtual machine configuration of a snapshot

View the virtual machine configuration saved in a snapshot.

vms vm snapshot config <id> <snapshot_name>

<id> is the virtual machine ID, and <snapshot_name> is the snapshot name, which can be obtained through vms vm snapshot list <id>.

Output example:

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 – Preview snapshot consistency

Preview the consistency type that may be obtained before creating a snapshot, helping determine whether it is suitable to create a snapshot at present.

vms vm snapshot consistency <id>

Output example:

PROPERTY          VALUE
CONSISTENCY TYPE  filesystem
REASON            vm_shutdown
VM STATE          shutdown

Creating a snapshot while the virtual machine is shut down yields a file system-consistent snapshot; while running, it is usually only possible to obtain a crash-consistent snapshot.

VI. Remote Console

vms vm link – Obtain VNC connection information

Obtain the connection information of the virtual machine VNC console, for opening the remote console in a browser.

vms vm link <id> --json

The virtual machine must be in the running or paused state, otherwise a status conflict error is returned

Output example:

{
  "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 is the console path relative to the NAS management address, port is the console service port, and https indicates whether access needs to go through HTTPS
In the JSON output, the & in the URL is escaped as \u0026

VII. Virtual Network Management

Network types are divided into two kinds:

Type	Description
Private (private)	An internal network only for communication between virtual machines on the local machine, not bound to a physical NIC
External (external)	A network bound to a physical NIC, through which virtual machines can communicate with the outside

vms network list – List virtual networks

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

Output example:

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 is the number of virtual machines connected to the network, and NUM INTERFACES is the number of selected physical NICs

vms network get – View virtual network details

vms network get <network_id> --json

Output example:

{
  "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 is the NIC information bound to the network, organized by host ID, and checked indicates whether the NIC is selected
metadata records the creation and update times of the network

vms network create – Create a virtual network

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

Create a private network:

The request body must contain name, type (private), and host_name or host_id, specifying on which host the network is created
Before creating, you can view the available hosts through vms network list-interfaces private

Create an external network:

The request body must contain name, type (external), and vlan_id, and at least one physical NIC must be specified
The NIC can be specified through interface_name (such as LAN 1) or interface_id; when the NIC name is not unique across hosts, it must be used together with host_name
Before creating, you can view the available NICs through vms network list-interfaces external

The output is the network information after creation, consistent with the structure of 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
}

When no NIC is specified, the command gives a prompt:

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 – Update a virtual network

Submit only the fields that need to be modified; fields not submitted retain their original values.

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

The request body must contain network_id
The command first reads the current network configuration and merges the submitted fields; the network name and selected NICs will not be cleared
The output is the updated network information

vms network delete – Delete a virtual network (high risk)

vms network delete <network_id> [--yes]

This is a high-risk operation: interactive mode asks for confirmation, and non-interactive mode must add --yes
Deleting a network disconnects all virtual machines connected to that network
It is recommended to first confirm the connected virtual machines through vms network list-vnics <network_id>

Interactive mode confirmation prompt:

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

Output: Network deleted: <network_id>

vms network list-interfaces – List network interfaces

List network interfaces of a specified type.

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

external returns the physical NICs available on the host
private returns the host information available for creating a private network

Output example (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

Output example (private):

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

vms network list-vnics – List the virtual NICs on a network

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

Output example:

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 – View OVS status

Confirm whether the Open vSwitch virtual switch is enabled.

vms network ovsinfo [--json]

Output example:

PROPERTY  VALUE
RESULT    true

VALUE being true indicates that OVS is enabled.

VIII. Image Management

vms image list – List images

List the system image files available for creating virtual machines.

vms image list --json

image_name is the image name, and file_name is the corresponding file name
type is the image format, such as iso or qcow2
status is the image status; available indicates available
repos is the repository where the image is located
progress is the progress of the image processing task; 0 indicates no task in progress

Output example:

{
  "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 – Edit an image

Modify the image name, or adjust the repository where the image is located.

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"}'

The request body must contain image_id and repos; repos is the complete list of target repositories of the image and cannot be empty
image_name, file_name, type, and file_size are optional fields; when not provided, the current values are used
An empty repos would cause the image to be removed from all repositories; the command rejects the request before execution
Output: Image updated

vms image delete – Delete an image (high risk)

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

--image-id is required
This is a high-risk operation: interactive mode asks for confirmation, and non-interactive mode must add --yes
Deleting an image does not affect virtual machines already created, but it affects subsequently creating virtual machines based on that image
It is recommended to first confirm the usage through vms image list-vms --image-id <image_id>

Interactive mode confirmation prompt:

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

Output: Image deleted: <image_id>

vms image list-vms – View the virtual machines using the image

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

Output example:

GUEST NAME
1454486

Before deleting an image, you can run this command to confirm the scope of impact; when no virtual machine uses the image, the output is empty.

IX. Repository Management

vms repo list – List repositories

vms repo list [--json]

Output example:

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 – View repository details

vms repo get <repo_id> [--json]

Output example:

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 is the volume where the repository is located
SOFT LIMIT and HARD LIMIT are capacity warning thresholds (percentage)
ENABLE LOWER NOTIFY is whether the low-capacity reminder is enabled

vms repo update – Update a repository

Submit only the fields that need to be modified; fields not submitted retain their original values.

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

The repository ID can be passed through repo_id or repoId
The command first reads the current configuration and merges the submitted fields; other settings will not be lost
The output is the updated repository information

vms repo delete – Delete a repository (high risk)

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

The second parameter is need_save_data: true indicates keeping the data files on the disk, and false indicates deleting them together with the data
This is a high-risk operation: interactive mode asks for confirmation, and non-interactive mode must add --yes
Deleting a repository also removes the virtual machines and images within it; it is recommended to first run vms repo check-running and vms repo whether-exist-data to confirm the scope of impact

Interactive mode confirmation prompt:

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

Output: Repository deleted: <repo_id>

vms repo list-volumes – List the available volumes

List the volumes available for creating a repository.

vms repo list-volumes [--json]

Output example:

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 – List the virtual machines in a repository

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

The repository ID can be passed through repo_id or repoId
The command first obtains the repository object and then queries its virtual machines, making the result more reliable

vms repo check-running – Check the virtual machines running on a repository

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

Run this before deleting a repository to confirm that no virtual machine is running; when there is no running virtual machine, the output is empty.

vms repo whether-exist-data – Check whether there is data in a repository

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

Run this before deleting a repository to confirm whether there is still data in the repository; consistent with the pre-check before deleting a repository in the web interface.

X. Global Settings

vms setting get – View global settings

View the global configuration of the VMs application.

vms setting get [--json]

Output example:

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

HOST SHUTDOWN BEHAVIOR is how virtual machines are handled when the host shuts down
KB LAYOUT is the keyboard layout of the virtual machine

XI. Monitoring Information Query

vms collectd hostinfo – View host monitoring information

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

Output example:

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

vms collectd vminfo – View virtual machine monitoring information

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

Output example:

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 – View storage monitoring information

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

Output example:

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

Interactive Mode and Non-interactive Mode

The CLI determines whether it is currently running in a terminal environment and adopts different behaviors:

Interactive Mode (terminal environment)

Dangerous operations display a confirmation prompt, with the default option being No
Enter y or Y to continue execution, and enter n or press Enter directly to cancel
When an operation is cancelled, it outputs Operation cancelled with exit code 99

Non-interactive Mode (script/automation)

Dangerous operations must use --yes to skip confirmation, otherwise the command directly errors out and returns exit code 1
There is no waiting for input when there is no terminal environment, suitable for scripts and scheduled task invocation
It is recommended to explicitly handle exit codes in scripts to distinguish between success, failure, and status conflict

JSON Output Format

Query commands support the --json parameter, outputting normalized JSON data that is convenient for program parsing.

Format conventions:

Field names use snake_case
Boolean values are true/false
Time uses the ISO 8601 format, including nanosecond precision and the UTC+8 offset (such as 2026-09-02T11:43:51.176535374+08:00)
JSON is output to stdout, and error information is output to stderr
Long fields that are truncated in the table output are complete values in the JSON output

Example:

vms setting get --json

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

The JSON structures of different commands differ slightly: vms vm list, vms vm snapshot list, and vms vm logs output arrays directly; the other list-type commands output objects containing totalCount and a data field, and the data field name varies by resource (such as items, hosts, vms, storage). For example, 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"
    }
  }
}

The JSON output of some commands is a simple value, for example vms network ovsinfo --json outputs true, and vms vm pause --json outputs null.

Exit Code Description

Exit code	Meaning	Typical scenario
0	Success	The command completes normally
1	Parameter error	Missing required parameter, wrong parameter format, or `--yes` not added
3	Resource not found	The command's pre-check fails, for example the specified image does not exist
4	Status conflict	The current status of the virtual machine does not allow the operation (such as shutting down a virtual machine that is already shut down)
6	Connection error	Unable to connect to the VMs service, or the socket path is incorrect
7	Timeout	The request timed out; this can be adjusted through `--timeout`
9	Execution error	The backend returns an error (the error message contains code_num and the error description)
99	User cancelled	Choosing No or pressing Enter directly in the interactive confirmation

Example:

# 退出码 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

Usage Scenarios

Daily Operations

# 查看所有虚拟机状态
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>

Batch Scripting

# 批量启动所有已关机的虚拟机
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'

Backup and Inspection

# 关机后为虚拟机创建快照
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"}'

Pre-deletion Checks

# 删除存储空间前，先确认是否有虚拟机正在运行、是否存在数据
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 Tool Invocation

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

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

Internal Development and System Integration

# 开发人员可通过 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 @-

FAQ

Q: Does the CLI need additional installation?

No. The CLI is installed together with the VMs application; after the application is enabled, simply execute the vms command to use it.

Q: Must the CLI be used through SSH?

No. The CLI can be invoked through any command-line terminal, including local terminals, remote SSH, scripts, AI tools, etc.

Q: Can the CLI manage virtual machines on other devices?

No. The CLI communicates with the VMs service through a local unix socket and is only used to manage virtual machines on the local machine.

Q: Why do some commands prompt for confirmation while others do not?

Operations such as deleting a virtual machine, deleting a network, deleting an image, deleting a repository, and shutting down (poweroff, force-poweroff) affect data or services, so they require confirmation by default; start, reboot, pause, resume, and query-type commands have no such restrictions.

Q: How do I confirm dangerous operations in non-interactive mode?

All dangerous operations must add the --yes parameter, otherwise the command errors out and exits (exit code 1).

Q: How do I determine in a script whether a command executed successfully?

Determine it by the exit code: 0 indicates success, and a non-0 indicates failure. You can also parse the output of --json.

Q: Why is the list output by --json an object?

The JSON output of some commands is organized as an object by ID, with a totalCount field attached, making it convenient to access directly by ID.

More Help

Every command supports --help to view detailed usage:

vms --help
vms vm --help
vms vm poweroff --help
vms network create --help

Introduction​

Key Features​

Quick Start​

Global Options​

Version Information Example​

Runtime Environment​

Command Summary Table​

Command Reference​

I. Virtual Machine Query​

vms vm list – List virtual machines​

vms vm get – View virtual machine details​

vms vm list-resource – List the resources available for creating a virtual machine​

vms vm logs – View virtual machine operation logs​

II. Virtual Machine Power Management​

vms vm poweron – Start a virtual machine​

vms vm poweroff – Shut down a virtual machine​

vms vm force-poweroff – Force shut down a virtual machine (high risk)​

vms vm reboot – Reboot a virtual machine​

vms vm pause – Pause a virtual machine​

vms vm resume – Resume a virtual machine​

vms vm autorun – Set auto-start on boot​

III. Virtual Machine Clone, Export, and Delete​

vms vm clone – Clone a virtual machine​

vms vm export – Export a virtual machine​

vms vm delete – Delete a virtual machine (high risk)​

IV. Virtual Disks​

vms vm disk list – View virtual disks​

V. Snapshot Management​

vms vm snapshot list – List snapshots​

vms vm snapshot create – Create a snapshot​

vms vm snapshot edit – Edit a snapshot​

vms vm snapshot config – View the virtual machine configuration of a snapshot​

vms vm snapshot consistency – Preview snapshot consistency​

VI. Remote Console​

vms vm link – Obtain VNC connection information​

VII. Virtual Network Management​

vms network list – List virtual networks​

vms network get – View virtual network details​

vms network create – Create a virtual network​

vms network update – Update a virtual network​

vms network delete – Delete a virtual network (high risk)​

vms network list-interfaces – List network interfaces​

vms network list-vnics – List the virtual NICs on a network​

vms network ovsinfo – View OVS status​

VIII. Image Management​

vms image list – List images​

vms image edit – Edit an image​

vms image delete – Delete an image (high risk)​

vms image list-vms – View the virtual machines using the image​

IX. Repository Management​

vms repo list – List repositories​

vms repo get – View repository details​

vms repo update – Update a repository​

vms repo delete – Delete a repository (high risk)​

vms repo list-volumes – List the available volumes​

vms repo list-vms – List the virtual machines in a repository​

vms repo check-running – Check the virtual machines running on a repository​

vms repo whether-exist-data – Check whether there is data in a repository​

X. Global Settings​

vms setting get – View global settings​

XI. Monitoring Information Query​

vms collectd hostinfo – View host monitoring information​

vms collectd vminfo – View virtual machine monitoring information​

vms collectd storageinfo – View storage monitoring information​

Interactive Mode and Non-interactive Mode​

Interactive Mode (terminal environment)​

Non-interactive Mode (script/automation)​

JSON Output Format​

Exit Code Description​

Usage Scenarios​

Daily Operations​

Batch Scripting​

Backup and Inspection​

Pre-deletion Checks​

AI Tool Invocation​

Internal Development and System Integration​

FAQ​

More Help​

Introduction

Key Features

Quick Start

Global Options

Version Information Example

Runtime Environment

Command Summary Table

Command Reference

I. Virtual Machine Query

vms vm list – List virtual machines

vms vm get – View virtual machine details

vms vm list-resource – List the resources available for creating a virtual machine

vms vm logs – View virtual machine operation logs

II. Virtual Machine Power Management

vms vm poweron – Start a virtual machine

vms vm poweroff – Shut down a virtual machine

vms vm force-poweroff – Force shut down a virtual machine (high risk)

vms vm reboot – Reboot a virtual machine

vms vm pause – Pause a virtual machine

vms vm resume – Resume a virtual machine

vms vm autorun – Set auto-start on boot

III. Virtual Machine Clone, Export, and Delete

vms vm clone – Clone a virtual machine

vms vm export – Export a virtual machine

vms vm delete – Delete a virtual machine (high risk)

IV. Virtual Disks

vms vm disk list – View virtual disks

V. Snapshot Management

vms vm snapshot list – List snapshots

vms vm snapshot create – Create a snapshot

vms vm snapshot edit – Edit a snapshot

vms vm snapshot config – View the virtual machine configuration of a snapshot

vms vm snapshot consistency – Preview snapshot consistency

VI. Remote Console

vms vm link – Obtain VNC connection information

VII. Virtual Network Management

vms network list – List virtual networks

vms network get – View virtual network details

vms network create – Create a virtual network

vms network update – Update a virtual network

vms network delete – Delete a virtual network (high risk)

vms network list-interfaces – List network interfaces

vms network list-vnics – List the virtual NICs on a network

vms network ovsinfo – View OVS status

VIII. Image Management

vms image list – List images

vms image edit – Edit an image

vms image delete – Delete an image (high risk)

vms image list-vms – View the virtual machines using the image

IX. Repository Management

vms repo list – List repositories

vms repo get – View repository details

vms repo update – Update a repository

vms repo delete – Delete a repository (high risk)

vms repo list-volumes – List the available volumes

vms repo list-vms – List the virtual machines in a repository

vms repo check-running – Check the virtual machines running on a repository

vms repo whether-exist-data – Check whether there is data in a repository

X. Global Settings

vms setting get – View global settings

XI. Monitoring Information Query

vms collectd hostinfo – View host monitoring information

vms collectd vminfo – View virtual machine monitoring information

vms collectd storageinfo – View storage monitoring information

Interactive Mode and Non-interactive Mode

Interactive Mode (terminal environment)

Non-interactive Mode (script/automation)

JSON Output Format

Exit Code Description

Usage Scenarios

Daily Operations

Batch Scripting

Backup and Inspection

Pre-deletion Checks

AI Tool Invocation

Internal Development and System Integration

FAQ

More Help