operate-vmos-edge-cli
Use when a task involves VMOS Edge Desktop — creating or controlling Android virtual devices on edge hosts, interacting with the Electron desktop UI via CDP, automating device workflows with YAML playbooks or batch JSON, or recovering from CLI error codes.
How do I install this agent skill?
npx skills add https://github.com/vmos-dev/vmos-edge-skills --skill operate-vmos-edge-cliIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill installs and operates a CLI tool for managing Android virtual devices. It performs global package installations and executes commands on remote hosts as part of its documented functionality.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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-clierror codes - Installing or verifying the
vmos-edge-clitool
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
| Check fails | Action |
|---|---|
node not found | Stop. Tell user to install Node.js 18+. |
npm not found | Stop. Tell user to install npm (bundled with Node.js). |
vmos-edge-cli not found | Run npm i -g @vmosedge/cli, then verify with schema. |
schema fails after install | Report error and stop. Do not improvise fallbacks. |
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
- ALWAYS
ui stateto inspect, NEVERscreenshot—stateis free and structured.screenshotcosts vision tokens. Only screenshot when user asks to save an image. - ALWAYS
ui click/typeto interact, NEVERevalto click/type —evalbypasses scroll and CDP fallback, fails on off-screen elements. - ALWAYS
ui stateafter page changes — afterclick,goto,back. Never reuse stale indices. - ALWAYS batch consecutive safe actions — if each step is safe regardless of others' results, batch them. Never run them as separate calls.
- NEVER mix mutating commands in one batch —
create,delete,start,stop,reseteach 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. - ALWAYS
schemabefore writing batch/YAML — never guess param names. Positional CLI args have different names in batch/YAML that are not guessable. Runschema <domain>to discover exact names and types. - Every
device/imagecommand needs--host <ip>—hostcommands take<ip>as positional arg.
Core Workflow
The app stays running between commands — no need to app start every time.
- Preflight → see Preflight section above. Must pass before continuing.
- Inspect →
ui state,device list,host info, etc. - Act → direct for single/mutating, batch for consecutive safe actions, run for reusable flows
- Parse → success: read
data. Failure: branch oncode(see error-recovery.md) - Verify →
ui stateafter page changes,ui form-stateafter typing,device infoafter mutations
Quick Reference
| Context | Format | Example |
|---|---|---|
| Terminal | vmos-edge-cli <domain> <method> | vmos-edge-cli ui eval "1+1" |
YAML action: | domain.method | action: ui.eval |
batch JSON | domain.method | {"action":"ui.eval"} |
| YAML variable | ${{ expr }} | ${{ devices[0].id }} |
batch variable | $expr | $devices[0].id |
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
| Mistake | Fix |
|---|---|
ui screenshot to inspect page | Use ui state — free, structured, has [N] indices |
ui eval "el.click()" | Use ui click <N> — handles scroll + CDP fallback |
| Reuse indices after page navigation | Run ui state again to get fresh indices |
host check 10.0.0.5 then host info 10.0.0.5 as 2 calls | Batch them: one call, both safe to run unconditionally |
| Guess batch/YAML param names from CLI syntax | Positional args have different names. Run schema <domain> first |
device create then device start in one batch | Never — different mutating commands must be separate calls |
| Type into field without verifying | ui form-state after typing to confirm value |
app start on every command | App persists — check app status first |
ui state output too long on complex page | ui state --interactive-only, or batch with interactiveOnly: true |
| Skip preflight, run CLI commands directly | CLI may not be installed. Always run Preflight gate first |
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/vmos-dev/vmos-edge-skills/operate-vmos-edge-cli">View operate-vmos-edge-cli on skillZs</a>