# コマンドライン

Device MCP のコマンドライン device-mcp-cli を使って、ターミナル、シェルスクリプト、CI から iPhone、iPad、Android デバイス、シミュレータを操作できます。どのコマンドも JSON で結果を返せます。

`device-mcp-cli` は Device MCP のコマンドラインです。アプリで行う操作や AI エージェントに頼む操作を、ターミナル、シェルスクリプト、Makefile、CI から実行できます。デバイスの一覧表示、スクリーンショット、画面の読み取り、タップや入力、アプリの起動やインストール、位置情報の設定、ライセンスの管理ができます。

どのコマンドも JSON で結果を返せるので、スクリプトではテキストを解析しなくても、`jq` で結果を読み取れます。

## 1. インストール
* **Homebrew**：`brew install --cask device-mcp` で、`device-mcp-cli` が `PATH` に追加されます。
* **Web サイトからダウンロードした場合**：ターミナルで次のコマンドを一度だけ実行して、`PATH` に追加します。

```bash
sudo ln -sf "/Applications/Device MCP.app/Contents/MacOS/device-mcp-cli" /usr/local/bin/device-mcp-cli
```

このリンクは、Device MCP がアップデートされても使えます。次のコマンドで確認します。

```bash
device-mcp-cli --version
device-mcp-cli --help                  # every command
device-mcp-cli help apps launch        # one command, with its options
```

## 2. 仕組み
* **コマンドは Device MCP が実行します**：デバイスのコマンドは、Mac 上の Device MCP アプリに送られます。Device MCP が起動していない場合、コマンドは Device MCP を開く前に確認します。`--launch` を付けると確認せずに開き（スクリプトではこちらを使います）、`--no-launch` を付けると開きません。`status`、`mcp`、`tools`、`logs` は Device MCP を開きません。
* **使うデバイス**：`--device`（または `-d`）でデバイスの名前か UDID を指定します。指定しない場合は `devices select` で選んだデバイスを使い、それもなければ Device MCP で選択されているデバイスを使います。
* **JSON**：どのコマンドにも `--json` を付けられます。エラーも JSON で返ります。
* **主導権はあなたに**：アプリのインストールと削除、リンクを開く操作、クリップボードの読み取りと変更、Build & Run は、AI エージェントの場合と同じく、まず Device MCP であなたに確認します。[承認](ai-agents/approvals.md)を参照してください。デバイスのペアリング解除とライセンスの無効化は、常に確認します。
* **無料版と Pro**：どのコマンドも Device MCP の無料版で使えます。ただし、Build & Run、アプリのインストール、3D ビューインスペクタには [Device MCP Pro](license.md) が必要です。無料版でミラーリングできるのは、一度に 1 台のデバイスだけです。

## 3. コマンド
`<device>` はデバイスの名前か UDID です。どのコマンドにも `--json` を、デバイスのコマンドには `--device` を付けられます。

### デバイス
| コマンド | 内容 |
| --- | --- |
| `devices` | デバイスを一覧表示します（名前、種類、OS、接続方法、状態、UDID）。`--all` を付けると、すべてのシミュレータとエミュレータに加え、新しいシミュレータに選べるモデルも表示します。 |
| `devices info` | デバイスのモデル、OS、画面サイズ、ミラーリングとロックの状態を表示します。`--settings` を付けると、外観とアクセシビリティの設定も表示します。 |
| `devices select <device>` | 以降のコマンドで使うデバイスを選び、Device MCP に表示します。 |
| `devices start-mirroring`、`devices stop-mirroring` | デバイスのミラーリングを開始または停止します。 |
| `devices reconnect` | ミラー画面が固まったデバイスに再接続します。 |
| `devices unpair <device>` | iPhone や iPad と Mac のペアリングを解除します。 |
| `devices remove <device>` | Device MCP のリストからデバイスを削除します。 |
| `simulators` | iOS と watchOS のシミュレータ、Android エミュレータを一覧表示します。 |
| `simulators start <name>` | シミュレータまたはエミュレータを起動し、起動が完了するまで待ちます。`--model "iPhone 17 Pro"` を付けると、新しいシミュレータを作成します。 |
| `simulators stop <name>` | シミュレータまたはエミュレータをシャットダウンします。 |

### 画面
| コマンド | 内容 |
| --- | --- |
| `screenshot` | フル解像度のスクリーンショットを保存します。`-o` で保存先のファイル（`.png` または `.jpg`）かフォルダを指定します。デフォルトは `~/Pictures/Device MCP` です。 |
| `record start`、`record stop` | 画面を収録して、`~/Movies/Device MCP` にムービーとして保存します。 |
| `elements` | 画面上の要素を一覧表示します。要素ごとに、種類、ラベル、値、フレーム、`tap --ref` で使う ref（`e12`）を表示します。 |

