Screenshots and Previews

Manage App Store screenshots and preview videos

Manage your App Store screenshots from capture to upload, including local automation workflows (experimental).

Overview

The CLI provides two screenshot workflows:

App Store Workflow: Upload and manage screenshots in App Store Connect
Local Automation (Experimental): Capture, frame, review, and prepare screenshots locally

App Store Screenshot Management

Understanding Screenshot Requirements

View required screenshot sizes for App Store submission:

asc screenshots sizes

For the full matrix including all device types:

asc screenshots sizes --all

For most iOS submissions, you need:

One iPhone set: IPHONE_65 (6.5” display)
One iPad set: IPAD_PRO_3GEN_129 (12.9” iPad Pro 3rd gen)

The App Store will automatically scale these to other sizes.

Upload Screenshots

Find your version localization ID

List localizations for your app version:

asc localizations list --version "VERSION_ID" --output json

Extract the localization ID for your target locale (e.g., en-US).

Prepare screenshot files

Organize screenshots by device type:

screenshots/
├── iphone/
│   ├── 01-home.png
│   ├── 02-features.png
│   └── 03-settings.png
└── ipad/
    ├── 01-home.png
    ├── 02-features.png
    └── 03-settings.png

Upload iPhone screenshots

asc screenshots upload \
  --version-localization "LOCALIZATION_ID" \
  --path "./screenshots/iphone" \
  --device-type "IPHONE_65"

Upload iPad screenshots

asc screenshots upload \
  --version-localization "LOCALIZATION_ID" \
  --path "./screenshots/ipad" \
  --device-type "IPAD_PRO_3GEN_129"

Device Types

Common device types for screenshots: iPhone:

IPHONE_65 - 6.5” display (iPhone 14 Plus, etc.)
IPHONE_55 - 5.5” display (iPhone 8 Plus)
IPHONE_40 - 4” display (iPhone SE 1st gen)

iPad:

IPAD_PRO_3GEN_129 - 12.9” iPad Pro (3rd gen)
IPAD_PRO_129 - 12.9” iPad Pro (1st/2nd gen)
IPAD_105 - 10.5” iPad Pro
IPAD_97 - 9.7” iPad

Apple Watch:

APPLE_WATCH_SERIES_7 - 45mm Series 7
APPLE_WATCH_SERIES_4 - 44mm Series 4
APPLE_WATCH_SERIES_3 - 42mm Series 3

Mac:

DESKTOP

Apple TV:

APPLE_TV

List Existing Screenshots

asc screenshots list --version-localization "LOCALIZATION_ID"

Filter client-side by device type:

asc screenshots list \
  --version-localization "LOCALIZATION_ID" \
  --output json | jq '.data[] | select(.attributes.displayType == "IPHONE_65")'

Download Screenshots

Download all screenshots for a localization:

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

Delete Screenshots

Delete a specific screenshot:

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

Deleting screenshots is permanent. Download backups before deleting.

Local Screenshot Automation (Experimental)

Local screenshot commands are experimental. Please report issues at: https://github.com/rorkai/App-Store-Connect-CLI/issues/new/choose

Complete Local Workflow

Capture screenshots from simulator

Launch your app in iOS Simulator, then capture screenshots:

asc screenshots capture \
  --bundle-id "com.example.myapp" \
  --name "home-screen" \
  --output "./screenshots/raw"

This captures from the currently running simulator.

Frame screenshots with device bezel

Add device frame around raw screenshots:

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

See available device frames:

asc screenshots list-frame-devices

Generate HTML review gallery

Create an HTML page to review all screenshots:

asc screenshots review-generate \
  --framed-dir "./screenshots/framed" \
  --output-dir "./screenshots/review"

Open review in browser

asc screenshots review-open --output-dir "./screenshots/review"

This opens a browser with an interactive gallery for review.

Approve screenshots

Mark screenshots as ready for upload:

asc screenshots review-approve \
  --all-ready \
  --output-dir "./screenshots/review"

Or approve selectively in the browser UI.

Preview uploads from approved screenshots

Build a deterministic upload plan from the approved review artifacts:

asc screenshots plan \
  --app "123456789" \
  --version "1.2.3"

Apply the approved upload plan

Apply the reviewed upload plan explicitly:

