@vmosedge/cli

@vmosedge/cli

VMOS Edge Desktop CLI. Designed for AI agents — all output is JSON.

Install

npm install -g @vmosedge/cli

Setup

# Set app path (required before app start)
vmos-edge-cli config set app.bin-path "/Applications/VMOS Edge 2.0.app"  # macOS
vmos-edge-cli config set app.bin-path "C:\Program Files\VMOS Edge 2.0\VMOS Edge 2.0.exe"  # Windows

# Start app
vmos-edge-cli app start
vmos-edge-cli app wait-ready

Three Invocation Modes

	Direct	Batch	Run
CLI	vmos-edge-cli device list --host <ip>	vmos-edge-cli batch '<json>'	vmos-edge-cli run <file.yaml>
Notation	spaces: device list	dots: device.list	dots: device.list
Params	CLI flags: --host <ip>	JSON: "args":{"host":"..."}	YAML: args: { host: "..." }
Variables	—	$name.path	${{ name.field }}

Key rule: Consecutive actions safe to run unconditionally → batch. Actions that require result inspection → direct, one at a time.

# ❌ 3 separate calls
vmos-edge-cli device list --host 10.0.0.5
vmos-edge-cli image list --host 10.0.0.5
vmos-edge-cli host hardware 10.0.0.5

# ✅ 1 batch call
vmos-edge-cli batch '[
  {"action":"device.list","args":{"host":"10.0.0.5"}},
  {"action":"image.list","args":{"host":"10.0.0.5"}},
  {"action":"host.hardware","args":{"ip":"10.0.0.5"}}
]'

Commands

Device

vmos-edge-cli device list --host <ip>
vmos-edge-cli device create --host <ip> --image <repo> --name <name> --count 3 --start
vmos-edge-cli device info --host <ip> <id>
vmos-edge-cli device start --host <ip> <ids...>
vmos-edge-cli device stop --host <ip> <ids...>
vmos-edge-cli device restart --host <ip> <ids...>
vmos-edge-cli device reset --host <ip> <ids...>       # Factory reset (data erased)
vmos-edge-cli device delete --host <ip> <ids...>
vmos-edge-cli device rename --host <ip> <id> <name>
vmos-edge-cli device shell --host <ip> <id> "ls /sdcard"
vmos-edge-cli device screenshot --host <ip> <id> -o shot.png

Host

vmos-edge-cli host check <ip>
vmos-edge-cli host info <ip>
vmos-edge-cli host hardware <ip>
vmos-edge-cli host network <ip>
vmos-edge-cli host templates <ip>
vmos-edge-cli host list --hosts <ip,ip,...>

App

vmos-edge-cli app start [--cdp-port <port>]
vmos-edge-cli app stop
vmos-edge-cli app status
vmos-edge-cli app wait-ready [-t <ms>]       # Default 30s

Image

vmos-edge-cli image list --host <ip>

UI Automation

vmos-edge-cli ui state                        # Page snapshot with [N] indices
vmos-edge-cli ui click <target>
vmos-edge-cli ui type <target> <text>
vmos-edge-cli ui native-type <text>           # CJK/IME safe, click to focus first
vmos-edge-cli ui native-key <key> [-m Ctrl]   # Modifier key support
vmos-edge-cli ui click-precise <target>       # CDP getContentQuads
vmos-edge-cli ui press-key <key>
vmos-edge-cli ui select <target> <value>
vmos-edge-cli ui hover <target>
vmos-edge-cli ui goto <url>
vmos-edge-cli ui back
vmos-edge-cli ui scroll <direction>
vmos-edge-cli ui scroll-to <target>
vmos-edge-cli ui wait <target>
vmos-edge-cli ui wait-text <text>
vmos-edge-cli ui upload <files...> [-t <target>]
vmos-edge-cli ui dialog [--accept|--dismiss]
vmos-edge-cli ui windows
vmos-edge-cli ui form-state
vmos-edge-cli ui network
vmos-edge-cli ui screenshot -o ui.png
vmos-edge-cli ui eval <expression>
vmos-edge-cli ui cdp <method> [json-params]

Other

vmos-edge-cli schema                          # All actions, params, error codes
vmos-edge-cli batch '<json>'                  # Multiple actions in one call
vmos-edge-cli run <file.yaml>                 # YAML playbook
vmos-edge-cli run <file.yaml> --dry-run
vmos-edge-cli run <file.yaml> --report html
vmos-edge-cli config show | set | get

Element Selection (Index-First)

ui state marks each interactive element with [N] (starting from 1). Use the index as default target:

vmos-edge-cli ui state        # Read indices
vmos-edge-cli ui click 3      # Click element [3]

Fallback to semantic selectors when index is impractical:

Selector	Example
text=	"text=Save"
placeholder=	"placeholder=Enter email"
role=	"role=button text=OK"
testid=	"testid=submit-btn"
label=	"label=Username"
CSS	"button.primary"

Param Name Convention

CLI flags use --kebab-case. Batch/YAML args use snake_case:

--device-type → device_type, --adi-name → adi_name, -o → output

Output Format

All commands return JSON:

{"ok": true, "data": ...}
{"ok": false, "error": "...", "code": "HOST_UNREACHABLE"}

Error Codes

Code	Exit	Action
HOST_NOT_SET	2	Pass --host <ip>
INVALID_ARGS	2	Fix params
DEVICE_NOT_FOUND	66	device list for correct ID
IMAGE_NOT_FOUND	66	image list for correct image
ELEMENT_NOT_FOUND	66	ui state to refresh indices
APP_NOT_RUNNING	69	app start
HOST_UNREACHABLE	69	Check network
CDP_NOT_READY	69	Wait for app startup
TIMEOUT	75	Retry
TRANSIENT	75	Retry once, then inspect state
OPERATION_FAILED	1	Check error message
ASSERTION_FAILED	1	Re-inspect state
CONFIG_MISSING	78	config set
UNKNOWN	1	Check raw error

47 actions — run vmos-edge-cli schema for full details.