### タッチとキー
| コマンド | 内容 |
| --- | --- |
| `tap` | 要素をテキスト（`--text "Sign In"`）か ref（`--ref e12`）で指定するか、座標（`-x 120 -y 640`）を指定してタップします。`--double` でダブルタップ、`--long` で長押しします。 |
| `type <text>` | フォーカスのあるフィールドに入力します。`--field "Email"` はフィールドをタップし、中身を消してから入力します。`--submit` で Return キーを押します。`-` を指定すると、パイプやファイルからテキストを読み込みます。 |
| `scroll up\|down\|left\|right` | スクロールします。`--distance 300` を付けると、コンテンツを指定したポイント数だけ正確に動かします。 |
| `swipe --from x,y --to x,y` | ある位置から別の位置までスワイプします。 |
| `press <button>` | `home`、`lock`、`volume_up`、`volume_down`、`mute`、`siri`、`back` のいずれかのボタンを押します。 |
| `key <key>` | キーボードのキーを押します。`--modifier command` などで修飾キーも指定できます。 |
| `gesture <gesture>` | `go_home`、`app_switcher`、`control_center`、`notification_center`、`spotlight` のいずれかのジェスチャを行います。 |
| `rotate <orientation>` | `portrait`、`landscape_left`、`landscape_right`、`portrait_upside_down` のいずれかの向きに回転します。 |
| `hide-keyboard` | 画面上のキーボードを隠します。 |
| `wait-for <text>` | テキストが画面に表示されるまで（`--gone` の場合は消えるまで）、最大 `--timeout` 秒待ちます。 |
| `alert accept\|dismiss` | アクセスの許可を求めるアラートなど、システムのアラートに応答します。`--button` を付けると、テキストで指定したボタンをタップします。 |

### アプリ
| コマンド | 内容 |
| --- | --- |
| `apps` | インストールされているアプリを一覧表示します（名前、バンドル ID、バージョン）。`--user` を付けると、自分でインストールしたアプリだけを表示します。 |
| `apps foreground` | 前面にあるアプリとそのバンドル ID を表示します。 |
| `apps launch <app>` | バンドル ID か名前でアプリを起動します。テスト用に起動するときは、`--language`、`--locale`、`--arg`、`--env` を使います。 |
| `apps terminate <bundle-id>` | 実行中のアプリを終了します。 |
| `apps install <path>` | `.ipa`、`.app`、`.apk` をインストールします。Device MCP Pro の機能です。 |
| `apps uninstall <bundle-id>` | アプリとそのデータを削除します。 |
| `apps container <bundle-id>` | 開発用アプリのデータを、Xcode と同じく `.xcappdata` パッケージとしてダウンロードします。 |
| `open-url <url>` | Web ページかディープリンク（`myapp://…`）を開きます。 |
| `build-and-run <project>` | Xcode プロジェクトをビルドし、インストールして起動します。Device MCP Pro の機能です。[Build & Run](ai-agents/build-and-run.md) を参照してください。 |
| `crashes` | クラッシュレポートを新しい順に一覧表示します。`--app` でアプリを絞り込みます。 |
| `crashes show <path>` | クラッシュレポートを表示します。何がどこでクラッシュしたかがわかります。`--app` を付けると、そのアプリの最新のクラッシュを表示します。 |

### デバイスの設定
| コマンド | 内容 |
| --- | --- |
| `location set <latitude> <longitude>` | 位置情報をシミュレートします。`location clear` で実際の位置に戻します。 |
| `appearance light\|dark` | デバイスをライトモードかダークモードに切り替えます。 |
| `clipboard get`、`clipboard set <text>` | デバイスのクリップボードのテキストを読み取るか、置き換えます。 |

### Device MCP
| コマンド | 内容 |
| --- | --- |
| `status` | Device MCP が起動しているかどうか、そのバージョン、MCP サーバー、ライセンスを表示します。 |
| `app open`、`app quit` | Device MCP をバックグラウンドで開くか、終了します。 |
| `mcp` | MCP サーバーがオンかどうかと、そのアドレスを表示します。`mcp on` と `mcp off` でオン／オフを切り替えます。 |
| `mcp setup claude\|codex` | Claude Code または Codex に Device MCP を追加します。`--print` を付けると、追加する代わりにコマンドを表示します。 |
| `mcp config` | Cursor など、ほかの MCP クライアントで使う JSON を表示します。 |
| `license` | ライセンスを表示します。無料版か、プラン、キー、シート数、対象となるバージョンがわかります。 |
| `license activate <key>` | この Mac でライセンスキーを有効にします。 |
| `license revoke` | この Mac でライセンスを無効にし、シートを解放します。 |
| `logs` | バグ報告用に、Device MCP のログを表示します。`-f` を付けると、新しい行を表示し続けます。 |

### その他
| コマンド | 内容 |
| --- | --- |
| `call <tool> [name=value…]` | Device MCP のどの MCP ツールも、AI エージェントと同じように実行できます。 |
| `tools` | それらのツールと引数を一覧表示します。 |

