/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.20.0` 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.20.0`. Install and verify before running framing steps:

pip install koubou==0.20.0
kou --version  # expect 0.20.0
# After upgrading from 0.18.x, or 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: `iphone-air` (default), `iphone-17-pro`, `iphone-17-pro-max`, `iphone-16e`, `iphone-17`
• iPad: `ipad-pro-13`, `ipad-pro-11`, `ipad-air-13`, `ipad-air-11`, `ipad-mini`
• Other: `mac`, `watch-series-11`, `watch-ultra-3`, `apple-tv`

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

Change the order of an uploaded set without re-uploading. `--ids` must list every screenshot in the set exactly once, in the new order. If a screenshot is added after the command reads the set, App Store Connect rejects the update and keeps the order it had before the update; list the set again and re-run. An order-only change made by someone else is not detected and is overwritten.

asc localizations screenshot-sets list --localization-id "LOC_ID" --include appScreenshots
asc screenshots list --set-id "SET_ID" --output table
asc screenshots reorder --set-id "SET_ID" --ids "THIRD_ID,FIRST_ID,SECOND_ID"

Agent behavior

• Always confirm exact flags with `--he