simctl

library0.0.2jsnpmunverified

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.

devops testing

npm install simctl

github ↗package ↗

INSTALL

IMPORT

SIG · SIMCTL

simctl

devopsjavascriptv0.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

list

✓ import { list } from 'simctl';

✗ const { list } = require('simctl');

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`.

spawn

✓ import { spawn } from 'simctl';

✗ const { spawn } = require('simctl');

`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.

simctl

✓ import * as simctl from 'simctl';

✗ import simctl from 'simctl';

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.

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.

import { list } from 'simctl'; async function getSimulatorInfo() { console.log('Fetching available Simulators and runtimes...'); try { const info = await list(); console.log('Devices:'); for (const runtimeId in info.devices) { console.log(` Runtime: ${runtimeId}`); info.devices[runtimeId].forEach(device => { console.log(` - ${device.name} (${device.udid}) - ${device.state}`); }); } console.log('\nRuntimes:'); info.runtimes.forEach(runtime => { console.log(` - ${runtime.name} (${runtime.identifier})`); }); console.log('\nDevice Types:'); info.devicetypes.forEach(type => { console.log(` - ${type.name} (${type.identifier})`); }); } catch (error) { console.error('Failed to retrieve simulator info:', error); process.exit(1); } } getSimulatorInfo();

Debug

Known issues

breakingIn `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.

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.

affects: >=3.0.0

breakingThe `spawn` method signature was updated in `simctl` v3.0.0. Code using the old signature will break.

fix

Refer to the official documentation or source code for the correct `spawn` method signature and adjust calls accordingly.

affects: >=3.0.0

breakingStarting 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.

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.

affects: >=2.0.0

gotcha`simctl` requires Xcode 8 or greater to be installed on macOS, and NodeJS 14.17.0 or greater.

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.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: output.toString is not a function

Attempting to call `toString()` on a `Buffer` object, but `simctl` v3.0.0+ now returns strings directly, not Buffers.

fix

Remove `.toString()` calls from the output of `simctl` methods, as the output is already a UTF-8 string.

Error: Command failed: xcrun simctl ... Error Domain=NSPOSIXErrorDomain Code=2 "No such file or directory"

`xcrun simctl` command failed, often due to an incorrect path, missing Xcode components, or an Xcode version older than the required 8+.

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.

TypeError: simctl.spawn is not a function or signature mismatch

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.

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.

Upgrade

Version history

0.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/ios-control/simctl ↗

packagehttps://www.npmjs.com/package/simctl ↗