simctl-list
List iOS simulators with intelligent caching and progressive disclosure. Returns concise summaries by default, preventing token overflow, with cache IDs for full details. Shows booted and recent devices first for faster workflows.
Instructions
simctl-list
List iOS simulators with intelligent progressive disclosure and caching.
Overview
Retrieves comprehensive simulator information including devices, runtimes, and device types. Returns concise summaries by default with cache IDs for progressive access to full details, preventing token overflow while maintaining complete functionality. Shows booted devices and recently used simulators first for faster workflows. Full output mode limits results to the most recently used devices for efficient browsing.
Parameters
Required
None - all parameters are optional
Optional
deviceType (string): Filter by device type (e.g., "iPhone", "iPad")
runtime (string): Filter by iOS runtime version (e.g., "17", "iOS 17.0")
availability (string, default: "available"): Filter by availability ("available", "unavailable", "all")
outputFormat (string, default: "json"): Output format ("json" or "text")
concise (boolean, default: true): Return concise summary with cache ID
max (number, default: 5): Maximum devices to return in full mode, sorted by lastUsed date (most recent first)
Returns
Concise mode: Summary with cacheId for detailed retrieval via simctl-get-details
Full mode: Limited device list (default 5 most recently used) with metadata showing total available and limit applied
Device Limiting in Full Mode
When concise: false, the response includes:
devices: Top N devices across all runtimes, sorted by lastUsed date (most recent first)
metadata: Shows total devices in cache, devices returned, and limit applied
Devices without lastUsed date are placed at the end
Total limit applies across all runtimes, not per-runtime
Examples
Get concise summary (default - prevents token overflow)
await simctlListTool({});Get full list for iPhone devices (limited to 5 most recent)
await simctlListTool({
deviceType: "iPhone",
concise: false
});Get full list with custom device limit
await simctlListTool({
concise: false,
max: 10
});Filter by iOS version
await simctlListTool({ runtime: "17.0" });Related Tools
simctl-get-details: Retrieve full device list using cache ID (bypasses max limit)
simctl-device: Boot, shutdown, or manage specific simulators
simctl-app: Install and launch apps on simulators
Notes
Prevents token overflow (raw output = 10k+ tokens) via concise summaries and device limiting
Default max=5 limits output to ~2.5k tokens (90% reduction from full 50-device list)
1-hour intelligent caching eliminates redundant queries
Shows booted devices and recently used simulators first in concise mode
Use simctl-get-details with cacheId for progressive access to full data (ignores max limit)
Device sorting: mostRecent (with lastUsed) → oldest (with lastUsed) → unknown (no lastUsed)
Smart filtering by device type, runtime, and availability
Essential: Use this instead of 'xcrun simctl list' for better performance
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| deviceType | No | ||
| runtime | No | ||
| availability | No | available | |
| outputFormat | No | json | |
| concise | No | ||
| max | No |