{"id":12026,"library":"simctl","title":"simctl - Xcode Simulator Utility Wrapper","description":"The `simctl` library provides a Node.js-based programmatic interface for interacting with Apple's `simctl` command-line utility, which manages iOS Simulators on macOS. It enables developers to automate tasks such as listing available devices, booting simulators, installing and launching applications, and interacting with device settings directly from JavaScript or TypeScript code. The current stable version is 3.0.0, which introduced significant breaking changes related to output handling and method signatures. The project's release cadence is driven by updates to Xcode and internal improvements, rather than a fixed schedule. `simctl` is designed for Xcode 8 or greater and Node.js 14.17.0 or greater, acting as a foundational component for other iOS development tools like `ios-sim` by abstracting complex `xcrun simctl` commands into a more accessible API.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/ios-control/simctl","tags":["javascript","simctl","iOS Simulator"],"install":[{"cmd":"npm install simctl","lang":"bash","label":"npm"},{"cmd":"yarn add simctl","lang":"bash","label":"yarn"},{"cmd":"pnpm add simctl","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While CommonJS `require` might work in older Node.js environments, the library's evolution (Node.js >=14.17.0) indicates a preference for ESM. Use named import for `list`.","wrong":"const { list } = require('simctl');","symbol":"list","correct":"import { list } from 'simctl';"},{"note":"`spawn` method signature changed significantly in v3.0.0, returning UTF-8 strings instead of Buffers. Ensure you are using the correct signature and handling string output.","wrong":"const { spawn } = require('simctl');","symbol":"spawn","correct":"import { spawn } from 'simctl';"},{"note":"The library primarily exposes named exports for its functionalities. While you can import all as a namespace object, a default import is generally not provided or recommended for this module's structure.","wrong":"import simctl from 'simctl';","symbol":"simctl","correct":"import * as simctl from 'simctl';"}],"quickstart":{"code":"import { list } from 'simctl';\n\nasync function getSimulatorInfo() {\n  console.log('Fetching available Simulators and runtimes...');\n  try {\n    const info = await list();\n    console.log('Devices:');\n    for (const runtimeId in info.devices) {\n      console.log(`  Runtime: ${runtimeId}`);\n      info.devices[runtimeId].forEach(device => {\n        console.log(`    - ${device.name} (${device.udid}) - ${device.state}`);\n      });\n    }\n\n    console.log('\\nRuntimes:');\n    info.runtimes.forEach(runtime => {\n      console.log(`  - ${runtime.name} (${runtime.identifier})`);\n    });\n\n    console.log('\\nDevice Types:');\n    info.devicetypes.forEach(type => {\n      console.log(`  - ${type.name} (${type.identifier})`);\n    });\n\n  } catch (error) {\n    console.error('Failed to retrieve simulator info:', error);\n    process.exit(1);\n  }\n}\n\ngetSimulatorInfo();","lang":"typescript","description":"This quickstart code demonstrates how to use the `list` function from `simctl` to asynchronously retrieve and display information about all available iOS Simulator devices, runtimes, and device types configured on the macOS system."},"warnings":[{"fix":"Update any code relying on `Buffer` operations or raw binary data from `simctl` method outputs to handle string input directly. Parse string output as needed.","message":"In `simctl` v3.0.0, all methods that call `spawnSync` now exclusively return UTF-8 encoded strings for `stdout`, `stderr`, and within `output`. Buffer output is no longer supported.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Refer to the official documentation or source code for the correct `spawn` method signature and adjust calls accordingly.","message":"The `spawn` method signature was updated in `simctl` v3.0.0. Code using the old signature will break.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"If a fresh simulator instance is required, explicitly use `shutdown` or `erase` commands before `start` to ensure the desired state, or adjust testing/development workflows to account for simulator re-use.","message":"Starting with `simctl` v2.0.0, the `start` behavior changed: the simulator is now re-used if it has already been started, instead of being killed and restarted each time. This impacts workflows expecting a fresh simulator instance.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your development environment meets the minimum Xcode and Node.js version requirements. Upgrade Xcode via the Mac App Store or developer portal, and Node.js using `nvm` or a similar tool.","message":"`simctl` requires Xcode 8 or greater to be installed on macOS, and NodeJS 14.17.0 or greater.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Remove `.toString()` calls from the output of `simctl` methods, as the output is already a UTF-8 string.","cause":"Attempting to call `toString()` on a `Buffer` object, but `simctl` v3.0.0+ now returns strings directly, not Buffers.","error":"TypeError: output.toString is not a function"},{"fix":"Verify Xcode is installed and up-to-date (Xcode 8+). Ensure `xcode-select --install` has been run for command line tools. Check if `xcrun simctl` works from the terminal.","cause":"`xcrun simctl` command failed, often due to an incorrect path, missing Xcode components, or an Xcode version older than the required 8+.","error":"Error: Command failed: xcrun simctl ... Error Domain=NSPOSIXErrorDomain Code=2 \"No such file or directory\""},{"fix":"Ensure `import { spawn } from 'simctl';` is used. Review the library's documentation for the correct `spawn` method signature in `simctl` v3.0.0+ and adjust your code accordingly.","cause":"This error can occur if `spawn` is not correctly imported (e.g., using a default import instead of a named import) or if the arguments passed to `spawn` do not match its updated signature in `simctl` v3.0.0.","error":"TypeError: simctl.spawn is not a function or signature mismatch"}],"ecosystem":"npm"}