mobilecli

Mobile CLI

iOS および Android のデバイス、シミュレーター、エミュレーター、モバイルアプリ向けの汎用自動化・管理スキルです。このスキルでは、mobilecli コマンドラインインターフェイスを使って、デバイスの操作、アプリの自動化、ジェスチャーの実行、画面状態のキャプチャ、WebView の調査を行う方法を説明します。

---

インストール

最初のデバイスコマンドを実行する前に、mobilecli バイナリが存在することを確認してください。見つからない場合は、npm でグローバルにインストールします。事前にユーザーへ確認する必要はありません。インストールは想定されています。

command -v mobilecli >/dev/null || npm install -g mobilecli@latest
mobilecli --version

npm install -g が権限エラーで失敗する場合は、sudo npm install -g mobilecli@latest で再試行するか、ユーザーに確認してください。mobilecli がエージェントの PATH にないものの、ユーザーがインストール済みだと言う場合は、npm bin -g（または npm prefix -g）を実行し、そこで見つかったバイナリを使用してください。

コマンドを実行するたびに npx mobilecli@latest を使わないでください。実行のたびにパッケージが再解決され、自動化が遅くなります。

各デバイスコマンドはバックグラウンドデーモンと通信します（自動起動し、アイドル状態が30分続くと終了します。mobilecli daemon status|stop）。セットアップは不要です。

プラットフォームの前提条件（このマシンでユーザーがすでにデバイスを使用している場合は、対応済みです）：

• Android：PATH に adb があること（brew install --cask android-platform-tools）。
• iOS シミュレーター：起動済みのシミュレーターがある Xcode。

---

クイックスタート（概要）

すぐに作業を開始してください。最初に --help や --version で調査しないでください。

# 1. List devices and note the device id. This starts the background daemon,
#    which keeps devices, tunnels and agents alive so following commands are fast.
mobilecli devices

# 2. Boot the target device (only if offline)
mobilecli device boot --device <device-id>

# 3. Launch the app and dump the UI in one go. Every element gets a ref like @e5.
mobilecli apps launch com.example.myapp --device <device-id> && \
  mobilecli snapshot --device <device-id>

# 4. Act on a ref, then re-dump to verify. Chain with && so one bash call does both.
mobilecli io tap @e5 --device <device-id> && \
  mobilecli snapshot --device <device-id>

# 5. Confirm visually when needed
mobilecli screenshot --device <device-id> --output screenshot.png

コマンドの連結

mobilecli の呼び出しはそれぞれ別のプロセスなので、関連する手順は1回の bash 呼び出しで && を使って連結してください。&& は最初の失敗時に連結処理を停止します。自動化ではこれが望ましい動作です。

# fill a login form and check the result with one bash call
mobilecli io tap @e3 --device <id> && mobilecli io text "[email protected]" --device <id> && \
mobilecli io tap @e4 --device <id> && mobilecli io text "secret" --device <id> && \
mobilecli io tap @e7 --device <id> && sleep 1 && mobilecli snapshot --device <id>

参照（@e1、@e2 など）は、直近の snapshot または dump ui によって番号が付けられます。タップ、テキスト入力、またはナビゲーションを行うとツリーが変わることがあるため、参照を再利用する前にもう一度ダンプしてください。読み取りには snapshot（テキスト）を、rect 座標が必要な場合や出力をスクリプトで処理する場合には dump ui（JSON）を使用してください。

---

AI 自動化ワークフロー

モバイルの自動化またはアプリのテストを実行する際は、次の構造化されたループに従ってください。

graph TD
    A[List Devices & Select Target] --> B[Launch Target Application]
    B --> C[Inspect State: UI Tree / Screenshot]
    C --> D{Is Goal Achieved?}
    D -- No --> E[Find Target Element Coordinates]
    E --> F[Perform Gesture: Tap/Swipe/Text]
    F --> C
    D -- Yes --> G[Finish Automation / Report Results]
    C -- Error/Crash --> H[Pull Crash Log / Restart App]
    H --> C

1. デバイスの確認と選択：mobilecli devices を実行して、オンラインのデバイスとシミュレーターを確認します。オンラインのデバイスが1台だけの場合は自動的に選択されます。それ以外の場合は、--device <id> フラグにデバイス ID を指定してください。
2. アプリの起動：mobilecli apps launch <bundle-id> を使って、対象アプリをフォアグラウンドに表示します。
3. 状態のキャプチャ：
   • UI ツリーをダンプします：要素を探すには mobilecli snapshot を、rect 座標を含む JSON を取得するには mobilecli dump ui を使います。
   • スクリーンショットを撮ります：表示内容を視覚的に確認するには mobilecli screenshot を使います。
4. 操作：ダンプ内の要素の参照をタップする（mobilecli io tap @e5）か、その rect の中心座標を計算して x,y をタップします。次に、入力には mobilecli io text を使います。
5. 繰り返しまたはデバッグ：新しい UI ダンプまたはスクリーンショットで変更を確認し、ポップアップに対処して、アプリが終了した場合はクラッシュレポートを確認します。

---

