Screenshots

Capture, frame, review, and upload App Store screenshots

Manage the full screenshot workflow from local capture to App Store upload.

Overview

The screenshots command provides both local automation for capturing and framing screenshots, and App Store operations for uploading and managing screenshots in your app listings.

Local Workflow (Experimental)

The local screenshot automation features are experimental. If you encounter issues, please file feedback.

Capture Screenshots

Capture screenshots from running simulators or applications:

asc screenshots capture --bundle-id "com.example.app" --name home

Supported Providers:

axe - Screenshot provider for iOS simulators
macos - Screenshot provider for macOS applications

Capture Options:

--bundle-id - Application bundle identifier
--name - Screenshot name (without extension)
--output-dir - Output directory for raw PNG files
--provider - Capture provider (axe or macos)
--udid - Simulator UDID or “booted”

Frame Screenshots

Add device frames and backgrounds to raw screenshots:

asc screenshots frame --input ./screenshots/raw/home.png --device iphone-air

Supported Devices:

iphone-air - iPhone Air (6.9”)
iphone-17-pro - iPhone 17 Pro (6.7”)
iphone-17-pro-max - iPhone 17 Pro Max (6.9”)
iphone-16e - iPhone 16e (6.1”)
iphone-17 - iPhone 17 (6.7”)
mac - macOS desktop

Framing Options:

--input - Path to raw screenshot PNG
--device - Frame device profile
--output - Output path for framed image
--title - Overlay title text
--subtitle - Overlay subtitle text
--title-color - Title text color (hex format)
--subtitle-color - Subtitle text color (hex format)

Requirements:

Koubou CLI tool (version 0.14.0 or higher)
Install via: brew install koubou or download from releases

Review Workflow

Generate, review, and approve framed screenshots:

# Generate review HTML
asc screenshots review-generate --framed-dir ./screenshots/framed

# Open review in browser
asc screenshots review-open --output-dir ./screenshots/review

# Approve ready screenshots
asc screenshots review-approve --all-ready --output-dir ./screenshots/review

Plan and Apply Approved Artifacts

Turn approved review artifacts into a deterministic upload plan before mutating remote screenshot state:

# Preview upload intent from approved review artifacts
asc screenshots plan --app "123456789" --version "1.2.3"

# Apply the approved upload plan
asc screenshots apply --app "123456789" --version "1.2.3" --confirm

Plan/Apply Options:

--app - App Store Connect app ID
--version - App Store version string
--version-id - App Store version ID (alternative to --version)
--review-output-dir - Directory containing manifest.json and approved.json
--skip-existing - Skip files whose checksum already exists remotely
--replace - Delete existing screenshots in each target set before uploading
--confirm - Required for apply

Run from Plan

Execute the full capture and framing workflow from a JSON plan:

asc screenshots run --plan .asc/screenshots.json

Plan Format:

{
  "screenshots": [
    {
      "name": "home",
      "bundle_id": "com.example.app",
      "device": "iphone-air",
      "title": "Welcome Home",
      "subtitle": "Your personalized dashboard"
    }
  ]
}

List Frame Devices

Show all supported frame device profiles:

asc screenshots list-frame-devices
asc screenshots list-frame-devices --output json

App Store Workflow

List Screenshots

List all screenshots for a version localization:

asc screenshots list --version-localization "LOC_ID"

Check Screenshot Sizes

Display supported screenshot dimensions and device types:

# Show common iOS submission sizes (iPhone 6.5" and iPad Pro 12.9")
asc screenshots sizes

# Show all supported sizes
asc screenshots sizes --all

# Filter by specific device type
asc screenshots sizes --display-type "APP_IPHONE_65"

Common Display Types:

APP_IPHONE_65 - iPhone 6.5” (required for most iOS submissions)
APP_IPAD_PRO_3GEN_129 - iPad Pro 12.9” (required for iPad submissions)
APP_IPHONE_67 - iPhone 6.7”
APP_IPHONE_61 - iPhone 6.1”

Upload Screenshots

Upload screenshots to App Store Connect:

# Upload single file
asc screenshots upload --version-localization "LOC_ID" \
  --path "./screenshot.png" \
  --device-type "IPHONE_65"

# Upload directory (all PNG files)
asc screenshots upload --version-localization "LOC_ID" \
  --path "./screenshots/iphone" \
  --device-type "IPHONE_65"

