Skip to main content

​
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