【Xcode】xcrun simctlコマンドまとめ

xcrun simctlは、iOSシミュレータをコマンドラインから制御するツールである。1つのサブコマンドが担う役割は小さく分かれているため、目的に応じたサブコマンドを個別に把握しておくと使いやすい。ここではsimctlの主要なサブコマンドを目的別に整理し、それぞれの使い方を解説した記事へリンクする。

クリップボード操作

xcrun simctl pbcopy/pbpasteでiOSシミュレータのクリップボードを操作する標準入力からシミュレータのペーストボードへのコピーと、ペーストボードの内容の標準出力への出力ができる。
xcrun simctl pbsyncで2台のiOSシミュレータ間・ホストとの間でペーストボードを同期する 2台のデバイス間、またはデバイスとmacOS本体との間でペーストボードの内容を同期できる。

UI設定

xcrun simctl ui appearanceでiOSシミュレータの外観をコマンドラインから操作するシミュレータのライト/ダークモードを取得・切り替えできる。
xcrun simctl ui increase_contrastでiOSシミュレータのコントラスト強調モードを操作するアクセシビリティ設定「コントラストを上げる」を取得・変更できる。
xcrun simctl ui content_sizeでiOSシミュレータのDynamic Typeを操作する Dynamic Type（文字サイズ設定）を取得・変更できる。

画面キャプチャ

xcrun simctl io screenshotでiOSシミュレータのスクリーンショットを撮影するシミュレータの画面をPNGなどの画像ファイルとして保存できる。

位置情報

xcrun simctl location setでiOSシミュレータの位置情報を固定値に設定する緯度・経度を指定した固定値にシミュレータの位置情報を設定できる。
xcrun simctl location runでiOSシミュレータにプリセットの移動シナリオを再生するあらかじめ用意されたシナリオを指定して、移動を伴う位置情報の変化を再生できる。
xcrun simctl location startでiOSシミュレータに複数地点を経由する移動をシミュレートする緯度・経度のウェイポイントを複数指定し、地点間を補間する任意の経路で位置情報を移動させられる。
xcrun simctl location list/clearでiOSシミュレータの位置情報シナリオを一覧・クリアする利用可能なシナリオの一覧表示と、設定済みの位置情報や再生中のシナリオのクリアができる。

ランタイム管理

xcrun simctl runtime listでインストール済みのiOSシミュレータランタイムを確認するインストール済みのシミュレータランタイムの一覧を、テキストまたはJSON形式で確認できる。
xcrun simctl runtime add/deleteでiOSシミュレータランタイムを追加・削除するランタイムディスクイメージの追加と、不要になったランタイムの削除ができる。
xcrun simctl runtime matchでSDKとランタイムビルドのマッピングを確認・上書きする XcodeがビルドやSwiftUIプレビューで使うランタイムビルドの確認と、明示的な上書きができる。
xcrun simctl runtime dyld_shared_cacheでシミュレータランタイムの共有キャッシュを管理するランタイムが起動時に使う共有ライブラリキャッシュの更新・削除ができる。

通知

xcrun simctl pushでiOSシミュレータにプッシュ通知をシミュレートする JSON形式のAPNsペイロードを使い、実際の配信基盤なしでプッシュ通知を送信できる。

権限管理

xcrun simctl privacyでiOSシミュレータのアプリ権限を操作する写真・連絡先・位置情報などのプライバシー系権限を、確認ダイアログを表示せずに許可・拒否・リセットできる。

デバイス管理

