@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.