Skip to main content

​
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:
  1. App Store Workflow: Upload and manage screenshots in App Store Connect
  2. 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

1

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).
2

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
3

Upload iPhone screenshots

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

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/rudrankriyam/App-Store-Connect-CLI/issues/new/choose

​
Complete Local Workflow

1

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.
2

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
3

Generate HTML review gallery

Create an HTML page to review all screenshots:
asc screenshots review-generate \
  --framed-dir "./screenshots/framed" \
  --output-dir "./screenshots/review"
4

Open review in browser

asc screenshots review-open --output-dir "./screenshots/review"
This opens a browser with an interactive gallery for review.
5

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.
6

Preview uploads from approved screenshots

Build a deterministic upload plan from the approved review artifacts:
asc screenshots plan \
  --app "123456789" \
  --version "1.2.3"
7

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:
  1. Launch iOS Simulator
  2. Open your app in the simulator
  3. 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

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