Use when backing up or restoring phone app local data (Documents and Caches), simulator/emulator app containers, temp session data recovery, app state migration, or rehydrating test data for iOS and Android. Keywords: backup app data, restore app data, documents directory, caches directory, simctl get_app_container, adb run-as.
Use this skill to safely copy an app's local data out of a phone app container and restore it later.
Scope:
xcrun simctladb and run-asThis skill focuses on:
Documents directory backup/restoreLibrary/Caches (iOS) and cache/code_cache (Android) backup/restoreCollect these values before running commands:
ios or androidflutter devices or xcrun simctl list devices)adb devices)com.f3nation.qmastercom.f3nation.q_masterworkouts.json) if schema compatibility is uncertain.rm -rf) against unresolved paths.xcrun simctl get_app_container <SIM_UDID> <BUNDLE_ID> data
Expected output: absolute path to the app's data container.
SIM_UDID="<SIM_UDID>"
BUNDLE_ID="<BUNDLE_ID>"
STAMP="$(date +%Y%m%d_%H%M%S)"
OUT_DIR="/tmp/app_backup_${STAMP}"
DATA_DIR="$(xcrun simctl get_app_container "$SIM_UDID" "$BUNDLE_ID" data)"
mkdir -p "$OUT_DIR"
cp -R "$DATA_DIR/Documents" "$OUT_DIR/Documents"
cp -R "$DATA_DIR/Library/Caches" "$OUT_DIR/Caches"
# Optional integrity metadata
find "$OUT_DIR" -type f -maxdepth 3 2>/dev/null | sort > "$OUT_DIR/file_list.txt"
SIM_UDID="<SIM_UDID>"
BUNDLE_ID="<BUNDLE_ID>"
BACKUP_DIR="<BACKUP_DIR>"
xcrun simctl terminate "$SIM_UDID" "$BUNDLE_ID" >/dev/null 2>&1 || true
DATA_DIR="$(xcrun simctl get_app_container "$SIM_UDID" "$BUNDLE_ID" data)"
# Pre-restore safety snapshot
SNAPSHOT_DIR="/tmp/pre_restore_$(date +%Y%m%d_%H%M%S)"
mkdir -p "$SNAPSHOT_DIR"
cp -R "$DATA_DIR/Documents" "$SNAPSHOT_DIR/Documents" 2>/dev/null || true
cp -R "$DATA_DIR/Library/Caches" "$SNAPSHOT_DIR/Caches" 2>/dev/null || true
mkdir -p "$DATA_DIR/Documents" "$DATA_DIR/Library/Caches"
cp -R "$BACKUP_DIR/Documents/." "$DATA_DIR/Documents/"
cp -R "$BACKUP_DIR/Caches/." "$DATA_DIR/Library/Caches/"
xcrun simctl launch "$SIM_UDID" "$BUNDLE_ID"
Note: run-as works only for debuggable builds and matching app signatures.
adb -s <DEVICE_SERIAL> shell run-as <PACKAGE_NAME> pwd
If this fails with permission errors, use a debug build or rooted workflow.
SERIAL="<DEVICE_SERIAL>"
PKG="<PACKAGE_NAME>"
STAMP="$(date +%Y%m%d_%H%M%S)"
OUT_DIR="/tmp/app_backup_${STAMP}"
mkdir -p "$OUT_DIR"
# Backup files dir (analogous to Documents/app files)
adb -s "$SERIAL" exec-out run-as "$PKG" tar -cf - files 2>/dev/null | tar -xf - -C "$OUT_DIR"
# Backup cache dirs if present
adb -s "$SERIAL" exec-out run-as "$PKG" tar -cf - cache code_cache 2>/dev/null | tar -xf - -C "$OUT_DIR" || true
SERIAL="<DEVICE_SERIAL>"
PKG="<PACKAGE_NAME>"
BACKUP_DIR="<BACKUP_DIR>"
adb -s "$SERIAL" shell am force-stop "$PKG"
# Optional pre-restore snapshot on host
SNAPSHOT_DIR="/tmp/pre_restore_android_$(date +%Y%m%d_%H%M%S)"
mkdir -p "$SNAPSHOT_DIR"
adb -s "$SERIAL" exec-out run-as "$PKG" tar -cf - files cache code_cache 2>/dev/null | tar -xf - -C "$SNAPSHOT_DIR" || true
# Push and copy with app uid via run-as
adb -s "$SERIAL" push "$BACKUP_DIR" /sdcard/Download/app_restore_tmp
adb -s "$SERIAL" shell run-as "$PKG" sh -c 'cp -R /sdcard/Download/app_restore_tmp/files/. files/ 2>/dev/null || true; cp -R /sdcard/Download/app_restore_tmp/cache/. cache/ 2>/dev/null || true; cp -R /sdcard/Download/app_restore_tmp/code_cache/. code_cache/ 2>/dev/null || true'
adb -s "$SERIAL" shell rm -rf /sdcard/Download/app_restore_tmp
adb -s "$SERIAL" shell monkey -p "$PKG" -c android.intent.category.LAUNCHER 1 >/dev/null 2>&1
After restore, verify:
Useful commands:
# iOS simulator critical file check
ls -l "$(xcrun simctl get_app_container <SIM_UDID> <BUNDLE_ID> data)/Documents"
# Android critical file check
adb -s <DEVICE_SERIAL> shell run-as <PACKAGE_NAME> ls -la files
For this repository:
Documents/workouts.json.workouts.json into the app data container is usually sufficient.