Device Control Reference (Device Hub, devicectl, simctl)
Reference for controlling iOS simulators and physical devices from outside Xcode. On Xcode 27, Device Hub replaces Simulator.app as the GUI for both, and because it is a front end over the devicectl and simctl command-line tools, everything it does can also be scripted without Xcode running.
When to Use This Reference
Use this reference when:
- You want to drive a simulator or device from a script or CI without keeping Xcode open
- You're choosing between the CLI tools and the Xcode MCP bridge (
xcrun mcpbridge) for a given job - You're deciding between
devicectlandsimctlfor a given operation - You need to script Face ID / Touch ID, orientation, appearance, VoiceOver, or simulated location
- You want to resize an app's window from a script — sweeping breakpoints in CI instead of dragging by hand
- You want to screenshot or screen-record a simulator or a physical device from the command line
- You're preparing App Store screenshots and need a clean status bar (9:41, full bars, full battery)
- You're parsing
devicectl --json-outputin CI and need the stable keys - You want to know what the Xcode 27 Device Hub GUI offers and how it maps to the CLI
Example Prompts
Questions you can ask your assistant that will draw from this reference:
- "Can I control the simulator without Xcode running?"
- "How do I script Face ID enrollment and a match in a UI test?"
- "What's the difference between devicectl and simctl?"
- "How do I resize the app window from a script?"
- "Can I automate resize-readiness testing across breakpoints?"
- "What is Device Hub in Xcode 27, and do I need to open Xcode to use it?"
- "My simulator is stuck and
killall -9 Simulatordoes nothing — what changed in Xcode 27?" - "How do I list physical devices and simulators together from the command line?"
- "How do I record a video of a physical device from the command line?"
- "How do I set the status bar to 9:41 with full bars for App Store screenshots?"
- "Why did my screenshot come out with the wrong status bar even though the command succeeded?"
- "Should I use xcui or the Xcode MCP device-interaction tools?"
- "Which devicectl JSON keys are deprecated, and what replaced them?"
- "How do I tell whether a device has Developer Mode enabled from the command line?"
- "Can I set iPhone Duo's hinge angle from a script or a UI test?"
What's Covered
Tool map
- Which tool owns which job —
devicectl,simctl, Axiom's bundled CLI tools (xcui,xclog,xcsym,xcprof), Device Hub, andmcpbridge - The "needs Xcode running?" column — nothing does on Xcode 27, though headless MCP requires a one-time
sudoopt-in that CI may not permit - CLI tools vs Xcode MCP (the server that lets your assistant drive Xcode itself) — with neither needing Xcode open, choose by capability: the CLI tools assert, wait, toggle accessibility settings and run without special privileges, which decides it in CI; MCP owns what only the IDE knows, such as build state and rendered previews
Resizable app sessions (Xcode 27)
devicectl device appResize start/set/observe, anddevicectl device info appResize--preferred-size WxHand--corner-radius, and why the actual size can differ from the requested one- The sweep-and-assert recipe — drive breakpoints from the CLI, assert each with
xcui
devicectl (Core Device CLI)
- Unified
list devicesinventory (physical + simulated,Realitycolumn) - Install / launch / inspect by
-d <udid> --json-outputstability contract and the keys to parse- The
propertiesdictionary that supersedes the deprecatedhardwareProperties/deviceProperties/connectionPropertieskeys, and--omit-deprecated-fields-in-json properties.hardware.reality,.deviceType,.platform;properties.connection.state,.pairingState,.transportType;properties.state.developerModeStatus,.bootState- Which of those fields are always present and which drop out on an unreachable device
- devicectl-vs-simctl division of labor (interaction vs lifecycle)
- Verified simulator-capable subcommand matrix
- Face ID / Touch ID as a CI primitive; the
CoreDeviceError 1001"device-only" signal - Reading iPhone Duo's hinge angle with
device motion hinge-angle, which nothing on the command line can set; from Xcode 27.3 a UI test sets it withXCUIDevice.shared.hinge
Rotating a simulator
devicectl device orientation set/get, and whysimctlcan't do it- Verifying a rotation by screenshot dimensions rather than by exit code
- The two devices that don't rotate this way — iPhone Duo (a silent no-op) and an app's own request on iPad
Screen capture
devicectl device capture screenshot/screen-record– unified sim + device path (Xcode 26.6+)- Codec, mask-policy, and
--durationauto-stop options, and the.png/.mp4extension rules - Simulator-only fallbacks (
simctl io,axe) and when to reach for them --mask alpha/ignored/black, and which one shows what the user sees- Why a black or failed simulator capture can reflect display state, and what to check before attributing it to your app — display state first, accessibility tree second
- Naming a display on a two-display device — simctl's port UUID vs devicectl's
uniqueId, and which display you get by default
Status bar for screenshots
devicectl device simulate statusBar presetand its four presets —screenshot,low-battery,no-service,chargingoverride/show/clear, and thesimctl status_barequivalents that share the same store- Why to clear before every override, and why to assert on the readback instead of the exit code
- The two tools' incompatible flag vocabularies, side by side
- Setting a carrier name, which only
simctl's--operatorNamecan do - The
--cellular-strengthrangedevicectl's own help text gets wrong, and the JSON backtick quirk indataNetworkType - Why
devicectl's command set follows a machine-wide CoreDevice, notxcode-select - Why the overrides are cosmetic: a 9:41 status bar doesn't change the clock your app reads
Device Hub (Xcode 27 GUI)
- Compact vs full window, the interactive canvas
- What Xcode 27.2 changes: input to pre-iOS 18 simulators, touch from a Sidecar iPad or touch-display Mac, and the conflict between Secure keyboard entry and Capture keyboard
- The five-panel inspector and what each panel is for
- Bundle path, process name, and bundle id per Xcode version, why
killall -9 Simulatorkills nothing on Xcode 27, and confirming the kill withpgreprather than the exit code - CarPlay Simulator built into Device Hub (it needs a physical iPhone, and on Xcode 27.2 a USB cable), and the
CarPlayExtraOptionsdefault that does not exist in Xcode 27
Documentation Scope
This page documents the device-control-ref skill (in the axiom-tools suite), the canonical home for the devicectl, simctl, and Device Hub facts that the build, testing, and tools skills cross-reference.
- For the bundled Axiom CLI tools this reference sits alongside, see Console Capture (xclog), Trace Capture & Analysis (xcprof), Crash Symbolication (xcsym), and xcui, which validates the on-screen UI that
devicectlsets up - For the Xcode MCP path, including the headless
mcp-serversetup that removes the running-Xcode requirement, see Xcode MCP Setup - For the debugging workflow that uses Device Hub to reproduce a device-only bug on a simulator, see Xcode Debugging
Related
- simulator-tester – The agent that applies device state and asserts on the result
- AXe Reference – The simulator-only input and video tool behind
xcui, and one of the capture fallbacks covered here - watch-device-diag – Applies these fields to a hard case: an Apple Watch that Xcode won't install to, launch, or attach to