How `get_booted_device_udid()` Identifies the Active iOS Simulator in ios-simulator-skill

The get_booted_device_udid() function detects the active iOS simulator by executing xcrun simctl list devices booted and extracting the first UUID match using the regex pattern \(([A-F0-9\-]{36})\).

The ios-simulator-skill repository provides automation utilities for managing iOS simulators via command-line tools. At the heart of its device detection logic lies get_booted_device_udid(), a utility function that reliably identifies which simulator is currently active without requiring manual UDID input.

How get_booted_device_udid() Detects the Active Simulator

Executing the simctl Query

The function shells out to Apple's simctl utility using Python's subprocess module. It runs:

xcrun simctl list devices booted

With parameters capture_output=True, text=True, and check=True to ensure the command executes successfully and returns readable output.

Parsing the Device UUID

The output contains lines like:

  iPhone 16 Pro (ABC123-DEF456-7890AB-CDEF12) (Booted)

The function applies the regex pattern:

r"\(([A-F0-9\-]{36})\)"

This captures the 36-character UUID (including hyphens) wrapped in parentheses. The first match is returned as the active simulator's UDID.

Handling Edge Cases

If the subprocess call raises CalledProcessError or no UUID pattern matches, the function returns None. This allows calling functions like resolve_udid() to handle the error state appropriately, typically by raising a RuntimeError when no booted device is found.

Implementation Location in device_utils.py

The core logic resides in ios-simulator-skill/scripts/common/device_utils.py at lines 24-55. This module also exports resolve_udid() and list_simulators(), which build upon get_booted_device_udid() to provide higher-level device management abstractions.

Practical Code Examples

Retrieving the Current Simulator UDID

from ios_simulator_skill.scripts.common.device_utils import get_booted_device_udid

udid = get_booted_device_udid()
if udid:
    print(f"Booted simulator UDID: {udid}")
else:
    print("No simulator is currently booted")

Integrating with Command-Line Scripts

import sys
from ios_simulator_skill.scripts.common.device_utils import resolve_udid

def main():
    # Assume args.udid comes from argparse (may be None)

    try:
        device_udid = resolve_udid(args.udid)
        print(f"Using device {device_udid}")
    except RuntimeError as e:
        print(e, file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()

Detecting Multiple Booted Simulators

from ios_simulator_skill.scripts.common.device_utils import list_simulators

booted = [d for d in list_simulators(state="booted")]
if len(booted) > 1:
    print("Warning: more than one simulator is booted")
elif booted:
    print(f"Booted UDID: {booted[0]['udid']}")
else:
    print("No booted simulators found")

Summary

• get_booted_device_udid() executes xcrun simctl list devices booted to query the system for active simulators.
• It extracts the device identifier using the regex pattern r"\(([A-F0-9\-]{36})\)" to capture the 36-character UUID.
• The function returns None when no booted device exists or the command fails, delegating error handling to calling functions like resolve_udid().
• Located in ios-simulator-skill/scripts/common/device_utils.py, this utility serves as the foundation for all automatic device detection in the repository.

Frequently Asked Questions

What command does get_booted_device_udid() use to find booted simulators?

The function shells out to xcrun simctl list devices booted, which returns a formatted list of all currently running iOS simulators along with their metadata and UDIDs.

How does the function handle cases where no simulator is running?

When the subprocess command fails or the regex fails to match a UUID pattern, get_booted_device_udid() returns None. This allows calling code to detect the absence of a booted device and respond appropriately, typically by raising a RuntimeError.

Can get_booted_device_udid() return multiple UDIDs if several simulators are booted?

No, the function returns only the first UUID match found in the simctl output. While xcrun simctl list devices booted can list multiple booted devices, this implementation specifically extracts and returns the first one detected, leaving multi-device handling to higher-level functions like list_simulators().

Where is get_booted_device_udid() defined in the ios-simulator-skill repository?

The function is implemented in ios-simulator-skill/scripts/common/device_utils.py between lines 24 and 55, alongside related utilities such as resolve_udid() and list_simulators().

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}