## 4. 使用例
### サインインして結果を確認する
シェルスクリプトや CI のステップで使える、アプリのスモークテストです。

```bash
set -e
device-mcp-cli apps launch com.example.myapp --launch
device-mcp-cli wait-for "Sign In"
device-mcp-cli type "test@example.com" --field "Email"
device-mcp-cli type - --field "Password" < password.txt
device-mcp-cli tap --text "Sign In"
device-mcp-cli wait-for "Welcome" --timeout 20 || {
  device-mcp-cli screenshot -o failure.png
  exit 1
}
```

### すべてのデバイスのスクリーンショットを撮る
```bash
device-mcp-cli devices --json |
  jq -r '.devices[] | select(.state == "ready" or .state == "running") | .udid' |
  while read -r udid; do device-mcp-cli screenshot --device "$udid" -o ~/Desktop/; done
```

### 画面上の要素をタップする
`elements` は画面の要素を ref 付きで一覧表示します。`jq` で目的の要素を見つけて、タップします。

```bash
REF=$(device-mcp-cli elements --json | jq -r '.elements[] | select(.label == "General") | .ref')
device-mcp-cli tap --ref "$REF"
```

### ほかの言語と場所でアプリをテストする
```bash
device-mcp-cli apps launch com.example.myapp --language fr --locale fr_FR
device-mcp-cli location set 48.8584 2.2945
device-mcp-cli open-url "myapp://map"
device-mcp-cli appearance dark
```

### 新しいシミュレータでビルドして実行する
```bash
device-mcp-cli simulators start --model "iPhone 17 Pro" --launch
device-mcp-cli build-and-run ~/Projects/MyApp/MyApp.xcodeproj --scheme MyApp
device-mcp-cli screenshot -o ~/Desktop/myapp.png
```

### バグを画面収録する
```bash
device-mcp-cli record start
# reproduce the bug on the device
device-mcp-cli record stop
```

### Mac をセットアップする
CI 用の Mac や、新しく加わったチームメンバーの Mac で実行します。

```bash
device-mcp-cli license activate --launch < license-key.txt
device-mcp-cli mcp on
device-mcp-cli mcp setup claude
device-mcp-cli status
```

## 5. JSON と終了コード
`--json` を付けると、コマンドは JSON オブジェクトを 1 つ出力します。たとえば、`device-mcp-cli devices --json` の出力は次のとおりです。

```json
{
  "devices" : [
    {
      "connection" : "USB",
      "current" : true,
      "kind" : "iphone",
      "mirroringStopped" : false,
      "model" : "iPhone 17 Pro",
      "name" : "My iPhone",
      "osVersion" : "27.0.1",
      "platform" : "iOS",
      "state" : "ready",
      "udid" : "00008150-000A1B2C3D4E5F60"
    }
  ]
}
```

デバイスの `kind` は `iphone`、`ipad`、`watch`、`android`、`simulator`、`emulator` のいずれかです。`state` は `ready`、`locked`、`blocked`（`issue` と `fix` に理由と対処法が入ります）、`connecting`、`running`、`shut_down`、`booting`、`shutting_down`、`creating`、`starting` のいずれかです。

エラーの場合は `{"error": {"code": "…", "message": "…"}}` を出力します。

| コード | 終了コード | 意味 |
| --- | --- | --- |
| `not_running` | 69 | Device MCP が起動しておらず開かれなかったか、応答する前に終了しました。 |
| `no_answer` | 69 | Device MCP は起動していますが、応答しませんでした。アップデートするか、いったん終了してからもう一度開いてください。 |
| `not_installed` | 69 | Device MCP がインストールされていません。 |
| `invalid_arguments` | 64 | 引数が間違っているか、ライセンスキーの形式が正しくありません。 |
| `pro_required` | 1 | このコマンドには Device MCP Pro が必要です。 |
| `not_approved` | 1 | Device MCP であなたが拒否したか、誰も応答しませんでした。 |
| `timed_out` | 1 | Device MCP が時間内に完了しませんでした。 |
| `cancelled` | 1 | あなたが「いいえ」と答えました。 |
| `failed` | 1 | その他のエラーです。理由はメッセージに示されます。 |

成功したコマンドは、終了コード 0 で終了します。

## 6. AI エージェントと使う
エージェントもコマンドラインを使えます。たとえば、アプリのテストスクリプトや CI のステップを書かせることができます。

* *「iPhone でサインインして、ホーム画面が読み込まれなかったら失敗するスクリプトを書いて。」*
* *「オンボーディングのすべての画面のスクリーンショットを撮る CI ステップを追加して。」*

エージェントが実行したコマンドは、**Agent** タブに **device-mcp-cli** として表示されます。[エージェントのアクティビティ](ai-agents/agent-activity.md)を参照してください。