sim-cli

Agent-friendly iOS simulator CLI. Thin wrapper around simctl and an idb companion gRPC endpoint, with JSON in / JSON out for easy scripting.

Requirements

• macOS with Xcode + xcrun simctl
• Bun
• An idb_companion running against your simulator (default: localhost:10882)
• Optional: xcpretty — run pipes xcodebuild output through it when available

Install

bun install
bun run build    # produces ./dist/sim-cli

Or run directly:

bun run src/index.ts --help

Usage

sim-cli [--udid <id|booted>] [--companion <host:port>] <command> [args]

Defaults: --udid booted, --companion localhost:10882. Overridable via IDB_UDID / IDB_COMPANION env vars.

Run sim-cli --help for the full grouped reference.

Commands

Device

Command	Description
list-devices	list all simulators
list-apps	list installed apps
uninstall <bundle_id>	remove app

App lifecycle

Command	Description
run <bundle_id> [args...]	build → install → terminate prior → launch → wait. Skip steps with --no-build, --no-install, --no-terminate, --no-wait. Use --app <path> for a prebuilt artifact. Auto-detects .xcworkspace / .xcodeproj + scheme; override with --workspace, --project, --scheme, --configuration. Enabled LaunchAction env vars + command-line args from the matching .xcscheme are picked up automatically; pass extra/override env via --env KEY=VAL (repeatable).
openurl <url>	open a URL / deep link

Observe

Command	Description
screenshot [--out file.png] [--base64]	capture screen as PNG
describe [--point x,y] [--screenshot]	accessibility tree (+ optional base64 PNG)
logs [--follow] [--last 1m] [-v]	one-shot returns a JSON array of parsed log show --style ndjson entries (each has timestamp, subsystem, category, processImagePath, eventMessage, etc.). --follow streams ndjson, one JSON object per line. Apple system subsystems are dropped by default; -v includes them plus info/debug levels. Filter to a specific app or message client-side with jq.

Interact

Command	Description
tap <x> <y> [--duration s]	tap at coordinates; or tap --label|--role|--text <s> to tap matched element's centroid
swipe <x1> <y1> <x2> <y2> [--duration s] [--delta n]	swipe between points
type "<string>"	send keystrokes to focused field
press <home|lock|siri|side_button|apple_pay> [--duration s]	press a hardware button

All commands write JSON to stdout on success and {"error": "..."} to stderr on failure with a non-zero exit code.

License

MIT — see LICENSE. src/idb.proto is derived from facebook/idb (also MIT).