asc screenshots apply \
  --app "123456789" \
  --version "1.2.3" \
  --confirm

Screenshot Plan Automation

Define a complete screenshot plan in .asc/screenshots.json:

{
  "bundle_id": "com.example.myapp",
  "device_types": ["iphone-air", "ipad-pro-129"],
  "locales": ["en-US", "es-ES", "ja"],
  "screenshots": [
    {
      "name": "home",
      "description": "Home screen showing main features",
      "device_type": "iphone-air"
    },
    {
      "name": "feature-detail",
      "description": "Detailed feature view",
      "device_type": "iphone-air"
    },
    {
      "name": "settings",
      "description": "Settings and customization",
      "device_type": "iphone-air"
    }
  ],
  "output_dirs": {
    "raw": "./screenshots/raw",
    "framed": "./screenshots/framed",
    "review": "./screenshots/review"
  }
}

Run the entire workflow:

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

Available Frame Devices

List supported devices for framing:

asc screenshots list-frame-devices --output json

Common devices:

iphone-air - iPhone with edge-to-edge display
iphone-14-pro - iPhone 14 Pro
iphone-se - iPhone SE
ipad-pro-129 - 12.9” iPad Pro
ipad-air - iPad Air
apple-watch-series-7 - Apple Watch Series 7

Complete Screenshot Workflow Example

Here’s a complete workflow for managing screenshots:

#!/bin/bash
set -e

# Configuration
export ASC_APP_ID="YOUR_APP_ID"
VERSION_ID="YOUR_VERSION_ID"
BUNDLE_ID="com.example.myapp"

# 1. Get localization IDs
echo "Getting localization IDs..."
EN_US_LOC_ID=$(asc localizations list --version "$VERSION_ID" --output json | \
  jq -r '.data[] | select(.attributes.locale == "en-US") | .id')

echo "en-US Localization ID: $EN_US_LOC_ID"

# 2. Create directories
mkdir -p screenshots/{raw,framed,iphone,ipad}

# 3. Capture screenshots (requires simulator running)
echo "Launch your app in iOS Simulator and press enter..."
read

for screen in home features settings details; do
  echo "Navigate to $screen screen and press enter..."
  read
  asc screenshots capture \
    --bundle-id "$BUNDLE_ID" \
    --name "$screen" \
    --output "./screenshots/raw"
done

