Operate Vmos Edge CLI

Operate VMOS Edge CLI

Overview

CLI tool for controlling the VMOS Edge Desktop Electron app — manage Android virtual devices on edge hosts, automate the desktop UI via CDP, and orchestrate device workflows.

When to Use

• Creating, starting, stopping, or deleting Android virtual devices on edge hosts
• Automating the VMOS Edge Desktop Electron UI via CDP
• Writing YAML playbooks or batch JSON for device workflows
• Recovering from vmos-edge-cli error codes
• Installing or verifying the vmos-edge-cli tool

Not for: raw ADB commands, Appium, Android Studio emulators, or any non-VMOS Android tooling.

Preflight

GATE — complete before any other command. Do not skip.

# 1. Node.js 18+ required
node --version

# 2. Check CLI
vmos-edge-cli --version

# 3. If CLI missing → install
npm i -g @vmosedge/cli

# 4. Verify
vmos-edge-cli schema

Do not substitute node dist/main.js, pnpm build, or pnpm link. The only supported install path is npm i -g @vmosedge/cli.

The manual steps above and the automated script (scripts/ensure-installed.mjs) run the same flow — use either. See invocation-preflight.md for platform paths and edge cases.

Critical Rules

1. ALWAYS ui state to inspect, NEVER screenshot — state is free and structured. screenshot costs vision tokens. Only screenshot when user asks to save an image.
2. ALWAYS ui click/type to interact, NEVER eval to click/type — eval bypasses scroll and CDP fallback, fails on off-screen elements.
3. ALWAYS ui state after page changes — after click, goto, back. Never reuse stale indices.
4. ALWAYS batch consecutive safe actions — if each step is safe regardless of others' results, batch them. Never run them as separate calls.
5. NEVER mix mutating commands in one batch — create, delete, start, stop, reset each as a separate direct call. Check result before issuing the next command. One command may target multiple items (device start id1 id2, --count 5) — the boundary is between commands, not between targets.
6. ALWAYS schema before writing batch/YAML — never guess param names. Positional CLI args have different names in batch/YAML that are not guessable. Run schema <domain> to discover exact names and types.
7. Every device/image command needs --host <ip> — host commands take <ip> as positional arg.

Core Workflow

The app stays running between commands — no need to app start every time.

1. Preflight → see Preflight section above. Must pass before continuing.
2. Inspect → ui state, device list, host info, etc.
3. Act → direct for single/mutating, batch for consecutive safe actions, run for reusable flows
4. Parse → success: read data. Failure: branch on code (see error-recovery.md)
5. Verify → ui state after page changes, ui form-state after typing, device info after mutations

Quick Reference

Terminal uses spaces. YAML and batch use dots. Variable syntax is not interchangeable.

Reference Map

Use the Read tool on these files when the condition applies — do not work from memory.

• references/page-map.md — read first when navigating the desktop UI: page routes, hidden features, how to reveal menus/panels/dialogs
• references/command-patterns.md — three invocation modes (direct / batch / run), full command reference
• references/ui-automation.md — element selection, action list, cost guide
• references/error-recovery.md — error codes and deterministic recovery
• references/invocation-preflight.md — automated helper script, platform paths, install edge cases

Common Pitfalls