| name | install-iphone |
| description | Build, install, and launch the OpenClient iOS app on a physical iPhone. Use when testing on-device, diagnosing iPhone install/launch failures, or refreshing the on-device debug build. |
OpenClient iPhone Install
Use this skill to build the app for a physical iOS device, install it on the configured iPhone, and launch it.
Target iPhone
- Device name:
Nic iPhone
- Device UDID source:
OPENCLIENT_IPHONE_UDID
- App bundle ID:
com.ntoporcov.openclient
- Fresh app path:
.derived-data-device/Build/Products/Debug-iphoneos/OpenClient.app
Do not hardcode the UDID in commands or logs. Read it from the environment. If OPENCLIENT_IPHONE_UDID is missing, source .opencode/.env if it exists, then stop and ask the user to set it locally before installing if it is still missing.
Skip device discovery unless build, install, or launch fails.
Use this shell guard before install/launch commands:
[ -f .opencode/.env ] && set -a && . .opencode/.env && set +a
: "${OPENCLIENT_IPHONE_UDID:?Set OPENCLIENT_IPHONE_UDID to the target iPhone UDID}"
Build
Build for iPhone using repo-local derived data so the install path is fresh and deterministic:
xcodebuild -quiet -project OpenCodeIOSClient.xcodeproj -scheme OpenCodeIOSClient -sdk iphoneos -derivedDataPath .derived-data-device build
Do not install from stale global DerivedData or old repo-local paths. The expected fresh install artifact is:
.derived-data-device/Build/Products/Debug-iphoneos/OpenClient.app
Important stale-path warning:
- Do not install from
DerivedData/Build/Products/... unless that exact folder was the explicit -derivedDataPath for the build you just ran.
- A stale
OpenCodeIOSClient.app may have the wrong bundle identifier after the app rename.
- Prefer
.derived-data-device/Build/Products/Debug-iphoneos/OpenClient.app after the command above.
Install On iPhone
Install the freshly built app:
[ -f .opencode/.env ] && set -a && . .opencode/.env && set +a; : "${OPENCLIENT_IPHONE_UDID:?Set OPENCLIENT_IPHONE_UDID to the target iPhone UDID}" && xcrun devicectl device install app --device "$OPENCLIENT_IPHONE_UDID" ".derived-data-device/Build/Products/Debug-iphoneos/OpenClient.app"
Launch On iPhone
Launch the installed app:
[ -f .opencode/.env ] && set -a && . .opencode/.env && set +a; : "${OPENCLIENT_IPHONE_UDID:?Set OPENCLIENT_IPHONE_UDID to the target iPhone UDID}" && xcrun devicectl device process launch --device "$OPENCLIENT_IPHONE_UDID" com.ntoporcov.openclient
Failure Handling
If install or launch fails because the iPhone is locked, unavailable, disconnected, or not paired, then verify device availability:
xcrun xcdevice list
Common fixes:
- Unlock Nic iPhone.
- Reconnect USB once.
- Ensure Developer Mode is enabled on the iPhone.
- If using wireless debugging, ensure the Mac and iPhone are on the same LAN.
- Verify
Connect via network in Xcode Devices and Simulators.
If install succeeds but launch fails because the iPhone is locked or unavailable, say that the install may have succeeded and the app can be opened manually after unlocking.
When Xcode Project Generation Is Needed
If build fails with bundle identifier validation errors, regenerate the project from project.yml using the local signing override, then rebuild:
INCLUDE_PROJECT_LOCAL_YAML=1 /Users/mininic/.local/bin/xcodegen generate
Known validation error strings include:
error: Unexpected app bundle identifier '$PRODUCT_BUNDLE_IDENTIFIER'. Regenerate the project from project.yml before building.error: Unexpected extension bundle identifier '$PRODUCT_BUNDLE_IDENTIFIER'. Regenerate the project from project.yml before building.
Final Report
Report:
- Whether the iPhone device build succeeded.
- Whether install on the configured iPhone succeeded.
- Whether launch on the configured iPhone succeeded.
- Any exact blocker if build/install/launch failed.
