CLI

概要

AppForceps には appforceps CLI ツールが同梱されており、ターミナルや AI エージェントから iOS Simulator / Android Emulator のアプリデータを検査・変更できます。コンテナ内のファイル、plist や SharedPreferences・Jetpack DataStore・SQLite の 1 key、プライバシー権限、ディープリンク、プッシュ通知、カメラソースまでを GUI を一切操作せずに扱えます。

インストール

brew install --cask kusumotoa/tap/appforceps

sudo ln -sf /Applications/AppForceps.app/Contents/MacOS/appforceps /usr/local/bin/appforceps

appforceps --version

コマンド一覧

すべてのコマンドは --json（1 行の JSON envelope で結果を返す。exit code 0〜7 と対応）を共通で持っています。破壊的な操作（files write / files rm / kv set / kv delete / perm grant / perm revoke / perm reset 等）はさらに --yes で実行を承認するか、--dry-run で変更計画だけを事前に確認できます。

kv: UserDefaults / SharedPreferences を確認・書き換える

典型的な流れは、対象の plist（または SharedPreferences / DataStore / SQLite）内の 1 key を kv get で確認し、--dry-run で変更内容を事前確認してから --yes で書き換える、という手順です。コマンドが返った時点で値は反映済みです。

# 現在の値を確認する
appforceps kv get --device sim:<udid> --app com.example.MyApp \
  Library/Preferences/com.example.MyApp.plist isPremium

# 書き換え前に変更内容を確認する（何も変更しない）
appforceps kv set --device sim:<udid> --app com.example.MyApp \
  Library/Preferences/com.example.MyApp.plist isPremium true --dry-run
# → update key isPremium: false -> true

# 承認して実際に書き換える
appforceps kv set --device sim:<udid> --app com.example.MyApp \
  Library/Preferences/com.example.MyApp.plist isPremium true --yes

権限を「未確認」の状態に戻してアプリを再起動すると、初回起動時の許可ダイアログや権限拒否時のエラーハンドリングを再現できます。権限変更はアプリを終了させることがあり、レスポンスの data.targetAppTerminated で実際に終了したかどうかを確認できます。

# 権限を未確認状態に戻す（iOS Simulator 専用。Android は revoke で代替）
appforceps perm reset --device sim:<udid> --app com.example.MyApp photos --yes --json
# → {"data":{"action":"reset","targetAppTerminated":false,...},"ok":true}

# アプリを再起動してオンボーディングを再現する
appforceps devices restart-app --device sim:<udid> --app com.example.MyApp --yes

assert / compare / snapshot: CI 向けの検証

assert は container 内の 1 key を期待値と比較するコマンドで、「実行は成功したが答えは No」という状態を ok: true のまま exitCode: 1 で表します（data.matched で判定）。exit code をそのまま CI のゲートに使えるため、他のコマンドより一段 CI 向けです。一方 compare（2 つのデバイス間の container を比較）と snapshot create / snapshot diff（同一デバイスの前後を named snapshot として比較）は、差分が見つかっても exit code は 0 のままです（exit 1 は比較そのものが実行できなかった場合）。差分の有無で CI を失敗させたい場合は、出力 JSON の summary を自前でチェックしてください。

# 1 key だけを CI で検証する（不一致なら exit code 1）
appforceps assert --device sim:<udid> --app com.example.MyApp \
  Library/Preferences/com.example.MyApp.plist isPremium --equals true --json

# 操作の前後で container 全体を named snapshot として比較する
appforceps snapshot create --device sim:<udid> --app com.example.MyApp --label before
# ...アプリを操作する...
appforceps snapshot create --device sim:<udid> --app com.example.MyApp --label after
appforceps snapshot diff --label-a before --label-b after --json