argent-ios-device-setup
software-mansion/argent
Set up a cabled physical iPhone for argent automation testing.
What is argent-ios-device-setup?
Configures a physical iPhone connected via USB cable for use with argent's automation framework. Use only for physical devices (not simulators); handles signing, developer mode setup, and on-device runner installation.
- Enables Developer Mode and registers physical iPhone with argent
- Builds, signs, and launches the ArgentRunner automation app on device
- Manages code signing with automatic team detection and ARGENT_IOS_TEAM_ID override support
- Handles first-run trust prompts and developer certificate validation
- Provides diagnostic logging and recovery steps for common signing failures
How to install argent-ios-device-setup
npx skills add https://github.com/software-mansion/argent --skill argent-ios-device-setup- Physical iPhone cabled via USB to the machine
- iPhone unlocked with screen kept awake during setup
- Developer Mode enabled (Settings > Privacy & Security > Developer Mode)
- Xcode command-line tools installed
- Valid Apple Developer account (free or paid team)
How to use argent-ios-device-setup
- 1.Cable the iPhone and unlock it, keeping the screen awake
- 2.Enable Developer Mode in Settings > Privacy & Security > Developer Mode
- 3.Verify the device shows as connected using list-devices
- 4.Run launch-app to register the app (first describe/gesture/screenshot will build and sign)
- 5.When prompted on device, trust the developer in Settings > General > VPN & Device Management
- 6.Confirm ArgentRunner app appears on home screen and remains installed
- 7.Proceed to argent-ios-device-interact for automation commands
Use cases
- Automating UI tests on a physical iPhone connected via USB
- Setting up a device for the first time before running any argent automation
- Troubleshooting signing or runner installation issues on a cabled iPhone
- Switching between different signing teams or certificates for device testing
- iOS QA engineers running device automation
- Mobile app developers testing on physical hardware
- CI/CD systems automating tests on connected iPhones
argent-ios-device-setup FAQ
The first describe, gesture, or screenshot triggers a cold build and signing process (up to 15 minutes), then starts the on-device runner (up to 120 seconds). Subsequent calls use cached builds and are much faster.
ArgentRunner is argent's automation runner that executes commands on the device. It must remain installed for automation to work.
Run `security set-key-partition-list -S apple-tool:,apple:,codesign: -s ~/Library/Keychains/login.keychain-db` (you will be prompted for your login password), then retry.
It overrides the automatically detected signing team. Set it as a tool-server environment variable; changes force a cold rebuild.
No. Use argent-ios-simulator-setup for simulators; this skill is for physical cabled iPhones only.
Full instructions (SKILL.md)
Source of truth, from software-mansion/argent.
name: argent-ios-device-setup description: Set up a cabled physical iPhone for argent. Use when a physical iPhone is involved (a list-devices iOS entry with kind "device") and ONLY then; never for a simulator.
Physical iPhone setup
Read this only for a physical iPhone. Simulators use argent-ios-simulator-setup.
First run
- Cable the phone, unlock it, keep the screen awake, and turn on Developer Mode (Settings > Privacy & Security > Developer Mode).
list-devicesmust show itconnected. launch-apponly registers the app. The firstdescribe, gesture orscreenshotbuilds, signs and starts the on-device runner: minutes cold, tens of seconds from cache or after a tool-server restart. Build cap 15 min, runner ready 120 s.- On the first install the phone asks to trust the developer (Settings > General > VPN & Device Management), and an ArgentRunner app appears on the home screen. Tell the user it is argent's automation runner and must stay installed.
Signing and failures
Signing needs no configuration. The first phone call of a tool-server process carries a note naming the team picked and the ARGENT_IOS_TEAM_ID override (tool-server environment; a change forces a cold rebuild). Cable, lock, trust, expired-profile and missing-certificate errors name their fix: apply it, retry the same call. Also: errSecInternalComponent: run security set-key-partition-list -S apple-tool:,apple:,codesign: -s ~/Library/Keychains/login.keychain-db (asks the user's login password), retry. team has no devices: keep the phone cabled, retry. Bundle id registration failed: free-team app-id cap, wait days or sign under a paid team. Any other xcodebuild failure prints raw error: lines: read ~/.argent/ios-device-runner/logs/runner-<udid8>.log. RUNNER_WEDGED: stop-simulator-server for the udid, retry.
Then read argent-ios-device-interact.
Related skills
More from software-mansion/argent and the wider catalog.
argent-ios-simulator-setup
Set up and boot iOS simulators, verify connection, and obtain UDIDs for simulator interaction tasks.
argent-lens
Propose and compare multiple visual design variants for UI elements with human selection.
argent-metro-debugger
Debug React Native and Chromium apps via Chrome DevTools Protocol with Metro and CDP integration.
argent-native-profiler
Native profiling for iOS and Android: CPU hotspots, UI hangs, memory leaks via xctrace and Perfetto.
argent-qa-flows
Create repeatable QA regression E2E tests as Argent flows from test cases and acceptance criteria.
argent-react-native-app-workflow
Step-by-step workflows for developing and debugging React Native apps on iOS simulator or Android emulator.