skills.rest
rshankras
rshankrasCOMMUNITY
Explore all skills by this author →
Website𝕏@rshankraGitHub

run-device

Builds, installs, and launches iOS apps on physical devices via xcodebuild and devicectl.

696|66|Updated Oct 29, 2025
Search Tags:#ios#command line#screenshot#xcodebuild#code signing#devicectl#device deployment
One-click install
npx skills add https://github.com/rshankras/claude-code-apple-skills --skill run-device
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: run-device
Source: https://github.com/rshankras/claude-code-apple-skills/tree/main/skills/ios/run-device
Command: npx skills add https://github.com/rshankras/claude-code-apple-skills --skill run-device

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Running an iOS app on a physical iPhone or iPad normally requires opening Xcode and clicking Run. This Skill performs the entire build-sign-install-launch cycle from the command line, enabling device testing, hardware-only bug reproduction, and on-device screenshots without the Xcode GUI.

Core Features & Use Cases

  • CLI Device Deployment: Builds with xcodebuild for a generic iOS destination, then installs and launches on a paired device using devicectl with automatic provisioning.
  • Device Verification: Confirms the app is actually running by checking the process list, and captures on-device screenshots via libimobiledevice's idevicescreenshot.
  • Pitfall Guidance: Documents known traps such as the devicectl identifier vs hardware UDID mismatch, the CoreDeviceError 10004 false alarm, and Developer Mode/Trust prerequisites.
  • Use Case: You fixed a camera bug that only reproduces on hardware. Ask the assistant to build and launch the app on your connected iPhone, then screenshot the result to verify the fix.

Quick Start

Build and launch my app on my connected iPhone from the command line and take a screenshot to confirm it runs.

Frequently Asked Questions about run-device

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run an iOS app on a physical device from the command line?▼

Build with xcodebuild using the generic/platform=iOS destination and -allowProvisioningUpdates, then install and launch with xcrun devicectl device install app and device process launch using the device's CoreDevice identifier.

How to take a screenshot of an app on a physical iPhone from the terminal?▼

Use idevicescreenshot from the libimobiledevice package, installed via Homebrew. Run it after launching the app through devicectl so the Developer Disk Image is mounted, then read the saved PNG to verify the screen.

Why does xcodebuild fail with 'Unable to find a device matching the provided destination'?▼

xcodebuild matches destinations on the hardware UDID, not the devicectl CoreDevice identifier. Build for generic/platform=iOS instead, which produces the same signed .app, and reserve the devicectl identifier for install and launch commands.

Can I enable Developer Mode or trust a computer from the command line?▼

No. Developer Mode must be toggled in Settings under Privacy & Security followed by a restart, and the Trust This Computer prompt must be tapped on the device. These are one-time interactive prerequisites that no CLI can perform.

What does CoreDeviceError 10004 mean when launching an app with devicectl?▼

Error 10004 is usually a false alarm triggered by the --terminate-existing flag, even though the app launched. Run a plain launch and confirm the process with xcrun devicectl device info processes to verify it is running.

When should I use a physical device instead of the iOS Simulator?▼

Use a physical device for hardware-dependent features like camera, sensors, push notifications, and real performance characteristics. The Simulator path uses simctl and different build products, so device testing requires devicectl and real code signing.

Related Skills

Explore More Software Engineering Skills→
danielraffeldanielraffel
13

ios

Build, deploy, and debug the Pulp codebase on iOS devices and simulators.

Community
Advanced
po4ykapo4yka
58

android-device-debug

Debug RIPDPI on Android devices and emulators using adb and Gradle.

Community
Intermediate
helpful-bitshelpful-bits

ios-simulator-eval-loop

Launch, drive, and verify iOS apps in the Apple Simulator with xcodebuild and simctl.

Official
Advanced
IlyaKukarkinIlyaKukarkin

expo-dev-client

Build and distribute Expo development clients for iOS and Android.

Community
Advanced