Crate smix_simctl 

smix-simctl

Async Rust wrapper around Apple’s xcrun simctl command-line tool. Boot / shutdown / launch / install / pasteboard / screenshot — every simulator-management subcommand wrapped in a typed tokio::process-backed client.

This crate exists because every Rust project doing iOS simulator automation re-implements the same Command::new("xcrun").arg("simctl")... boilerplate, parses the same JSON outputs, fights the same pbcopy stdin-pipe edge case. smix-simctl does it once, cleanly typed.

Quickstart

use smix_simctl::{Appearance, SimctlClient, SimctlPermission};
use std::time::Duration;

let simctl = SimctlClient::new();

// 1. Inventory
let runtimes = simctl.list_runtimes().await?;
let devices = simctl.list_devices().await?;
let booted: Vec<_> = devices.iter().filter(|d| d.state == "Booted").collect();

// 2. Lifecycle (idempotent on already-booted)
let udid = "4F0B35D2-03F0-4A8F-B729-09072153E8AE";
simctl.boot_and_wait(udid, Duration::from_secs(60)).await?;
let launched = simctl.launch(udid, "com.example.app").await?;
println!("launched pid={}", launched.pid);

// 3. Settings
simctl.set_appearance(udid, Appearance::Dark).await?;
simctl.grant_permission(udid, SimctlPermission::Camera, "com.example.app").await?;
simctl.set_reduce_motion(udid, true).await?;

// 4. IO
let png = simctl.screenshot(udid).await?;
std::fs::write("/tmp/screen.png", png).unwrap();

// 5. Pasteboard
simctl.pasteboard_set(udid, "hello clipboard").await?;
let got = simctl.pasteboard_get(udid).await?;
assert_eq!(got, "hello clipboard");

Methods

Category	Methods
Inventory	list_runtimes, list_devices
Lifecycle	boot, boot_and_wait, shutdown, erase, install, uninstall, terminate, launch
Settings	set_appearance, grant_permission, keychain_reset, set_reduce_motion
Pasteboard	pasteboard_get, pasteboard_set
URL	open_url
IO	screenshot (returns Vec<u8> PNG bytes)
Provisioning	create_device, delete_device

When to reach for this vs. shelling out yourself

Use case	Pick
Need typed SimctlDevice / SimctlRuntime with is_available filter	smix-simctl
Want boot_and_wait polling logic without re-implementing it	smix-simctl
Need pasteboard_set (handles pbcopy stdin-pipe correctly)	smix-simctl
One-off shell script wrapping a single xcrun simctl boot call	plain Command
Need real-device control (instruments, devicectl)	out of scope — this is sim-only

Scope

• ✅ All async, returns typed SimctlError variants
• ✅ Uses tokio::process::Command for spawn
• ✅ Parses JSON outputs (list devices -j, etc.) into typed structs
• ✅ screenshot returns raw PNG bytes — no PNG parsing dep needed
• ❌ No real-device support — this is xcrun simctl only
• ❌ No instruments / devicectl integration
• ❌ No XCUITest runner spawning (see smix-runner-client for that)

Originally extracted from smix as a standalone stone. The crate is intentionally smix-business-decoupled — any Rust project doing iOS-Simulator automation can adopt it without pulling in the rest of smix.

License

Dual-licensed under either:

• Apache License 2.0
• MIT License

at your option. smix-simctl — xcrun simctl child_process wrapper (outer crate).

Ported from now-retired TS source: src/sim/simctl.ts (375 lines). All operations shell out to xcrun simctl <subcommand>; JSON-formatted outputs (list runtimes, list devices, screenshot binary) are parsed with serde_json / raw bytes. Tokio’s process::Command is the async spawn primitive.

This is an outer crate (per user 2026-05-25 brief — outer crates allowed to depend on the wider tokio ecosystem). Use it from cement (smix-cli / smix-mcp) or from a higher-level driver wrapper.

Modules

registry

.smix/sims.json device registry — deterministic device addressing.

Structs

LaunchResult

Launched-app result. TS returns { pid: number }; we follow suit.

RecordingHandle

v5.2 c5 — handle to an active xcrun simctl io recordVideo child process. Pair with SimctlClient::record_video_stop for SIGINT-and-wait shutdown (so the mp4 trailer is flushed). Dropping the handle without stop would tokio-SIGKILL on Drop and truncate the output file.

SimctlClient

Stateless wrapper around xcrun simctl. Methods are free functions in spirit (no instance state beyond optionally-cached xcrun path); kept as a struct for API ergonomics + future caching.

SimctlDevice

One simulator device known to xcrun simctl.

SimctlRuntime

One iOS / watchOS / tvOS runtime installed on the host.

Enums

Appearance

UI appearance mode for xcrun simctl ui <udid> appearance.

SimctlError

Failure variants for any xcrun simctl invocation.

SimctlPermission

Permission names accepted by xcrun simctl privacy <udid> grant <name>. Mirrors TS SimctlPermission 1:1.

Functions

compose_child_env

v6.8 c2 — compose user-provided (key, value) pairs into the SIMCTL_CHILD_* envp that xcrun simctl launch strips and delivers to the launched app. Idempotent: a key that already starts with SIMCTL_CHILD_ is passed through unchanged. Insight gol-611 §4 reference: their prelaunch-sim-app.ts does the same composition.