Metadata-Version: 2.4
Name: xcshot
Version: 0.2.0
Summary: Real iOS simulator screenshots from Linux: trigger an Xcode Cloud test workflow, download the xcresult, extract labeled PNGs. No Mac, no xcresulttool.
Project-URL: Homepage, https://github.com/BariBariGood/xcshot
Project-URL: Repository, https://github.com/BariBariGood/xcshot
Project-URL: Issues, https://github.com/BariBariGood/xcshot/issues
Author: Ivan Del Rio
License-Expression: MIT
License-File: LICENSE
Keywords: app-store-connect,ios,linux,png,screenshots,simulator,xcode-cloud,xcresult
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics :: Capture :: Screen Capture
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: cryptography>=41
Requires-Dist: pyjwt>=2.6
Requires-Dist: zstandard>=0.20
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=2.0; extra == 'mcp'
Description-Content-Type: text/markdown

# xcshot

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

xcshot drives [Xcode Cloud](https://developer.apple.com/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.

![xcshot shoot demo](https://raw.githubusercontent.com/BariBariGood/xcshot/main/assets/demo.gif)

## 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

```sh
pipx install xcshot        # or: pip install xcshot
```

## Commands

| command | what it does |
|---|---|
| `xcshot extract <bundle.xcresult> -o dir` | extract labeled PNGs from any xcresult — fully offline |
| `xcshot products -w` | list your Xcode Cloud products and workflows |
| `xcshot runs <workflow>` | list recent build runs |
| `xcshot pull --latest -w <workflow>` | download + extract an existing run's screenshots |
| `xcshot shoot -w <workflow> -b <branch>` | trigger → wait → download → extract, one command |
| `xcshot workflow-create --product <id> --scheme <s> --container <p>` | create the manual-start simulator TEST workflow via API |

Auth: three env vars (`ASC_API_KEY_ID`, `ASC_API_ISSUER_ID`,
`ASC_API_KEY_P8`). See [docs/SETUP.md](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`](templates/Screenshots.swift) UI-test capture
template. Running from CI instead of a laptop? There's a copy-pasteable
[GitHub Actions recipe](docs/github-actions.md). Agents: there's a ready-made
[Agent Skill](.agents/skills/xcshot/SKILL.md).

## MCP server

Agents can use xcshot as [MCP](https://modelcontextprotocol.io) tools:
`pip install "xcshot[mcp]"` and point your client at the `xcshot-mcp`
command. See [docs/mcp.md](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](https://github.com/MobAI-App/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
