smix-simctl 0.1.0

smix-simctl — xcrun simctl child_process wrapper (outer crate). Ported from now-retired TS source: src/sim/simctl.ts. v3.1 c10.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

# smix-simctl

[![Crates.io](https://img.shields.io/crates/v/smix-simctl?style=flat-square&logo=rust)](https://crates.io/crates/smix-simctl)
[![docs.rs](https://img.shields.io/docsrs/smix-simctl?style=flat-square&logo=docs.rs)](https://docs.rs/smix-simctl)
[![License](https://img.shields.io/crates/l/smix-simctl?style=flat-square)](#license)

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

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

# async fn demo() -> Result<(), smix_simctl::SimctlError> {
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");
# Ok(())
# }
```

## 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`](https://crates.io/crates/smix-runner-client) for that)

Originally extracted from [smix](https://github.com/goliajp/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](../../LICENSE-APACHE)
- [MIT License](../../LICENSE-MIT)

at your option.