AI エージェント向けのベストプラクティス

重要

座標よりも参照を優先してください： mobilecli io tap @e5 は、最新の snapshot または dump ui にある要素 5 の中央をタップします。要素ではない位置（スワイプの開始点や終了点など）を指定する必要がある場合に限り、座標を使用してください。その場合は、要素の rect の中央を使用します：centerX = x + width/2、centerY = y + height/2。参照は UI が変更されるたびに無効になるため、再利用する前にダンプし直してください。

ヒント

手順は && で連結してください： 1 回の bash 呼び出しで操作と検証を実行します：mobilecli io tap @e5 --device <id> && mobilecli snapshot --device <id>。呼び出し回数が減り、最初の手順が失敗すると連鎖が停止します。

警告

リモートデバイスを解放してください： Mobile Next Cloud のリモートデバイスは、mobilecli remote release --device <id> を実行するまで割り当てられたままとなり、料金が発生します。失敗した場合も含め、タスクの最後に解放してください。最低利用時間は 5 分のため、本当に使い終わるまでデバイスを解放しないでください。

メモ

テキストを入力する前に入力フィールドを操作してください： テキストフィールドにテキストを入力するには、まずそのフィールドの中央をタップしてフォーカスし、ソフトキーボードが表示されるまで数百ミリ秒待ってから、mobilecli io text を呼び出します。

警告

自動選択に関する注意点： オンラインデバイスが 1 台だけ接続されている場合、mobilecli は対象デバイスを自動選択しますが、必ず最初に接続済みデバイスの一覧を確認してください。オンラインデバイスが複数ある場合、コマンドの失敗を避けるため、正確なデバイス ID を指定する必要があります。

---

クイック操作リファレンス

標準的なユーザー操作と mobilecli コマンドの対応を以下の表に示します。

ユーザー操作	CLI コマンド	説明
タップ	mobilecli io tap @e5 または mobilecli io tap <x,y>	snapshot または dump ui の参照、あるいは座標を指定して 1 回タップします
長押し	mobilecli io longpress <x,y | @ref> --duration <ms>	指定した時間、押し続けます
スワイプ	mobilecli io swipe <x1,y1,x2,y2>	開始座標から終了座標までドラッグします
ピンチ	mobilecli io pinch [x,y] --direction in|out	x,y または画面中央を中心に、2 本指で縮小（in）または拡大（out）します
テキスト入力	mobilecli io text "<text>"	フォーカス中のフィールドにテキストをそのまま送信します
キーの押下	mobilecli io button <BUTTON_NAME>	ハードウェアボタン（HOME、POWER など）を押します
クリップボードの読み取り	mobilecli io clipboard get	デバイスのクリップボードからテキストを読み取ります
クリップボードへの書き込み	mobilecli io clipboard set "<text>"	デバイスのクリップボードのテキストを置き換えます

---

リモートデバイス（Mobile Next Cloud）

Mobile Next がホストする実機の iOS および Android デバイスです。割り当て後、リモートデバイスは mobilecli devices に "type": "remote" として表示され、上記のすべてのコマンドを --device <id> で指定してそのまま使用できます。

1. 1 回だけ認証する

# device-code flow: prints a URL and a code for the user to enter in a browser.
# the user must do this step; it cannot be completed by the agent.
mobilecli auth login

# headless hosts with no OS keyring
mobilecli auth login --insecure-storage

# verify
mobilecli auth status

トークンの検索順序は、MOBILECLI_TOKEN 環境変数、次に OS のキーリング（または --insecure-storage を指定した認証情報ファイル）です。CI では、ログインする代わりに MOBILECLI_TOKEN を設定してください。ログインしておらず、トークンもない場合、すべての remote コマンドが失敗します。ユーザーに mobilecli auth login の実行を依頼してください。

2. 割り当て、使用、解放する

# see what the fleet has
mobilecli remote list-devices

# allocate and block until the device is ready (default timeout 900s)
mobilecli remote allocate --platform ios --version ">=18" --name "iPhone*" --wait
mobilecli remote allocate --platform android --version 14 --wait

# the response includes the device id; from here it is a normal device
mobilecli devices
mobilecli apps install ./app.ipa --device <remote-id> && \
  mobilecli apps launch com.example.app --device <remote-id> && \
  mobilecli snapshot --device <remote-id>

# always release when done, devices are billed while allocated
mobilecli remote release --device <remote-id>

フィルター：--platform ios|android、--version（複数回指定可能。AND 条件で適用され、>=、>、<=、<、または完全一致をサポート）、--name（完全一致または末尾に * を付けた前方一致）。必ず --wait を指定してください。指定しない場合、デバイスがまだ allocating の状態でコマンドが返ります。

---

---

詳細リファレンス

その他すべてのコマンド（アプリ、画面録画、スワイプ／長押し／ボタン、クリップボード、WebView、ファイルシステム、クラッシュレポート、デバイスログ、ディープリンク、画面の向き）、プラットフォーム固有の挙動、JSON-RPC／WebSocket API については、reference.md を参照してください。mobilecli <command> --help には常に最新の情報が表示されます。