xcshot

Real iOS simulator screenshots from Linux (or Windows, or anything). No Mac, no Xcode, no xcresulttool.

xcshot drives Xcode Cloud through the App Store Connect API: it triggers a UI-test workflow on an Apple-hosted simulator, waits, downloads the .xcresult artifact, and extracts labeled PNG screenshots — entirely with portable Python.

Why this exists

Every existing .xcresult tool (xcparse, XCResultKit, xcresultparser, …) is Swift and shells out to Apple's xcresulttool, so they only run on macOS. But an xcresult's Data/ directory is just a content-addressed store of raw or zstd-compressed blobs — and a PNG can carry its own name in a tEXt chunk. So xcshot's extractor byte-scans the store for PNG magic, reads the embedded names, and writes labeled files. Any OS, no Apple tooling.

Pair that with Xcode Cloud (25 free compute hours/month with an Apple Developer membership) and a $200 laptop can see a real iOS app running on a real simulator.

Install

pipx install xcshot        # or: pip install xcshot

Commands

Auth: three env vars (ASC_API_KEY_ID, ASC_API_ISSUER_ID, ASC_API_KEY_P8). See docs/SETUP.md for the full walkthrough, including the one-time Xcode Cloud onboarding (the only step that ever needs Xcode) and the templates/Screenshots.swift UI-test capture template. Running from CI instead of a laptop? There's a copy-pasteable GitHub Actions recipe. Agents: there's a ready-made Agent Skill.

MCP server

Agents can use xcshot as MCP tools: pip install "xcshot[mcp]" and point your client at the xcshot-mcp command. See docs/mcp.md for client config and the tool list.

What it is / isn't

• Is: a way to get real simulator pixels from a machine that can't run a simulator — for visual review, App Store listing shots, agents, docs.
• Isn't: an interactive dev loop. Each shot is a ~10-minute Xcode Cloud round trip; you can't tap on things between frames. Unsigned builds, hot reload, and on-device installs are a different problem (see ios-builder).

Requirements

• Apple Developer Program membership (Xcode Cloud requires it; the free tier is 25 compute hours/month ≈ ~150 screenshot runs).
• A native Xcode project with a UI-test target (generated projects work via a ci_scripts/ci_post_clone.sh hook — see SETUP.md).
• One-time product onboarding in Xcode: the ASC API can create workflows but not products (no POST /v1/ciProducts), so the very first link between app and Xcode Cloud needs Xcode once. Mac-free forever after.

License

MIT