operate-vmos-edge-cli

VMOS Edge CLI の操作

概要

VMOS Edge Desktop Electron アプリを制御する CLI ツールです。エッジホスト上の Android 仮想デバイスを管理し、CDP 経由でデスクトップ UI を自動化し、デバイスのワークフローをオーケストレーションします。

使用する場面

• エッジホスト上で Android 仮想デバイスを作成、起動、停止、削除する場合
• CDP 経由で VMOS Edge Desktop Electron UI を自動化する場合
• デバイスのワークフロー用に YAML プレイブックやバッチ JSON を作成する場合
• vmos-edge-cli のエラーコードから復旧する場合
• vmos-edge-cli ツールをインストールまたは確認する場合

対象外： 生の ADB コマンド、Appium、Android Studio エミュレーター、または VMOS 以外の Android ツール。

事前確認

ゲート — ほかのコマンドを実行する前に完了してください。省略しないでください。

# 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

確認に失敗した場合	対処
node が見つからない	停止します。 Node.js 18 以降をインストールするようユーザーに伝えてください。
npm が見つからない	停止します。 npm（Node.js に同梱）をインストールするようユーザーに伝えてください。
vmos-edge-cli が見つからない	npm i -g @vmosedge/cli を実行し、続けて schema で確認します。
インストール後に schema が失敗する	エラーを報告して停止します。代替手段を独自に試さないでください。

node dist/main.js、pnpm build、pnpm link に置き換えないでください。サポートされている唯一のインストール方法は npm i -g @vmosedge/cli です。

上記の手動手順と自動スクリプト（scripts/ensure-installed.mjs）は同じフローを実行します。どちらか一方を使用してください。プラットフォームごとのパスと例外については、invocation-preflight.md を参照してください。

重要なルール

1. 必ず ui state で確認し、screenshot は使わないでください — state は無料で構造化されています。screenshot はビジョントークンを消費します。スクリーンショットは、ユーザーから画像の保存を求められた場合にのみ使用してください。
2. 操作には必ず ui click／type を使い、クリックや入力に eval は使わないでください — eval はスクロールと CDP フォールバックを迂回するため、画面外の要素では失敗します。
3. ページが変わった後は必ず ui state を実行してください — click、goto、back の後に実行します。古いインデックスを再利用しないでください。
4. 安全な連続操作は必ずバッチ処理してください — 各ステップがほかのステップの結果にかかわらず安全であれば、バッチ処理します。個別の呼び出しとして実行しないでください。
5. 変更を伴うコマンドを同じバッチに混在させないでください — create、delete、start、stop、reset はそれぞれ個別に直接呼び出します。次のコマンドを実行する前に結果を確認してください。1 つのコマンドで複数の対象を指定することはできます（device start id1 id2、--count 5 など）。境界は対象の間ではなく、コマンドの間です。
6. バッチ／YAML を作成する前に必ず schema を実行してください — パラメーター名を推測しないでください。位置指定の CLI 引数とバッチ／YAML で使う名前は異なり、推測できません。正確な名前と型を確認するには schema <domain> を実行してください。
7. すべての device／image コマンドには --host <ip> が必要です — host コマンドでは <ip> を位置引数として指定します。

基本的なワークフロー

コマンド間でアプリは起動したままなので、毎回 app start を実行する必要はありません。

1. 事前確認 → 上記の事前確認セクションを参照してください。続行する前に必ず合格してください。
2. 確認 → ui state、device list、host info などを実行します。
3. 操作 → 単一の操作や変更を伴う操作には直接呼び出し、安全な連続操作にはバッチ、再利用可能なフローには run を使います。
4. 解析 → 成功した場合は data を読み取ります。失敗した場合は code に基づいて分岐します（error-recovery.md を参照）。
5. 検証 → ページが変わった後は ui state、入力後は ui form-state、変更後は device info を実行します。

クイックリファレンス

コンテキスト	形式	例
ターミナル	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 変数	${{ expr }}	${{ devices[0].id }}
batch 変数	$expr	$devices[0].id

ターミナルではスペースを使用します。YAML と batch ではドットを使用します。変数の構文は相互に置き換えられません。

リファレンスマップ

条件に該当する場合は、これらのファイルで Read ツールを使用してください。記憶に頼って作業しないでください。

• references/page-map.md — デスクトップ UI を操作する際は、まず読みます。ページのルート、隠し機能、メニュー／パネル／ダイアログの表示方法を記載しています
• references/command-patterns.md — 3 つの呼び出しモード（直接／バッチ／実行）と、コマンドの完全なリファレンス
• references/ui-automation.md — 要素の選択、アクション一覧、コストガイド
• references/error-recovery.md — エラーコードと決定論的な復旧方法
• references/invocation-preflight.md — 自動ヘルパースクリプト、プラットフォームのパス、インストール時の例外ケース

よくある落とし穴

間違い	対処法
ページを確認するために ui screenshot を使う	ui state を使います。無料で構造化されており、[N] インデックスも表示されます
ui eval "el.click()" を使う	ui click <N> を使います。スクロールと CDP フォールバックに対応しています
ページ遷移後もインデックスを再利用する	ui state を再実行して、新しいインデックスを取得します
host check 10.0.0.5 の後に host info 10.0.0.5 を 2 回に分けて呼び出す	バッチ処理します。1 回の呼び出しで、どちらも無条件に安全に実行できます
CLI の構文からバッチ／YAML のパラメーター名を推測する	位置引数の名前は異なります。最初に schema <domain> を実行します
1 つのバッチ内で device create の後に device start を実行する	絶対に避けてください。変更を伴う別々のコマンドは、個別に呼び出す必要があります
値を確認せずにフィールドへ入力する	入力後に ui form-state を実行して、値を確認します
すべてのコマンドで app start を実行する	アプリは起動したままです。まず app status を確認します
複雑なページで ui state の出力が長すぎる	ui state --interactive-only を使うか、interactiveOnly: true を指定してバッチ処理します
プリフライトを省略し、CLI コマンドを直接実行する	CLI がインストールされていない可能性があります。必ず最初にプリフライトゲートを実行してください