# Fan out across locale directories in one run
asc screenshots upload --app "123456789" \
  --version "1.2.3" \
  --path "./screenshots" \
  --device-type "IPHONE_65"

For app/version fan-out uploads, structure --path with locale directories such as ./screenshots/en-US/iphone/*.png and ./screenshots/fr-FR/iphone/*.png. Each locale directory is matched against the remote App Store version localizations, and only files matching the selected --device-type are uploaded from each locale subtree. A device-rooted layout such as ./screenshots/iphone/en-US/*.png also works when --path points at ./screenshots/iphone. File Requirements:

Format: PNG or JPEG
Exact dimensions must match the device type specification
Use asc screenshots sizes to verify required dimensions
Partial failures write a retry artifact under .asc/reports/screenshots-upload/

Resume a Failed Upload:

# Resume from the artifact printed by the failed run
asc screenshots upload \
  --resume ".asc/reports/screenshots-upload/failures-123.json"

Typical Submission:

# iPhone set (required)
asc screenshots upload --version-localization "LOC_ID" \
  --path "./screenshots/iphone" \
  --device-type "IPHONE_65"

# iPad set (for iPad apps)
asc screenshots upload --version-localization "LOC_ID" \
  --path "./screenshots/ipad" \
  --device-type "IPAD_PRO_3GEN_129"

# Multi-locale iPhone set
asc screenshots upload --app "123456789" \
  --version "1.2.3" \
  --path "./screenshots" \
  --device-type "IPHONE_65"

Download Screenshots

Download existing screenshots from App Store Connect:

asc screenshots download --version-localization "LOC_ID" \
  --output-dir "./screenshots/downloaded"

Delete Screenshots

Remove screenshots from a version localization:

asc screenshots delete --id "SCREENSHOT_ID" --confirm

Complete Example Workflow

# 1. Capture raw screenshots
asc screenshots capture --bundle-id "com.example.app" --name home
asc screenshots capture --bundle-id "com.example.app" --name profile
asc screenshots capture --bundle-id "com.example.app" --name settings

# 2. Frame screenshots with device bezels and text
asc screenshots frame --input ./screenshots/raw/home.png \
  --device iphone-air \
  --title "Welcome Home" \
  --subtitle "Your personalized dashboard"

asc screenshots frame --input ./screenshots/raw/profile.png \
  --device iphone-air \
  --title "Your Profile" \
  --subtitle "Manage your account"

# 3. Review framed screenshots
asc screenshots review-generate --framed-dir ./screenshots/framed
asc screenshots review-open --output-dir ./screenshots/review
asc screenshots review-approve --all-ready --output-dir ./screenshots/review

# 4. Preview upload intent from approved artifacts
asc screenshots plan --app "123456789" --version "1.2.3"

# 5. Apply the approved upload plan
asc screenshots apply --app "123456789" --version "1.2.3" --confirm

Video Previews - Manage app preview videos
Apps - Manage app metadata and versions

Overview

App Management

TestFlight & Builds

Monetization & Analytics

Signing

Review & Release

Team & Access

Automation & Utilities

Screenshots

Screenshots

Overview

Local Workflow (Experimental)

Capture Screenshots

Frame Screenshots

Review Workflow

Plan and Apply Approved Artifacts

Run from Plan

List Frame Devices

App Store Workflow

List Screenshots

Check Screenshot Sizes

Upload Screenshots

Download Screenshots

Delete Screenshots

Complete Example Workflow

​Screenshots

​Overview

​Local Workflow (Experimental)

​Capture Screenshots

​Frame Screenshots

​Review Workflow

​Plan and Apply Approved Artifacts

​Run from Plan

​List Frame Devices

​App Store Workflow

​List Screenshots

​Check Screenshot Sizes

​Upload Screenshots

​Download Screenshots

​Delete Screenshots

​Complete Example Workflow

​Related Commands

Screenshots

Overview

Local Workflow (Experimental)

Capture Screenshots

Frame Screenshots

Review Workflow

Plan and Apply Approved Artifacts

Run from Plan

List Frame Devices

App Store Workflow

List Screenshots

Check Screenshot Sizes

Upload Screenshots

Download Screenshots

Delete Screenshots

Complete Example Workflow

Related Commands