/asc-shots-pipeline

name: asc-shots-pipeline
description: Orchestrate iOS screenshot automation with xcodebuild/simctl for build-run, AXe for UI actions, JSON settings and plan files, Koubou-based framing (`asc screenshots frame`), and screenshot upload (`asc screenshots upload`). Use when users ask for automated screenshot capture, AXe-driven simulator flows, frame composition, or screenshot-to-upload pipelines.

asc screenshots pipeline (xcodebuild -> AXe -> frame -> asc)

Use this skill for agent-driven screenshot workflows where the app is built and launched with Xcode CLI tools, UI is driven with AXe, and screenshots are uploaded with `asc`.

Current scope

• Implemented now: build/run, AXe plan capture, frame composition, and upload.
• Device discovery is built-in via `asc screenshots list-frame-devices`.
• Local screenshot automation commands are experimental in asc cli.
• Framing is pinned to Koubou `0.18.1` for deterministic output.
• Feedback/issues: https://github.com/rorkai/App-Store-Connect-CLI/issues/new/choose

Defaults

• Settings file: `.asc/shots.settings.json`
• Capture plan: `.asc/screenshots.json`
• Raw screenshots dir: `./screenshots/raw`
• Framed screenshots dir: `./screenshots/framed`
• Default frame device: `iphone-air`

1) Create settings JSON first

Create or update `.asc/shots.settings.json`:

{
  "version": 1,
  "app": {
    "bundle_id": "com.example.app",
    "project": "MyApp.xcodeproj",
    "scheme": "MyApp",
    "simulator_udid": "booted"
  },
  "paths": {
    "plan": ".asc/screenshots.json",
    "raw_dir": "./screenshots/raw",
    "framed_dir": "./screenshots/framed"
  },
  "pipeline": {
    "frame_enabled": true,
    "upload_enabled": false
  },
  "upload": {
    "version_localization_id": "",
    "device_type": "IPHONE_65",
    "source_dir": "./screenshots/framed"
  }
}

If you intentionally skip framing, set:

• `"frame_enabled": false`
• `"upload.source_dir": "./screenshots/raw"`

2) Build and run app on simulator

Use Xcode CLI for build/install/launch:

xcrun simctl boot "$UDID" || true

xcodebuild \
  -project "MyApp.xcodeproj" \
  -scheme "MyApp" \
  -configuration Debug \
  -destination "platform=iOS Simulator,id=$UDID" \
  -derivedDataPath ".build/DerivedData" \
  build

xcrun simctl install "$UDID" ".build/DerivedData/Build/Products/Debug-iphonesimulator/MyApp.app"
xcrun simctl launch "$UDID" "com.example.app"

Use `xcodebuild -showBuildSettings` if the app bundle path differs from the default location.

3) Capture screenshots with AXe (or `asc screenshots run`)

Prefer plan-driven capture:

asc screenshots run --plan ".asc/screenshots.json" --udid "$UDID" --output json

Useful AXe primitives during plan authoring:

axe describe-ui --udid "$UDID"
axe tap --id "search_field" --udid "$UDID"
axe type "wwdc" --udid "$UDID"
axe screenshot --output "./screenshots/raw/home.png" --udid "$UDID"

Minimal `.asc/screenshots.json` example:

{
  "version": 1,
  "app": {
    "bundle_id": "com.example.app",
    "udid": "booted",
    "output_dir": "./screenshots/raw"
  },
  "steps": [
    { "action": "launch" },
    { "action": "wait", "duration_ms": 800 },
    { "action": "screenshot", "name": "home" }
  ]
}

4) Frame screenshots with `asc screenshots frame`

The asc CLI pins framing to Koubou `0.18.1`. Install and verify before running framing steps:

pip install koubou==0.18.1
kou --version  # expect 0.18.1
# If Koubou reports missing device frames, run once with network access:
kou setup-frames

List supported frame device values first:

asc screenshots list-frame-devices --output json

Frame one screenshot (defaults to `iphone-air`):

asc screenshots frame \
  --input "./screenshots/raw/home.png" \
  --output-dir "./screenshots/framed" \
  --device "iphone-air" \
  --output json

Supported `--device` values:

• `iphone-air` (default)
• `iphone-17-pro`
• `iphone-17-pro-max`
• `iphone-16e`
• `iphone-17`
• `mac`

5) Upload screenshots with asc

Generate and review artifacts before upload:

asc screenshots review-generate --framed-dir "./screenshots/framed" --output-dir "./screenshots/review"
asc screenshots review-open --output-dir "./screenshots/review"
asc screenshots review-approve --all-ready --output-dir "./screenshots/review"

For reviewed multi-locale sets, prefer the plan/apply flow so existing remote screenshot counts are included before upload:

asc screenshots plan --app "APP_ID" --version "1.2.3" --review-output-dir "./screenshots/review" --output json
asc screenshots apply --app "APP_ID" --version "1.2.3" --review-output-dir "./screenshots/review" --confirm --output json

Upload from the configured source directory (default `./screenshots/framed` when framing is enabled):

asc screenshots upload \
  --version-localization "LOC_ID" \
  --path "./screenshots/framed" \
  --device-type "IPHONE_65" \
  --output json

List or validate before upload when needed:

asc screenshots sizes --output table
asc screenshots list --version-localization "LOC_ID" --output table

Agent behavior

• Always confirm exact flags with `--help` before running commands.
• Re-check command paths with `asc screenshots --help` because screenshot commands are evolving quickly.
• Keep outputs deterministic: default to JSON for machine steps.
• Prefer `asc screenshots list-frame-devices --output json` before selecting a frame device.
• Ensure screenshot files exist before upload.
• Use explicit long flags (`--app`, `--output`, `--version-localization`, etc.).
• Treat screenshot-local automation as experimental and call it out in user-facing handoff notes.
• Use `asc screenshots plan` / `asc screenshots apply` for reviewed batches when you need append-limit guardrails across existing remote screenshots.
• If framing fails with a version error, re-install pinned Koubou: `pip install koubou==0.18.1`.
• If framing fails because devi