xcrun simctl createでiOSシミュレータデバイスを新規作成するデバイスタイプとランタイムを指定して、シミュレータデバイスを新規作成できる。
xcrun simctl deleteでiOSシミュレータデバイスを削除する指定したデバイスの削除や、不要になったデバイスのまとめての削除ができる。
xcrun simctl cloneでiOSシミュレータデバイスを複製する既存デバイスのデータをファイルシステムレベルで複製し、別のデバイスとして作成できる。
xcrun simctl renameでiOSシミュレータデバイス名を変更する既存デバイスの名前を、UUIDを変えずに変更できる。
xcrun simctl eraseでiOSシミュレータデバイスの内容を初期化するデバイス自体は残したまま、インストール済みアプリやデータを含む内容と設定を初期化できる。
xcrun simctl boot/shutdownでiOSシミュレータデバイスを起動・終了するデバイスの起動・終了に加え、環境変数の注入もできる。
xcrun simctl upgradeでiOSシミュレータデバイスのランタイムを変更する同じUUID・データを保持したまま、デバイスのランタイムを新しいバージョンに変更できる。
xcrun simctl rebootでiOSシミュレータデバイスを再起動するインストール済みアプリやデータを保持したまま、デバイスをシャットダウンしてから起動し直せる。

アプリ操作

xcrun simctl appinfoでiOSシミュレータのインストール済みアプリの詳細情報を表示するインストール済みアプリを1つ指定して、listappsと同じ形式の詳細情報を直接取得できる。
xcrun simctl install/uninstallでiOSシミュレータにアプリをインストール・削除する .appバンドルのインストールとbundle identifier指定での削除ができる。
xcrun simctl terminateでiOSシミュレータの実行中アプリを終了する実行中のアプリをbundle identifier指定で終了できる。
xcrun simctl getenvでiOSシミュレータの環境変数を取得するデバイスの環境変数を1つ指定して取得できる。
xcrun simctl get_app_containerでiOSシミュレータのアプリのコンテナパスを取得するインストール済みアプリの.appバンドルやデータ保存先、App Groupのパスを取得できる。
xcrun simctl launchでiOSシミュレータのアプリを環境変数・引数付きで起動する起動時の引数・環境変数の指定や、デバッガのアタッチ待ちができる。
xcrun simctl spawnでiOSシミュレータ内の任意の実行ファイルを実行するアプリとしてインストールされていないコマンドを、シミュレータのコンテキストで実行できる。
xcrun simctl addmediaで写真・動画・連絡先をiOSシミュレータのライブラリに追加する写真アプリのライブラリや連絡先に、テスト用のデータをまとめて追加できる。
xcrun simctl keychainでiOSシミュレータに証明書を信頼させる自己署名の証明書をルート証明書ストアに追加し、ローカル開発サーバーへの接続を信頼させられる。
xcrun simctl listappsでiOSシミュレータのインストール済みアプリ一覧を表示するインストール済みアプリをbundle identifierやコンテナパスなどの詳細情報付きで一覧できる。

Watch連携

xcrun simctl pairでWatchとiPhoneをペアリングする Apple WatchシミュレータとiPhoneシミュレータを、実機同様のペアとして組み合わせられる。
xcrun simctl pair_activateで作成済みのペアをアクティブにする 1台のiPhoneに複数のWatchをペアリングしている場合に、実際に連携するペアを切り替えられる。
xcrun simctl unpairでWatchとiPhoneのペアを解除するデバイス自体は削除せず、ペアリングの関係だけを解除できる。

その他

xcrun simctl status_barでiOSシミュレータのステータスバー表示を固定する時刻・電波・バッテリーなどのステータスバー表示を、任意の固定値に上書きできる。
xcrun simctl openurlでiOSシミュレータ内のURLを開く Universal LinkやアプリのカスタムURLスキームを、実際にアプリを操作せずに開ける。
xcrun simctl listでiOSシミュレータのデバイス・ランタイム一覧を絞り込むデバイス・ランタイムなどの一覧を、検索語やJSON形式で柔軟に取得できる。
xcrun simctl icloud_syncでiOSシミュレータのiCloud同期をトリガーするデバイスに対してiCloud同期を即座に実行させられる。
xcrun simctl logverboseでiOSシミュレータの詳細ログ出力を切り替える詳細ログ出力(verbose logging)の有効・無効を切り替えられる。
xcrun simctl diagnoseでiOSシミュレータの診断ログを収集する sysdiagnoseを補完する診断情報・ログをまとめて収集できる。