# 4. Frame screenshots
echo "Framing screenshots..."
for raw_file in screenshots/raw/*.png; do
  filename=$(basename "$raw_file")
  asc screenshots frame \
    --input "$raw_file" \
    --device "iphone-air" \
    --output "./screenshots/framed/$filename"
done

# 5. Copy to upload directories
cp screenshots/framed/*.png screenshots/iphone/

# 6. Upload to App Store Connect
echo "Uploading iPhone screenshots..."
asc screenshots upload \
  --version-localization "$EN_US_LOC_ID" \
  --path "./screenshots/iphone" \
  --device-type "IPHONE_65"

echo "Screenshots uploaded successfully!"

# 7. Verify upload
asc screenshots list --version-localization "$EN_US_LOC_ID"

If an upload stops partway through, the command prints a failure artifact path like .asc/reports/screenshots-upload/failures-123.json. Resume the remaining files with:

asc screenshots upload --resume ".asc/reports/screenshots-upload/failures-123.json"

Preview Videos

Upload app preview videos:

Upload Preview Video

asc video-previews upload \
  --version-localization "LOCALIZATION_ID" \
  --path "./previews/app-preview.mp4" \
  --device-type "IPHONE_65"

Preview Video Requirements

Format: H.264 or HEVC codec, .mov or .mp4
Duration: 15-30 seconds
Resolution: Matches device screenshot size
File size: Up to 500 MB
Aspect ratio: Matches device (typically 16:9 or device aspect)

Multi-Locale Screenshot Workflow

For apps with multiple localizations, you can now fan out one upload across all matching locale directories:

asc screenshots upload \
  --app "YOUR_APP_ID" \
  --version "1.2.3" \
  --path "./screenshots" \
  --device-type "IPHONE_65"

Recommended directory layout:

screenshots/
  en-US/
    iphone/
      01-home.png
      02-settings.png
  fr-FR/
    iphone/
      01-home.png
  ja/
    iphone/
      01-home.png

The command resolves the app store version, fetches its version localizations, and uploads each locale subtree to the matching remote localization. It only includes files whose dimensions match the selected --device-type, so mixed iPhone/iPad locale trees are safe as long as each locale contains the slot you are uploading. A device-rooted layout such as screenshots/iphone/en-US also works when --path points at ./screenshots/iphone. For CI or large locale batches, save the printed failure artifact as a workflow artifact so a rerun can continue with asc screenshots upload --resume <artifact>.

Troubleshooting

”Invalid image dimensions”

Problem: Screenshot dimensions don’t match the device type. Solution: Verify required dimensions:

asc screenshots sizes

Ensure your images match exactly:

iPhone 6.5”: 1242 x 2688 pixels
iPad Pro 12.9”: 2048 x 2732 pixels

”Capture failed - no simulator running”

Problem: asc screenshots capture requires a running simulator. Solution:

Launch iOS Simulator
Open your app in the simulator
Run the capture command

”Frame device not found”

Problem: Invalid device name for framing. Solution: List available devices:

asc screenshots list-frame-devices

Use exact device names from the output.

”Upload failed - file too large”

Problem: Image file size exceeds limits. Solution: Optimize images:

# Using ImageMagick
mogrify -quality 85 -resize '1242x2688>' screenshots/*.png

# Using pngquant for compression
pngquant --quality=80-95 screenshots/*.png

Best Practices

Use consistent naming: Name screenshots clearly (01-home.png, 02-features.png)
Optimize file sizes: Compress screenshots to reduce upload time while maintaining quality
Follow Apple guidelines:
- No UI chrome (status bars are optional)
- Show actual app content
- Use device-appropriate assets
Localize screenshots: Create locale-specific screenshots showing localized UI
Test on real devices: Capture from actual devices when possible for best quality
Version control: Keep screenshot sources in git for easy updates
Automate where possible: Use the local workflow tools to streamline repetitive tasks
Review before upload: Always review screenshots in context before uploading to App Store Connect

Metadata Management - Manage app descriptions and metadata
App Store Submission - Submit with screenshots
Localizations API - Manage version localizations

Getting Started

Core Concepts

Guides

CI/CD Integration

Configuration

Screenshots

Screenshots and Previews

Overview

App Store Screenshot Management

Understanding Screenshot Requirements

Upload Screenshots

Device Types

List Existing Screenshots

Download Screenshots

Delete Screenshots

Local Screenshot Automation (Experimental)

Complete Local Workflow

Screenshot Plan Automation

Available Frame Devices

Complete Screenshot Workflow Example

Preview Videos

Upload Preview Video

Preview Video Requirements

Multi-Locale Screenshot Workflow

Troubleshooting

”Invalid image dimensions”

”Capture failed - no simulator running”

”Frame device not found”

”Upload failed - file too large”

Best Practices

​Screenshots and Previews

​Overview

​App Store Screenshot Management

​Understanding Screenshot Requirements

​Upload Screenshots

​Device Types

​List Existing Screenshots

​Download Screenshots

​Delete Screenshots

​Local Screenshot Automation (Experimental)

​Complete Local Workflow

​Screenshot Plan Automation

​Available Frame Devices

​Complete Screenshot Workflow Example

​Preview Videos

​Upload Preview Video

​Preview Video Requirements

​Multi-Locale Screenshot Workflow

​Troubleshooting

​”Invalid image dimensions”

​”Capture failed - no simulator running”

​”Frame device not found”

​”Upload failed - file too large”

​Best Practices

​Related Commands

Screenshots and Previews

Overview

App Store Screenshot Management

Understanding Screenshot Requirements

Upload Screenshots

Device Types

List Existing Screenshots

Download Screenshots

Delete Screenshots

Local Screenshot Automation (Experimental)

Complete Local Workflow

Screenshot Plan Automation

Available Frame Devices

Complete Screenshot Workflow Example

Preview Videos

Upload Preview Video

Preview Video Requirements

Multi-Locale Screenshot Workflow

Troubleshooting

”Invalid image dimensions”

”Capture failed - no simulator running”

”Frame device not found”

”Upload failed - file too large”

Best Practices

Related Commands