Appshot 📸

AI-First CLI for App Store Screenshots - Generate beautiful, localized screenshots with device frames, gradients, and captions.

🌐 https://appshot.sh

🆕 Version 2.0.0 - Layout v2 + Agent-First Architecture

• MCP Server: Full Model Context Protocol support for AI agents (Claude Desktop, Claude Code, etc.)
• 20 MCP Tools: Complete coverage - init, build, wizard, quickstart, template, captions, gradients, backgrounds, fonts, config, validate, specs, doctor, presets, localize, languages, frame, export, clean, projectInfo
• Claude Code Skill: Install with appshot skill - includes templates, troubleshooting guides
• Auto-Caption: Generate captions from filenames with --auto-caption or MCP action: "auto"
• Direct Tool Access: Agents can manage entire screenshot workflows without shell access

📖 Table of Contents

• Why Appshot?
• Features
• Quick Start
  • Prerequisites
  • Installation
  • Wizard (Recommended)
  • Your First Screenshot
  • Cleaning & Reset
• MCP Server & Agent Integration
• Core Concepts
• Visual Customization
  • Gradient System
  • Font System
  • Device Frames
  • Caption System
• Localization & Translation
• Device Support
• Fastlane Integration
• Command Reference
• Configuration Reference
• Agent & Automation Guide
• Recipes & Examples
• Troubleshooting
• Development
• Roadmap
• License & Support

🌟 Why Appshot?

Appshot is the only agent-first CLI tool designed for automated App Store screenshot generation. Built for LLM agents, CI/CD pipelines, and developers who value automation over GUIs.

NEW in v2.0.0: Fixed layout zones and v2 templates for clean, predictable screenshots out of the box.

Key Differentiators

• 🤖 Agent-First Design - JSON outputs, predictable commands, no interactive prompts in automation mode
• 🎯 Smart Automation - Auto-detects orientation, selects appropriate frames, handles batch operations
• 🌍 AI-Powered Localization - Translate captions in real-time using GPT-4o, GPT-5, o1, and o3 models
• 📏 App Store Compliant - Built-in validation for all official Apple App Store specifications
• ⚡ Fast & Parallel - Process hundreds of screenshots with configurable concurrency
• 🛠️ Pure CLI - No web UI, no GUI, just predictable commands perfect for automation

📱 iPhone Screenshot Examples (v2)

These are generated by the v2 templates included in template-samples/iphone/:

Ocean Header	Sunset Footer	Clean Screenshot
Pastel Header	Noir Footer	Silver Header
Slate Footer	Midnight Header	Tropical Header

For the full template gallery, open template-samples/index.html.

✨ Features

• 🖼️ Smart Frames - Automatically detects portrait/landscape and selects appropriate device frame
• 🎨 Gradient Presets - 24+ beautiful gradients with visual preview and easy application
• 🔤 Font System - 50+ font mappings, direct font setting, interactive selection, and system detection
• 📦 Embedded Fonts - 10 high-quality open source fonts bundled for consistent rendering everywhere
• ✏️ Dynamic Captions - Smart text wrapping, auto-sizing, and multi-line support
• 🌍 AI Translation - Real-time and batch translation using OpenAI's latest models
• 📱 Multi-Device - iPhone, iPad, Mac, Apple TV, Vision Pro, and Apple Watch support
• 🎭 Frame-Only Mode - Quick device framing with transparent backgrounds (no gradients/captions)
• 📏 App Store Specs - All official resolutions with validation and presets
• 🔄 Orientation Detection - Intelligently handles both portrait and landscape
• 👁️ Watch Mode - File system monitoring with auto-processing (macOS)
• 📱 Device Capture - Direct capture from iOS simulators (macOS)
• ⚡ Parallel Processing - Configurable concurrency for large batches
• 🔍 Caption Autocomplete - Intelligent suggestions with fuzzy search and learning
• 🔬 Dry-Run Mode - Preview what would be built without generating images
• 🐛 Verbose Debugging - Detailed rendering metrics for troubleshooting

🚀 Quick Start

Prerequisites

• Node.js 18+ - Required for ESM modules
• npm or yarn - Package manager
• Operating System - macOS, Linux, or Windows
• Optional: OpenAI API key for translation features

Installation

# Install globally via npm
npm install -g appshot-cli

# Or with yarn
yarn global add appshot-cli

# Verify installation
appshot --version

Note: The package is called appshot-cli on NPM, but the command is appshot

Wizard (Recommended)

The wizard is the fastest way to get v2 screenshots, because it:

• Applies a template (optional) for layout + background + caption styling
• Auto-detects orientation from your screenshots and sets resolution
• Generates captions (from filenames or manual entry)
• Localizes + enhances (optional)
• Builds in one pass

# Interactive wizard (templates included)
appshot wizard

# Non-interactive (CI)
appshot wizard --no-interactive --devices iphone,ipad --template ocean-header --caption-source filenames --langs en,es,fr

Tip: If no screenshots exist yet, the wizard keeps resolution unset so build uses the real screenshot dimensions later.

Your First Screenshot - Two Ways

Option 1: Quick Start with Templates (NEW! 🎨)

The fastest way to get professional screenshots:

# One command interactive setup
appshot quickstart

# One-shot v2 flow (layout → captions → build)
appshot wizard

# Or apply a specific template
appshot template ocean-header --caption "Your Amazing App"

# Build your screenshots
appshot build

# ✨ Professional screenshots ready in seconds!

Option 2: Traditional Step-by-Step

Full control over every aspect:

# 1. Initialize your project
appshot init

# 2. Add your screenshots
cp ~/Desktop/screenshots/*.png screenshots/iphone/

# 3. Add captions interactively
appshot caption --device iphone

# 4. Apply a gradient preset
appshot gradients --apply ocean

# 5. Build final screenshots
appshot build

# ✨ Output ready in final/ directory!

Quick Frame-Only Mode

Need just device frames without the full treatment? Use the new frame command:

# Frame a single screenshot
appshot frame screenshot.png

# Batch frame a directory
appshot frame ./screenshots --recursive

# ✨ Framed PNGs with transparent backgrounds ready!

Watch Mode (macOS)

Automatically process screenshots as they're added:

# Start watching for new screenshots
appshot watch start --process --background

# Capture from simulator (auto-processes via watch)
appshot device capture

# Check status
appshot watch status

# Stop watching
appshot watch stop

Example Output Structure

final/
├── iphone/
│   └── en/           # Language subdirectory (always created)
│       ├── home.png       # 1284×2778 with frame, gradient, and caption
│       ├── features.png   
│       └── settings.png
└── ipad/
    └── en/           # Language subdirectory
        └── dashboard.png  # 2048×2732 iPad Pro screenshot

Cleaning & Reset

When you want a clean slate without deleting screenshots:

# Remove outputs + .appshot/ but keep screenshots/
appshot clean --reset --yes

# Remove outputs + .appshot/ + temp files
appshot clean --all --yes

# Clear caption history only
appshot clean --history

--reset is safe for projects: it keeps screenshots/ intact and wipes generated files.

🤖 MCP Server & Agent Integration

Appshot provides a full Model Context Protocol (MCP) server, enabling AI agents like Claude Desktop and Claude Code to manage screenshot workflows directly through tool calls.

Installation

Claude Code (recommended):

# Add the MCP server
claude mcp add appshot-mcp appshot mcp

# Verify it's connected
claude mcp list

Claude Desktop (macOS):

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "appshot": {
      "command": "appshot",
      "args": ["mcp"]
    }
  }
}

Tip: When using Claude Desktop, provide the full configPath parameter to your project directory since the server runs from the home directory.

Available MCP Tools

Tool	Description
appshot_projectInfo	Get project metadata (devices, languages, config)
appshot_init	Initialize new project structure
appshot_quickstart	Quick start setup with templates + captions
appshot_wizard	One-shot v2 flow (template/layout → captions → translate/enhance → build)
appshot_build	Generate final screenshots
appshot_frame	Apply device frames only (transparent background)
appshot_template	Apply v2 template presets
appshot_captions	Read/write caption text, auto-generate from filenames
appshot_gradients	List/apply gradient presets
appshot_backgrounds	Configure background images
appshot_fonts	List/validate available fonts
appshot_config	Modify device-specific settings
appshot_validate	Check App Store compliance
appshot_specs	View App Store specifications
appshot_doctor	Run system diagnostics
appshot_presets	Manage App Store presets
appshot_localize	AI-powered caption translation
appshot_languages	Discover available translations
appshot_export	Export for Fastlane
appshot_clean	Remove generated files

Example: Agent Workflow

Agent: I'll set up your App Store screenshots.

1. appshot_init with force: true
2. appshot_gradients with action: "apply", preset: "ocean"
3. appshot_captions with device: "iphone", action: "set",
   filename: "home.png", caption: "Welcome Home"
4. appshot_build with devices: ["iphone"]
5. appshot_validate

✓ Screenshots ready in final/iphone/en/

Auto-Caption Workflow (generate captions from filenames):

1. appshot_init with force: true
2. appshot_template with template: "ocean-header"
3. appshot_captions with device: "iphone", action: "auto"
4. appshot_build with devices: ["iphone"]

✓ Captions auto-generated: "home-screen.png" → "Home Screen"

Wizard Workflow (single tool call):

appshot_wizard with {
  devices: ["iphone", "ipad"],
  template: "ocean-header",
  captionSource: "filenames",
  languages: ["en", "es", "fr"],
  noInteractive: true
}

Claude Code Skill

For Claude Code users, install the appshot skill for guided workflows:

# Install skill to ~/.claude/skills/appshot/
appshot skill

# Update existing installation
appshot skill --force

# Uninstall
appshot skill --uninstall

The skill provides:

• Project workflow guidance (init → captions → styling → build)
• Template recommendations by app type (dev tools → midnight-header, business → slate-footer)
• Troubleshooting guide for common errors
• Reference files for all 24 gradients, 10 fonts, and 9 templates

Agent-Friendly Features

• Structured Output: All tools return JSON for easy parsing
• No Interactive Prompts: Full automation without user input
• Predictable Commands: Consistent tool interfaces
• Complete Coverage: Every CLI feature available as MCP tool

Claude Desktop Support

Claude Desktop is fully supported as of v2.0.0. Add appshot to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "appshot": {
      "command": "appshot",
      "args": ["mcp"]
    }
  }
}

Restart Claude Desktop after adding the configuration. All MCP tools will be available.

Tip: When using Claude Desktop, always provide the full configPath parameter pointing to your project directory, since Claude Desktop runs from the home directory.

📘 Core Concepts

🧭 Layout v2 - Fixed Zones + Three Layout Modes

• Modes: header, footer, screenshot-only (overlay removed)
• Fixed Regions: Caption/device ratios are deterministic per device type
• Device-Based Font Scaling: Text size scales by output resolution (iPad/Mac larger, Watch smaller)
• Config v2: version: 2 configs only allow styling, not layout proportions
• Docs: See docs/layout-v2.md for full rules

Project Structure

Appshot creates and manages the following directory structure in your project:

your-project/
├── .appshot/
│   ├── config.json          # Main configuration
│   ├── captions/            # Device-specific captions
│   │   ├── iphone.json
│   │   ├── ipad.json
│   │   ├── mac.json
│   │   └── watch.json
│   ├── caption-history.json # Autocomplete history (created on use)
│   ├── ai-config.json       # AI translation settings (optional)
│   ├── processed/           # Watch mode tracking (macOS only)
│   └── watch.pid            # Watch service PID (macOS only)
├── screenshots/             # Your original screenshots
│   ├── iphone/
│   │   └── background.png  # Optional device background
│   ├── ipad/
│   ├── mac/
│   └── watch/
└── final/                   # Generated output
    ├── iphone/
    │   ├── en/              # Language subdirectory (always created)
    │   ├── es/              # Additional languages as needed
    │   └── fr/
    └── ipad/
        └── en/

Created by appshot init:

• .appshot/ directory with config.json
• .appshot/captions/ with device JSON files
• screenshots/ directories for each device type

Created during usage:

• final/ - Created when you run appshot build
• .appshot/caption-history.json - Created when using captions
• .appshot/processed/ - Created by watch mode (macOS)

Configuration Overview

All settings are stored in .appshot/config.json:

{
  "version": 2,
  "layout": "header",
  "caption": {
    "font": "SF Pro Display Bold",
    "color": "#FFFFFF"
  },
  "background": {
    "mode": "gradient",
    "gradient": {
      "colors": ["#0077BE", "#33CCCC"],
      "direction": "diagonal"
    }
  },
  "devices": {
    "iphone": {
      "input": "./screenshots/iphone",
      "resolution": "1290x2796"
    }
  },
  "output": "./final",
  "frames": "./frames"
}

Workflow

1. Capture - Take screenshots from simulator/device or design tool
2. Configure - Set up gradients, fonts, and device settings
3. Caption - Add marketing text with optional AI translation
4. Build - Generate final App Store-ready screenshots
5. Validate - Ensure compliance with App Store requirements

🎨 Visual Customization

Template System (v2)

Appshot v2 templates map to fixed layout modes (header/footer/screenshot-only) plus curated gradients and caption styling defaults. Layout proportions are deterministic per device and not user-adjustable in v2. Overlay mode is removed. See docs/layout-v2.md for the full rules.

Quick Start with Templates

# Interactive template selection
appshot quickstart

# Apply a specific template
appshot template ocean-header

# Apply template with caption
appshot template pastel-header --caption "Beautiful & Simple"

# Preview template settings
appshot template --preview noir-footer

# List all templates
appshot template --list

Available Templates (v2)

Template	Description	Best For
ocean-header	Cool blue gradient + header layout	General purpose
sunset-footer	Warm sunset gradient + footer layout	Bold marketing
clean-screenshot	Minimal background + screenshot-only	Product-focused
pastel-header	Soft pastel gradient + header layout	Clean, friendly apps
noir-footer	Dark dramatic gradient + footer layout	Entertainment, gaming
silver-header	Elegant silver gradient + header layout	Professional apps
tropical-header	Bright tropical gradient + header layout	Playful brands
slate-footer	Professional slate gradient + footer layout	Business, productivity
midnight-header	Deep blue gradient + header layout	Developer tools

📸 Template Gallery (v2): Open template-samples/index.html to browse the current v2 template gallery.

Template Features (v2)

Each template automatically configures:

• Layout Mode: header, footer, or screenshot-only
• Background: Gradient colors and direction
• Caption Style: Font family, color, background, and opacity
• Device Strategies: Fixed ratios, scaling, and line limits per device type

Template Examples

# Ocean Header - General purpose
appshot template ocean-header
# → Header layout + cool blue gradient
# → Fixed zones, centered caption

# Clean Screenshot - Product-forward
appshot template clean-screenshot
# → Screenshot-only layout
# → Minimal background styling

# Noir Footer - Bold marketing
appshot template noir-footer
# → Footer layout + dark gradient
# → High-contrast caption styling

Customizing Templates

Templates provide a starting point that you can further customize:

# 1. Apply a template
appshot template ocean-header

# 2. Adjust styling (layout proportions are fixed in v2)
appshot style                 # Pick layout + gradient + caption color
appshot fonts --set "Poppins Bold"  # Change font
appshot caption --device iphone  # Update captions

# 3. Build with your customizations
appshot build

Creating Consistent Screenshots

Templates ensure consistency across all your screenshots:

// After applying a template, all devices share:
{
  "background": { /* Same gradient/image */ },
  "caption": { /* Same font and styling */ },
  "devices": {
    "iphone": { /* Optimized for iPhone */ },
    "ipad": { /* Optimized for iPad */ },
    "watch": { /* Special watch handling */ }
  }
}

Gradient System

Appshot includes 24+ professional gradient presets organized by category:

Browse & Apply Gradients

# View all gradients with color preview
appshot gradients

# Apply a gradient to your project
appshot gradients --apply sunset

# Interactive selection
appshot gradients select

# Generate preview image
appshot gradients --preview ocean

# Create sample gallery
appshot gradients --sample

Gradient Categories

• 🔥 Warm: sunset, autumn, golden, coral
• ❄️ Cool: ocean, arctic, mint, twilight
• 🎨 Vibrant: neon, tropical, rainbow, vivid
• 🕊️ Subtle: pastel, lavender, peach, sky
• ⚫⚪ Monochrome: noir, silver, charcoal, pearl
• 🏢 Brand: instagram, spotify, twitter, slack

Custom Gradients

{
  "gradient": {
    "colors": ["#FF5733", "#FFC300", "#FF1493"],
    "direction": "diagonal"  // top-bottom, left-right, diagonal
  }
}

Background System

Replace gradients with custom static background images for a unique, branded look. Appshot supports automatic detection, multiple formats, and intelligent scaling.

Background Locations

Backgrounds are searched in priority order:

1. Device-specific: screenshots/<device>/background.png
2. Global: screenshots/background.png
3. Custom: Path specified via config or CLI

Background Commands

# Set background for a device
appshot backgrounds set iphone ./backgrounds/sunset.jpg

# Set global background for all devices
appshot backgrounds set --global ./backgrounds/brand-bg.png

# Validate dimensions against App Store specs
appshot backgrounds validate

# List all configured backgrounds
appshot backgrounds list

# Clear background configuration
appshot backgrounds clear iphone

Build Options

# Auto-detect background.png in device folders
appshot build --auto-background

# Use specific background image
appshot build --background ./assets/custom-bg.png

# Set background fit mode
appshot build --background-fit cover

# Disable backgrounds (transparent)
appshot build --no-background

Fit Modes

• cover - Scale to cover entire area (may crop)
• contain - Scale to fit within area (may add letterbox bars)
• fill - Stretch to exact dimensions (may distort)
• scale-down - Only scale down if larger, never scale up

Creating Backgrounds with ImageMagick

ImageMagick is a powerful CLI tool for creating custom backgrounds:

# Solid color background
magick -size 1290x2796 canvas:navy background.png

# Gradient background
magick -size 1290x2796 gradient:blue-purple background.png

# Radial gradient
magick -size 1290x2796 radial-gradient:white-darkblue background.png

# Plasma fractal pattern
magick -size 1290x2796 plasma:fractal background.png

# Blurred noise texture
magick -size 1290x2796 xc: +noise Random -blur 0x10 background.png

# Tiled pattern
magick -size 100x100 pattern:checkerboard -scale 1290x2796 background.png

# Multi-point color interpolation
magick -size 1290x2796 xc: -sparse-color barycentric \
  '0,0 skyblue 1290,0 white 645,2796 lightblue' background.png

Configuration

{
  "background": {
    "mode": "image",
    "image": "./backgrounds/global.png",
    "fit": "cover"
  },
  "devices": {
    "iphone": {
      "background": {
        "image": "./backgrounds/iphone.png",
        "fit": "contain"
      }
    }
  }
}

Mixed Configurations

You can mix backgrounds and gradients across devices:

• iPhone uses a custom background image
• iPad falls back to gradient
• Mac uses a different background
• Watch uses the global background

This flexibility allows you to optimize each device's appearance independently.

Dimension Validation

Appshot validates background dimensions and warns about:

• Images smaller than target resolution (will be upscaled)
• Aspect ratio mismatches (may cause cropping/distortion)
• Large file sizes (>10MB triggers optimization suggestion)

Use appshot backgrounds validate to check all backgrounds before building.

Font System

Version 0.4.0 introduces comprehensive font management with intelligent fallbacks.

Font Commands

# Browse recommended fonts
appshot fonts

# Set font directly (NEW in v0.4.0)
appshot fonts --set "Montserrat"

# Interactive font selection (NEW in v0.4.0)
appshot fonts --select

# Set device-specific font (NEW in v0.4.0)
appshot fonts --set "SF Pro" --device iphone

# List ALL system fonts
appshot fonts --all

# Validate a font
appshot fonts --validate "SF Pro"

# Get JSON output for automation
appshot fonts --json

Font Setting Methods

You have three ways to set fonts:

1. Direct Command (Fastest):

   appshot fonts --set "Helvetica"
   appshot fonts --set "SF Pro" --device iphone

2. Interactive Selection:

   appshot fonts --select
   appshot style --device iphone  # Also includes font selection

3. Manual Configuration:

   {
     "caption": {
       "font": "Montserrat",     // Global default
       "fontsize": 64
     },
     "devices": {
       "iphone": {
         "captionFont": "SF Pro"  // Device override
       }
     }
   }

Intelligent Fallbacks

Every font automatically includes appropriate fallback chains:

• SF Pro → system-ui, -apple-system, Helvetica, Arial, sans-serif
• Custom Serif → 'Custom Serif', Georgia, Times New Roman, serif
• Code Font → 'Code Font', Monaco, Consolas, monospace

System Font Detection

• macOS: Uses system_profiler for complete font list
• Linux: Uses fc-list for fontconfig fonts
• Windows: PowerShell queries font registry

Frame-Only Mode

New in v0.8.0, the appshot frame command provides a quick way to apply device frames to screenshots without adding gradients or captions. Perfect for design workflows, quick exports, and when you just need a framed device mockup.

Features

• Auto Device Detection - Intelligently detects iPhone, iPad, Mac, or Apple Watch from image dimensions
• Transparent Backgrounds - Outputs PNG with alpha channel preserved
• Batch Processing - Frame entire directories with recursive support
• Smart Frame Selection - Automatically chooses portrait/landscape frames
• No Configuration Required - Works instantly without setup

Basic Usage

# Frame a single screenshot
appshot frame screenshot.png

# Frame all images in a directory
appshot frame ./screenshots

# Recursive directory processing
appshot frame ./screenshots --recursive

# Output to specific directory
appshot frame screenshot.png -o ./framed

# Force device type
appshot frame screenshot.png --device iphone

Options

• -o, --output <dir> - Output directory (default: same as input)
• -d, --device <type> - Force device type (iphone|ipad|mac|watch)
• -r, --recursive - Process directories recursively
• -f, --format <type> - Output format: png (default) or jpeg
• --suffix <text> - Filename suffix (default: "-framed")
• --overwrite - Overwrite original file name
• --dry-run - Preview without processing
• --verbose - Show detailed information

Examples

# Batch frame iPhone screenshots
appshot frame ./iphone-screenshots

# Frame with custom output directory
appshot frame ./screenshots -o ./mockups --recursive

# Preview what would be framed
appshot frame ./screenshots --dry-run

# Force iPad frame for ambiguous dimensions
appshot frame screenshot.png --device ipad

# JPEG output with white background
appshot frame screenshot.png --format jpeg

Device Detection Logic

The frame command uses intelligent heuristics to detect device type:

1. Apple Watch - Small, square-ish images (< 600k pixels, aspect ratio 0.75-1.3)
2. iPad - 4:3 aspect ratio (1.20-1.40) with 1.5M-8M pixels
3. Mac - 16:10 or 16:9 aspect ratio (1.50-1.85) with 2M+ pixels
4. iPhone - Tall aspect ratios (1.60-2.40) with < 5M pixels

When dimensions are ambiguous, use --device to specify the target device.

Device Frames

Appshot auto-detects orientation and selects the best-fitting device frame for each screenshot. Frames are always based on the full device image; the screenshot is inset into the frame’s screenRect.

# Disable frames entirely
appshot build --no-frame

# Frame-only mode (no captions or gradients)
appshot frame ./screenshots

Caption System (v2)

Captions render inside fixed layout zones (header/footer only). Text is centered within the caption region and truncated with ellipsis if it exceeds the max line count for the device. Font size is computed from output dimensions, with device-specific min/max bounds.

{
  "version": 2,
  "layout": "header",
  "caption": {
    "font": "SF Pro Display Bold",
    "color": "#FFFFFF",
    "background": {
      "color": "#000000",
      "opacity": 0.75
    }
  }
}

Tips:

• Use appshot build --dry-run --verbose to inspect computed regions and sizes.
• Use appshot style to pick layout + gradient + caption color.
• Use appshot caption to edit caption text per device.

Template Gallery

Browse the current v2 template gallery in template-samples/index.html.

Caption Autocomplete

The caption command includes intelligent autocomplete:

appshot caption --device iphone
# Features:
# - Fuzzy search
# - Frequency tracking
# - Device-specific suggestions
# - Pattern detection

Keyboard shortcuts:

• Tab - Complete suggestion
• ↑↓ - Navigate suggestions
• Enter - Select
• Esc - Dismiss

🌍 Localization & Translation

AI-Powered Translation

Appshot integrates with OpenAI for instant caption translation.

Setup

export OPENAI_API_KEY="your-api-key-here"

Real-Time Translation

# Translate as you type
appshot caption --device iphone --translate --langs es,fr,de

# Output:
# ? home.png: Welcome to the future
#   es: Bienvenido al futuro
#   fr: Bienvenue dans le futur
#   de: Willkommen in der Zukunft

Batch Translation

# Translate all existing captions
appshot localize --langs es,fr,de,ja,zh-CN

# Device-specific translation
appshot localize --device iphone --langs es,fr

# Use premium model
appshot localize --langs ja,ko --model gpt-5

# Review before saving
appshot localize --langs es --review

Supported Models

Model Series	Best For	Parameter	Temperature
GPT-4o	Fast, cost-effective	max_tokens	0.3
GPT-5	High-quality, nuanced	max_completion_tokens	1.0
o1	Deep reasoning	max_completion_tokens	1.0
o3	State-of-the-art	max_completion_tokens	1.0

Supported Languages

25+ languages including:

• European: es, fr, de, it, pt, nl, sv, no, da, fi, pl, ru
• Asian: ja, ko, zh-CN, zh-TW, hi, th, vi, id, ms
• Middle Eastern: ar, he, tr
• Variants: pt-BR

Multi-Language Workflow

# 1. Add captions with translation
appshot caption --device iphone --translate --langs es,fr

# 2. Build localized screenshots
appshot build --langs en,es,fr

# Output structure (always uses language subdirectories):
# final/
#   iphone/
#     en/
#     es/
#     fr/

📱 Device Support

Apple Devices

Device	Orientations	Frame Variants	Special Features
iPhone	Portrait, Landscape	15+ models	Notch/Dynamic Island support
iPad	Portrait, Landscape	10+ models	Multiple sizes
Mac	Landscape	4 resolutions	16:10 aspect ratio
Apple Watch	Portrait	5 sizes	Band cropping
Apple TV	Landscape	HD, 4K	TV frame
Vision Pro	Landscape	3840×2160	Spatial computing

App Store Specifications

Required Resolutions

iPhone (choose one):

• 6.9" Display: 1290×2796 (iPhone 16/15 Pro Max)
• 6.5" Display: 1284×2778 (iPhone 14 Plus)

iPad:

• 13" Display: 2064×2752 or 2048×2732

Mac:

• 16:10 aspect: 2880×1800, 2560×1600, 1440×900, or 1280×800

Apple Watch:

• Must use same size across all localizations

Preset Management

# View all presets
appshot presets

# Show required only
appshot presets --required

# Generate config for specific presets
appshot presets --generate iphone-6-9,ipad-13

# Build with presets
appshot build --preset iphone-6-9,ipad-13

Validation

# Validate against App Store requirements
appshot validate

# Strict mode (required presets only)
appshot validate --strict

# Get fix suggestions
appshot validate --fix

🚀 Fastlane Integration

Appshot seamlessly integrates with Fastlane for uploading screenshots to App Store Connect. The export command reorganizes your Appshot-generated screenshots into Fastlane's expected directory structure.

Overview

Appshot and Fastlane work together but remain separate tools:

• Appshot: Generates beautiful screenshots with frames, gradients, and captions
• Fastlane: Uploads screenshots to App Store Connect

Quick Start

# 1. Generate screenshots with Appshot
appshot build --preset iphone-6-9,ipad-13

# 2. Export for Fastlane (auto-detects languages)
appshot export

# 3. Upload with Fastlane
cd fastlane && fastlane deliver

Export Command

The appshot export command bridges Appshot and Fastlane:

# Basic export (auto-detects languages, creates symlinks)
appshot export

# Export specific devices only
appshot export --devices iphone,ipad

# Copy files instead of symlinks (for CI/CD)
appshot export --copy --clean

# Generate Fastlane configuration
appshot export --generate-config

# Preview without creating files
appshot export --dry-run

# Custom paths
appshot export --source ./my-screenshots --output ./upload

Language Mapping

Appshot automatically maps language codes to Fastlane format:

• en → en-US
• es → es-ES
• fr → fr-FR
• de → de-DE
• zh → zh-Hans
• pt → pt-PT
• [and 20+ more mappings]

Custom mappings via .appshot/export-config.json:

{
  "languageMappings": {
    "en": "en-GB",
    "custom": "x-special"
  }
}

Directory Structure

Appshot Output (source):

final/
├── iphone/
│   ├── en/
│   │   ├── home.png
│   │   └── features.png
│   └── es/
│       └── home.png
└── ipad/
    └── en/
        └── home.png

Fastlane Structure (after export):

fastlane/screenshots/
├── en-US/
│   ├── iphone/
│   │   ├── home.png
│   │   └── features.png
│   └── ipad/
│       └── IPAD_PRO_3GEN_129_home.png  # Auto-renamed
└── es-ES/
    └── iphone/
        └── home.png

Special Handling

iPad Pro Naming

iPad Pro 12.9" (3rd gen) screenshots are automatically renamed with the IPAD_PRO_3GEN_129_ prefix for proper Fastlane recognition.

Symlinks vs Copying

• Default: Creates symlinks (saves disk space, instant)
• CI/CD: Use --copy for portable archives
• Clean: Use --clean to remove old exports before creating new ones

Screenshot Ordering

📌 Important Discovery: Fastlane uploads screenshots in alphabetical order by filename. Without explicit ordering, your carefully arranged screenshots may appear in the wrong sequence on the App Store!

The Order Problem

When exporting screenshots for Fastlane, the alphabetical ordering can disrupt your intended flow:

• ❌ Without ordering: bluesky.png, cast.png, home.png, media.png, updates.png
• ✅ With ordering: 01_home.png, 02_updates.png, 03_cast.png, 04_media.png, 05_bluesky.png

Managing Screenshot Order

# Set order interactively for each device
appshot order --device iphone
appshot order --device ipad
appshot order --device watch

# Export with numeric prefixes
appshot export --order --copy --clean

# View current order
appshot order --show

The order configuration is saved in .appshot/screenshot-order.json and intelligently handles:

• Files with existing numeric prefixes (prevents double-prefixing like 01_01_home.png)
• Mixed naming conventions in your source files
• New screenshots added after initial ordering

Quick Order Setup

Create a standard order configuration:

cat > .appshot/screenshot-order.json << 'EOF'
{
  "version": "1.0",
  "orders": {
    "iphone": ["home.png", "features.png", "search.png", "profile.png", "settings.png"],
    "ipad": ["home.png", "features.png", "search.png", "profile.png", "settings.png"],
    "watch": ["home.png", "features.png", "profile.png"]
  }
}
EOF

Fastlane Gotchas & Solutions

🔍 Key Discoveries from Real-World Integration

1. Nested Directory Limitations

Problem: Fastlane's deliver command struggles with nested device directories inside language folders.

Solution: Appshot automatically flattens the structure during export:

# Appshot structure (nested):
final/iphone/en/home.png →

# Fastlane structure (flattened):
fastlane/screenshots/en-US/iphone/home.png

2. Device-Specific Prefixes

Discovery: Some devices require specific filename prefixes for Fastlane to recognize them correctly.

Handled Automatically:

• iPad Pro 12.9" (3rd gen) → IPAD_PRO_3GEN_129_ prefix
• iPad Pro 11" → IPAD_PRO_11_ prefix

3. Upload Staging Approach

For complex projects with many screenshots, use the staging approach in your Fastfile:

lane :upload_screenshots_staged do
  # Flattens nested structures for Fastlane compatibility
  # Handles device prefixes automatically
  # See full implementation in Fastlane export --generate-config
end

4. API Key Configuration

Important: Never commit your api_key.json to version control!

# Use the template
cp fastlane/api_key.json.template fastlane/api_key.json
# Edit with your credentials
# Add to .gitignore (done automatically by export --generate-config)

Complete Workflow Example

# 1. Initialize Appshot project
appshot init

# 2. Add your raw screenshots
# Place them in screenshots/iphone/home.png, etc.

# 3. Generate styled screenshots
appshot build --preset iphone-6-9,ipad-13 --langs en,es,fr

# 4. Export for Fastlane with config generation
appshot export --generate-config

# 5. Configure Fastlane (one-time setup)
cd fastlane
# Edit Deliverfile with your App Store Connect credentials
# app_identifier "com.example.myapp"
# username "your@email.com"

# 6. Upload to App Store Connect
fastlane deliver --skip_metadata --skip_app_version_update

# 7. For updates, just rebuild and re-export
appshot build --preset iphone-6-9,ipad-13
appshot export --clean
cd fastlane && fastlane deliver

CI/CD Integration

# GitHub Actions Example
- name: Generate Screenshots
  run: |
    npm install -g appshot-cli
    appshot build --preset iphone-6-9,ipad-13

- name: Export for Fastlane
  run: appshot export --copy --clean

- name: Upload to App Store
  env:
    APP_STORE_CONNECT_API_KEY: ${{ secrets.ASC_API_KEY }}
  run: |
    cd fastlane
    fastlane deliver --api_key_path api_key.json

Validation

The export command includes comprehensive validation:

• Checks for valid output directory permissions
• Validates language codes against Fastlane's supported set
• Warns about missing screenshots for requested devices
• Suggests App Store required presets if missing

# Preview and validate
appshot export --dry-run --verbose

# Check what would be exported
appshot export --dry-run --json | jq

Generated Fastlane Files

With --generate-config, Appshot creates:

• Deliverfile: Screenshot configuration
• Fastfile: Upload lanes
• README.md: Instructions
• .gitignore: Excludes screenshots

Example generated Deliverfile:

# Generated by Appshot
screenshots_path "./screenshots"
languages ["en-US", "es-ES", "fr-FR"]
skip_binary_upload true
skip_metadata true
overwrite_screenshots true

Tips

1. Language Detection: Let Appshot auto-detect languages from your screenshots
2. Device Filtering: Export only what you need with --devices
3. Dry Run First: Always preview with --dry-run before actual export
4. Validation: Run appshot validate before export to ensure compliance
5. Incremental Updates: Use --clean to ensure fresh exports

📝 Command Reference

appshot quickstart (NEW!)

Get started with App Store screenshots in seconds with interactive setup.

appshot quickstart [options]

Options:

• --template <id> - Template to use (default: ocean-header)
• --caption <text> - Main caption for screenshots
• --no-interactive - Skip interactive prompts
• --force - Overwrite existing configuration

What it does:

1. Creates project structure
2. Applies professional template
3. Sets up example captions
4. Shows next steps

Examples:

# Interactive setup
appshot quickstart

# Quick setup with template
appshot quickstart --template pastel-header --caption "My App"

# Non-interactive
appshot quickstart --template noir-footer --no-interactive

appshot wizard (NEW!)

One-shot v2 flow that sets layout, captions, translations, enhancement, and build in a single pass.

appshot wizard [options]

Options:

• --devices <list> - Comma-separated device list (default: iphone)
• --layout <mode> - header | footer | screenshot-only
• --template <id> - Apply a v2 template preset (ocean-header, sunset-footer, clean-screenshot, etc.)
• --caption-source <mode> - filenames | manual
• --langs <codes> - Languages to build (default: en,es,fr)
• --model <name> - OpenAI model (default: gpt-5-mini)
• --enhance / --no-enhance - Toggle caption enhancement (default: on)
• --no-interactive - Skip prompts (CI-friendly)
• --dry-run - Print the planned commands only
• --require-ai - Fail if AI steps are requested but OPENAI_API_KEY is missing

What it does:

1. Ensures v2 config
2. Applies a template (optional) or sets layout
3. Auto-detects screenshot resolution + orientation (when available)
4. Generates captions (auto or manual)
5. Translates (if languages > 1)
6. Enhances captions (optional)
7. Builds screenshots

Examples:

# Interactive wizard
appshot wizard

# Non-interactive with template + translations
appshot wizard --no-interactive --devices iphone,ipad --template ocean-header --caption-source filenames --langs en,es,fr

appshot template (NEW!)

Apply professional screenshot templates for instant visual styling.

appshot template [template] [options]

Arguments:

• [template] - Template ID (ocean-header, sunset-footer, clean-screenshot, pastel-header, noir-footer, silver-header, tropical-header, slate-footer, midnight-header)

Options:

• --list - List all available templates
• --preview <id> - Preview template configuration
• --caption <text> - Add caption to all screenshots
• --device <name> - Apply to specific device only
• --no-backup - Skip config backup
• --dry-run - Preview without applying

Examples:

# List templates
appshot template --list

# Apply template
appshot template ocean-header

# With caption
appshot template pastel-header --caption "Beautiful App"

# Preview settings
appshot template --preview noir-footer

# Device-specific
appshot template silver-header --device iphone

appshot preset (NEW!)

Ultra-simple one-line commands to generate App Store screenshots with professional templates.

appshot preset <preset-name> [options]

Arguments:

• <preset-name> - Template to use (ocean-header, sunset-footer, clean-screenshot, pastel-header, noir-footer, silver-header, tropical-header, slate-footer, midnight-header)

Options:

• -c, --caption <text> - Add caption to all screenshots
• -d, --devices <list> - Comma-separated device list
• -l, --langs <list> - Comma-separated language codes
• -o, --output <path> - Output directory (default: ./final)
• --dry-run - Preview without building
• -v, --verbose - Show detailed output

Examples:

# Quick professional screenshots
appshot preset ocean-header --caption "Amazing Features"

# Multiple devices
appshot preset noir-footer --devices iphone,ipad,watch

# Multiple languages
appshot preset pastel-header --langs en,es,fr,de

# Custom output
appshot preset silver-header --output ./marketing/screenshots

# Preview mode
appshot preset slate-footer --dry-run

# Full example
appshot preset clean-screenshot \
  --caption "Summer Sale!" \
  --devices iphone,ipad \
  --langs en,es,fr \
  --output ./app-store-assets

What it does:

1. Applies professional template (gradient, positioning, styling)
2. Adds caption to first screenshot if provided
3. Builds screenshots for specified devices and languages
4. All in one command - perfect for CI/CD!

appshot build

Generate final screenshots with frames, gradients, and captions.

appshot build [options]

Options:

• --devices <list> - Comma-separated device list (default: all)
• --preset <ids> - Use App Store presets (e.g., iphone-6-9,ipad-13)
• --config <file> - Custom config file (default: .appshot/config.json)
• --langs <list> - Build for specific languages (if not specified, auto-detects)
• --preview - Generate low-res previews
• --concurrency <n> - Parallel processing limit (default: 5)
• --dry-run - Show what would be rendered without generating images
• --verbose - Show detailed rendering information
• --no-frame - Skip device frames
• --no-gradient - Skip gradient backgrounds
• --no-caption - Skip captions
• --auto-caption - Generate captions from filenames when none exist

Language Detection: When --langs is not specified, appshot automatically determines languages in this order:

1. Languages found in caption files (if using multi-language captions)
2. defaultLanguage setting in config.json
3. System locale (e.g., fr for French systems)
4. Fallback to en

Examples:

# Build all devices
appshot build

# Specific devices and languages
appshot build --devices iphone,ipad --langs en,fr,es

# Use App Store presets
appshot build --preset iphone-6-9-portrait,ipad-13-landscape

# Preview mode
appshot build --preview --devices iphone

# Dry-run to see what would be built
appshot build --dry-run

# Verbose mode for debugging
appshot build --verbose --devices iphone

# Auto-generate captions from filenames
appshot build --auto-caption --devices iphone

Exit Codes:

• 0 - Success
• 1 - Configuration error
• 2 - Missing screenshots
• 3 - Processing error

appshot caption

Add or edit captions with autocomplete and AI translation.

appshot caption --device <name> [options]

Options:

• --device <name> - Device name (required)
• --lang <code> - Primary language (default: en)
• --translate - Enable real-time AI translation
• --langs <codes> - Target languages for translation
• --model <name> - OpenAI model (default: gpt-4o-mini)
• --auto-caption - Generate captions from filenames (non-interactive)

If OPENAI_API_KEY is missing, translation is skipped with a warning.

Examples:

# Basic caption entry
appshot caption --device iphone

# With translation
appshot caption --device iphone --translate --langs es,fr,de

# Auto-generate captions and translate (non-interactive)
appshot caption --device iphone --auto-caption --translate --langs es,fr

# Custom model
appshot caption --device ipad --translate --langs ja --model gpt-5

appshot caption enhance

Enhance existing captions using OpenAI without translating languages.

appshot caption enhance --device <name> [options]

Options:

• --device <name> - Device name (required)
• --lang <code> - Primary language (default: en)
• --langs <codes> - Languages to enhance (comma-separated)
• --model <name> - OpenAI model (default: gpt-5-mini)
• --dry-run - Preview changes without writing

Examples:

# Enhance English captions
appshot caption enhance --device iphone

# Enhance only French + Japanese captions
appshot caption enhance --device ipad --langs fr,ja

# Explicit GPT-5 model selection
appshot caption enhance --device mac --model gpt-5-mini

appshot check

Validate project configuration and assets.

appshot check [options]

Options:

• --fix - Attempt automatic fixes

Checks:

• Configuration file validity
• Screenshot presence
• Frame availability
• Directory structure
• Caption files

appshot clean

Remove generated files and temporary data.

appshot clean [options]

Options:

• --all - Remove all generated files including .appshot/
• --reset - Remove generated files but keep screenshots/
• --history - Clear caption autocomplete history
• --keep-history - Preserve history when using --all
• --yes - Skip confirmation prompt

Examples:

# Clean output only
appshot clean

# Full reset
appshot clean --all --yes

# Reset but keep screenshots
appshot clean --reset --yes

# Clear history
appshot clean --history

appshot doctor

Run comprehensive system diagnostics to verify appshot installation and dependencies.

appshot doctor [options]

Options:

• --json - Output results as JSON for CI/automation
• --verbose - Show detailed diagnostic information
• --category <categories> - Run specific checks (comma-separated: system,dependencies,fonts,filesystem,frames)

Checks:

• System Requirements - Node.js version (≥18), npm availability, platform detection
• Dependencies - Sharp module installation, native bindings, image processing test, OpenAI API key
• Font System - Font detection commands, system font loading, common font availability
• File System - Write permissions (current/temp directories), .appshot directory, configuration validity
• Frame Assets - Frame directory presence, Frames.json validation, device frame counts, missing files

Examples:

# Run all diagnostics
appshot doctor

# Check specific categories
appshot doctor --category system,dependencies

# JSON output for CI
appshot doctor --json

# Verbose mode for debugging
appshot doctor --verbose

Output Example:

🏥 Appshot Doctor - System Diagnostics

System Requirements:
  ✓ Node.js v20.5.0 (minimum: v18.0.0)
  ✓ npm v9.8.0
  ✓ darwin (macOS)

Dependencies:
  ✓ Sharp v0.33.5 installed
  ✓ libvips v8.15.3 loaded
  ✓ Sharp image processing test passed
  ⚠ OpenAI API key not found (translation features disabled)

Summary: 20 passed, 1 warning, 0 errors

Suggestions:
  • Set OPENAI_API_KEY environment variable to enable translation features

appshot fonts

Browse, validate, and set fonts for captions. Includes 8 high-quality embedded fonts for consistent rendering across all platforms.

appshot fonts [options]

Options:

• --all - List all system fonts
• --embedded - Show embedded fonts bundled with appshot
• --recommended - Show recommended fonts only (default)
• --validate <name> - Check if font is available (embedded or system)
• --set <name> - Set the caption font
• --select - Interactive font selection
• --device <name> - Target specific device (with --set or --select)
• --json - Output as JSON

Embedded Fonts (Always Available):

• Modern UI: Inter, Poppins, Montserrat, DM Sans
• Popular Web: Roboto, Open Sans, Lato, Work Sans
• Monospace: JetBrains Mono, Fira Code
• Variants: Regular, Italic, Bold, and Bold Italic styles

All embedded fonts use open source licenses (OFL or Apache 2.0) and provide consistent rendering without requiring system installation. Font variants are automatically detected and properly rendered with correct styles.

Examples:

# Browse recommended fonts
appshot fonts

# Show embedded fonts
appshot fonts --embedded

# Set global font directly (embedded font)
appshot fonts --set "Inter"

# Set font variant (italic style)
appshot fonts --set "Poppins Italic"

# Set bold variant
appshot fonts --set "Montserrat Bold"

# Interactive font selection
appshot fonts --select

# Set device-specific font variant
appshot fonts --set "Poppins Bold Italic" --device iphone

# Validate font availability
appshot fonts --validate "Inter"  # Shows: embedded
appshot fonts --validate "Arial"  # Shows: system installed

# List all system fonts
appshot fonts --all

# JSON output for automation
appshot fonts --json > fonts.json

appshot frame

Apply device frames to screenshots with transparent backgrounds (no gradients or captions).

appshot frame <input> [options]

Arguments:

• <input> - Input image file or directory

Options:

• -o, --output <dir> - Output directory (default: same as input)
• -d, --device <type> - Force device type (iphone|ipad|mac|watch)
• -r, --recursive - Process directories recursively
• -f, --format <type> - Output format: png or jpeg (default: png)
• --suffix <text> - Filename suffix when not overwriting (default: "-framed")
• --overwrite - Overwrite original file name
• --dry-run - Preview files without processing
• --frame-tone <tone> - Frame color treatment (original | neutral)
• --verbose - Show detailed information

Features:

• Auto-detects device type from image dimensions
• Preserves transparency with PNG output
• Batch processes entire directories
• Smart portrait/landscape frame selection
• Progress indicators for large batches

Examples:

# Frame single file (auto-detect device)
appshot frame screenshot.png

# Specify output directory
appshot frame screenshot.png -o framed/

# Force device type
appshot frame screenshot.png --device iphone

# Batch process directory
appshot frame ./screenshots -o ./framed --recursive

# Dry run with verbose logs
appshot frame ./screenshots --dry-run --verbose

# JPEG output (white background)
appshot frame screenshot.png --format jpeg

# Generate neutral (desaturated) device frames
appshot frame screenshot.png --frame-tone neutral

appshot mcp

Start the Model Context Protocol (MCP) server for AI agent integration. Enables Claude Desktop, Claude Code, and other MCP-compatible agents to control appshot directly.

appshot mcp [options]

Options:

• --stdio - Use stdio transport (default)

Usage: Register in Claude Desktop's config to enable AI-powered screenshot workflows. See MCP Server & Agent Integration for setup details.

appshot mcp

Tools exposed:

• appshot_projectInfo – Returns appshot_json metadata (devices, languages, templates).
• appshot_doctor – Runs diagnostics and returns console output.
• appshot_build – Wraps appshot build with options for devices, languages, and rendering flags.
• appshot_frame – Batch frames screenshots (including --frame-tone neutral support).
• appshot_export – Runs the Fastlane export pipeline.

The server uses the stdio transport, so you can register it in Anthropic Desktop by pointing at appshot mcp (working directory = your Appshot project). The same entry point works for any MCP-compatible agent or automation.

appshot skill

Install the appshot skill for Claude Code. The skill provides workflow guidance, template recommendations, and troubleshooting help.

appshot skill [options]

Options:

• --force - Overwrite existing installation
• --uninstall - Remove the skill
• --path <dir> - Custom installation path

Examples:

# Install skill to ~/.claude/skills/appshot/
appshot skill

# Update existing installation
appshot skill --force

# Uninstall
appshot skill --uninstall

Skill contents:

• SKILL.md - Main documentation with workflows and scenarios
• references/templates.md - v2 template guidance and recommendations by app type
• references/gradients.md - All 24 gradient presets with colors
• references/fonts.md - All 10 embedded font families
• references/troubleshooting.md - Common errors and solutions

appshot device (macOS only)

Capture screenshots from iOS simulators.

appshot device <command> [options]

Commands:

• capture - Capture screenshot from device
• list - List available devices
• prepare - Boot simulators

Capture Options:

• -d, --device <name> - Device name or alias
• --all - Capture from all devices
• --simulators - Filter simulators
• --booted - Currently booted simulators
• --process - Auto-process with frames
• --app <bundleId> - Launch app before capture

Examples:

# List devices
appshot device list

# Interactive capture
appshot device capture

# Capture from specific device
appshot device capture --device "iPhone 15 Pro"

# Capture and process
appshot device capture --process

appshot watch (macOS only)

Monitor directories for new screenshots with automatic processing.

appshot watch <command> [options]

Commands:

• start - Start watching directories
• stop - Stop the watch service
• status - Check service status
• setup - Interactive configuration

Start Options:

• -d, --dirs <paths...> - Directories to watch
• --devices <names...> - Device names for processing
• --process - Auto-process with frames
• --frame-only - Frames only (no gradient/caption)
• --background - Run in background
• --verbose - Detailed output

Examples:

# Interactive setup
appshot watch setup

# Start in background with processing
appshot watch start --process --background

# Watch multiple directories
appshot watch start --dirs ./screenshots ./downloads

# Check status
appshot watch status --verbose

# Stop watching
appshot watch stop

appshot gradients

Manage gradient presets.

appshot gradients [options]
appshot gradients select

Options:

• --list - List all presets (default)
• --category <name> - Filter by category
• --preview <id> - Generate preview image
• --sample - Generate all samples with HTML
• --apply <id> - Apply preset to project

Examples:

# Browse all
appshot gradients

# Apply preset
appshot gradients --apply ocean

# Interactive selection
appshot gradients select

# Generate samples
appshot gradients --sample

appshot init

Initialize new project with scaffolding.

appshot init [options]

Options:

• --force - Overwrite existing files

Creates:

• .appshot/config.json
• .appshot/captions/
• screenshots/ directories
• Default configuration

appshot localize

Batch translate all captions using AI.

appshot localize --langs <codes> [options]

Options:

• --langs <codes> - Target languages (required)
• --device <name> - Specific device only
• --model <name> - OpenAI model (default: gpt-4o-mini)
• --source <lang> - Source language (default: en)
• --review - Review before saving
• --overwrite - Replace existing translations

Examples:

# Translate all
appshot localize --langs es,fr,de

# Device-specific
appshot localize --device iphone --langs ja,ko

# Premium model with review
appshot localize --langs zh-CN --model gpt-5 --review

appshot presets

Manage App Store screenshot presets.

appshot presets [options]

Options:

• --list - List all presets (default)
• --required - Show required only
• --generate <ids> - Generate config for presets
• --category <type> - Filter by device type
• --output <file> - Output file for config

Examples:

# View all
appshot presets

# Required only
appshot presets --required

# Generate config
appshot presets --generate iphone-6-9,ipad-13

appshot specs

Display complete Apple App Store screenshot specifications.

appshot specs [options]

Options:

• --device <name> - Filter by device type (iphone|ipad|mac|watch|appletv|visionpro)
• --json - Output as JSON (exact Apple specifications for diffing)
• --required - Show only required presets

Shows:

• Complete Apple specifications with exact resolutions
• Display sizes and device compatibility lists
• Required vs optional indicators
• Fallback notes and requirements

JSON Output for Change Tracking: The --json flag outputs the complete Apple App Store specifications data, perfect for tracking changes over time:

# Save current specifications
appshot specs --json > apple-specs-2024-08.json

# After Apple updates (typically September)
appshot specs --json > apple-specs-2024-09.json

# See what changed
diff apple-specs-2024-08.json apple-specs-2024-09.json

Data Source: The specifications mirror Apple's official screenshot requirements and are maintained in sync with Apple's updates. The JSON output preserves all metadata including:

• Exact resolutions (e.g., 1290x2796 for iPhone 6.9")
• Device groupings (which devices share requirements)
• Requirement status (mandatory vs optional)
• Fallback rules and special notes

This is particularly useful for:

• Tracking when Apple adds new device requirements
• Validating screenshot compliance before submission
• Automating screenshot generation pipelines
• Planning resource allocation for new devices

appshot validate

Validate screenshots against App Store requirements.

appshot validate [options]

Options:

• --strict - Validate required presets only
• --fix - Show fix suggestions

Validates:

• Resolution compliance
• Aspect ratios
• Required presets
• File formats

⚙️ Configuration Reference

{
  "version": 2,
  "layout": "header",             // header | footer | screenshot-only
  "caption": {
    "font": "SF Pro Display Bold",
    "color": "#FFFFFF"
  },
  "background": {
    "mode": "gradient",
    "gradient": {
      "colors": ["#667eea", "#764ba2"],
      "direction": "top-bottom"
    }
  },
  "devices": {
    "iphone": "./screenshots/iphone",
    "ipad": "./screenshots/ipad",
    "mac": "./screenshots/mac",
    "watch": "./screenshots/watch"
  },
  "output": "./final",
  "frames": "./frames"
}

v2 uses fixed layout zones and per-device strategies. See docs/layout-v2.md.

🤖 Agent & Automation Guide

Design Principles

Appshot is built for automation:

1. Predictable - Consistent commands and outputs
2. Scriptable - JSON configs, exit codes, no GUI
3. Composable - Unix philosophy, pipe-friendly
4. Fast - Parallel processing, no overhead

JSON Output Mode

Most commands support JSON output for parsing:

# Device specs as JSON
appshot specs --json

# Font list as JSON
appshot fonts --json

# Preset data as JSON
appshot presets --json

# Validation results as JSON
appshot validate --json

Exit Codes

Code	Meaning	Commands
0	Success	All
1	Configuration error	build, check
2	Missing files	build, validate
3	Processing error	build
4	Invalid input	All
5	API error	localize, caption

Batch Operations

# Process multiple devices
appshot build --devices iphone,ipad,mac

# Multiple languages
appshot build --langs en,es,fr,de,ja

# Parallel processing
appshot build --concurrency 10

CI/CD Integration

GitHub Actions

name: Generate Screenshots
on: [push]

jobs:
  screenshots:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Setup Node
        uses: actions/setup-node@v2
        with:
          node-version: '18'
      
      - name: Install Appshot
        run: npm install -g appshot-cli
      
      - name: Generate Screenshots
        run: |
          appshot init --force
          appshot gradients --apply ocean
          appshot build --preset iphone-6-9,ipad-13
      
      - name: Upload Artifacts
        uses: actions/upload-artifact@v2
        with:
          name: screenshots
          path: final/

Shell Script Automation

#!/bin/bash
set -e

# Configure
cat > .appshot/config.json << EOF
{
  "gradient": {"colors": ["#FF5733", "#FFC300"]},
  "devices": {
    "iphone": {"resolution": "1290x2796"}
  }
}
EOF

# Add captions programmatically
echo '{"home.png": "Welcome"}' > .appshot/captions/iphone.json

# Build
appshot build --devices iphone

# Validate
appshot validate --strict || exit 1

MCP Integration

Works with Model Context Protocol tools:

# MCP captures screenshot
mcp-screenshot capture --output ./screenshots/iphone/home.png

# Appshot processes
appshot build --devices iphone --no-interactive

Python Automation

import subprocess
import json

def generate_screenshots(device, captions):
    # Configure
    config = {
        "gradient": {"colors": ["#0077BE", "#33CCCC"]},
        "devices": {
            device: {"resolution": "1290x2796"}
        }
    }
    
    with open('.appshot/config.json', 'w') as f:
        json.dump(config, f)
    
    # Add captions
    with open(f'.appshot/captions/{device}.json', 'w') as f:
        json.dump(captions, f)
    
    # Build
    result = subprocess.run(
        ['appshot', 'build', '--devices', device],
        capture_output=True,
        text=True
    )
    
    return result.returncode == 0

# Usage
captions = {
    "home.png": "Your Dashboard",
    "settings.png": "Customize Everything"
}
generate_screenshots("iphone", captions)

Node.js Automation

import { exec } from 'child_process';
import { writeFileSync } from 'fs';

async function generateScreenshots() {
  // 1. Initialize
  await execPromise('appshot init --force');
  
  // 2. Configure
  const config = {
    gradient: { colors: ['#FF5733', '#FFC300'] },
    caption: { font: 'SF Pro', fontsize: 64 }
  };
  writeFileSync('.appshot/config.json', JSON.stringify(config));
  
  // 3. Add captions
  const captions = {
    'home.png': {
      en: 'Welcome',
      es: 'Bienvenido',
      fr: 'Bienvenue'
    }
  };
  writeFileSync('.appshot/captions/iphone.json', JSON.stringify(captions));
  
  // 4. Build with multiple languages
  await execPromise('appshot build --langs en,es,fr');
}

function execPromise(cmd) {
  return new Promise((resolve, reject) => {
    exec(cmd, (error, stdout) => {
      if (error) reject(error);
      else resolve(stdout);
    });
  });
}

🎯 Recipes & Examples

App Store Submission Workflow

# 1. Initialize project
appshot init

# 2. Configure for App Store
appshot presets --generate iphone-6-9,ipad-13 > .appshot/config.json

# 3. Add screenshots
cp simulator/*.png screenshots/iphone/

# 4. Add captions with translation
export OPENAI_API_KEY="sk-..."
appshot caption --device iphone --translate --langs es,fr,de,ja,zh-CN

# 5. Apply premium gradient
appshot gradients --apply twilight

# 6. Configure styling
appshot style --device iphone

# 7. Build all localizations
appshot build --preset iphone-6-9,ipad-13 --langs en,es,fr,de,ja,zh-CN

# 8. Validate
appshot validate --strict

# 9. Output ready in final/

Consistent Marketing Screenshots

For identical device positioning across all screenshots (v2 uses fixed zones):

{
  "version": 2,
  "layout": "header",
  "caption": {
    "font": "SF Pro Display Bold",
    "color": "#FFFFFF"
  },
  "background": {
    "mode": "gradient",
    "gradient": {
      "colors": ["#111111", "#333333"],
      "direction": "top-bottom"
    }
  },
  "devices": {
    "iphone": "./screenshots/iphone"
  }
}

Brand Guidelines Compliance

{
  "version": 2,
  "layout": "header",
  "background": {
    "mode": "gradient",
    "gradient": {
      "colors": ["#BrandColor1", "#BrandColor2"],
      "direction": "diagonal"
    }
  },
  "caption": {
    "font": "Brand Font Name",
    "color": "#BrandTextColor"
  }
}

Multi-Device Campaign

# Configure each device
appshot style --device iphone
appshot style --device ipad
appshot style --device mac

# Build all at once
appshot build --devices iphone,ipad,mac --langs en,es,fr

# Output structure (language subdirectories):
# final/
#   iphone/
#     en/ es/ fr/
#   ipad/
#     en/ es/ fr/
#   mac/
#     en/ es/ fr/

A/B Testing Different Styles

# Version A - Ocean gradient
appshot gradients --apply ocean
appshot build --devices iphone --output final-ocean

# Version B - Sunset gradient
appshot gradients --apply sunset
appshot build --devices iphone --output final-sunset

# Version C - Monochrome
appshot gradients --apply noir
appshot build --devices iphone --output final-noir

🔧 Troubleshooting

Common Issues

Screenshots Not Found

# Check path configuration
appshot check

# Verify screenshot location
ls screenshots/iphone/

# Fix: Update config
{
  "devices": {
    "iphone": {
      "input": "./correct/path/to/screenshots"
    }
  }
}

Font Not Rendering

# 1. Validate font availability
appshot fonts --validate "Font Name"

# 2. Use fallback font
appshot fonts --recommended

# 3. Set web-safe font
{
  "caption": {
    "font": "Arial"  // Always works
  }
}

Translation Not Working

# Check API key
echo $OPENAI_API_KEY

# Test with different model
appshot caption --device iphone --translate --model gpt-4o-mini

# Check rate limits
# Wait 60 seconds between large batches

Blurry Output

# Ensure high-res input
# Minimum: 1242x2208 for iPhone

# v2 uses fixed layout zones and deterministic device scaling.
# If output is blurry, use higher-res inputs or match the exact device resolution.
# You can also try --no-frame to remove any frame scaling.

Memory Issues with Large Batches

# Reduce concurrency
appshot build --concurrency 2

# Process in batches
appshot build --devices iphone
appshot build --devices ipad

Debugging with Verbose Mode

Use --verbose flag to diagnose rendering issues:

# See detailed caption metrics
appshot build --verbose --devices iphone

# Output includes:
# - Caption wrap width and line count
# - Font stack with fallbacks
# - Device frame scaling factors
# - Position calculations

Use --dry-run to validate configuration without processing:

# Check what would be generated
appshot build --dry-run

# Verify frame selection
appshot build --dry-run --devices iphone

# Check multi-language output
appshot build --dry-run --langs en,es,fr

Performance Tips

1. Use appropriate concurrency

   # For 8GB RAM
   appshot build --concurrency 3
   
   # For 16GB+ RAM
   appshot build --concurrency 8

2. Optimize images before processing

   # Use imagemagick to optimize
   mogrify -quality 95 screenshots/iphone/*.png

3. Cache translations

   • Translations are automatically cached
   • Reuse improves speed and reduces costs

4. Use preview mode for testing

   appshot build --preview

Error Messages

Error	Cause	Solution
Frame not found	Missing frame file	Run appshot check --fix
Invalid resolution	Wrong dimensions	Check with appshot validate
Font validation failed	Font not available	Use appshot fonts to find alternatives
API rate limit	Too many requests	Add delays or reduce batch size
Out of memory	Large images	Reduce concurrency or image size

🧑‍💻 Development

Building from Source

# Clone repository
git clone https://github.com/chrisvanbuskirk/appshot.git
cd appshot

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests
npm test

# Link for local development
npm link

# Run in development mode
npm run dev -- build --devices iphone

Project Structure

appshot/
├── src/
│   ├── cli.ts              # Entry point
│   ├── commands/           # Command implementations
│   ├── core/               # Core functionality
│   ├── services/           # Services (fonts, translation, etc)
│   ├── types/              # TypeScript type definitions
│   ├── utils/              # Utility functions
│   └── types.ts            # Main type definitions
├── tests/                  # Test files
│   ├── integration/        # Integration tests
│   └── visual/             # Visual regression tests
├── fonts/                  # Embedded font files
│   ├── Inter/
│   ├── Poppins/
│   ├── Montserrat/
│   └── ...                 # 10+ font families
├── frames/                 # Device frame images
├── assets/                 # Static assets
│   ├── specs/              # App Store specifications
│   └── frames/             # Frame metadata
└── examples/               # Example projects
    └── minimal-project/    # Basic example setup

Testing

Appshot includes comprehensive test coverage with unit tests, integration tests, and CI/CD validation.

Test Suites

• Unit Tests (50+ test files)

  • Device detection and frame selection
  • Gradient rendering and presets
  • Font validation and fallbacks
  • Caption positioning and text wrapping
  • Multi-language support
  • App Store specifications validation

• Integration Tests (tests/integration/)

  • Full CLI command testing
  • End-to-end workflow validation
  • Multi-platform compatibility
  • Error handling scenarios

• CI/CD Testing

  • Automated testing on every PR
  • Multi-OS testing (Ubuntu, macOS, Windows)
  • Multi-Node version testing (18.x, 20.x, 22.x)
  • Visual validation workflows
  • Screenshot artifact generation

# Run all tests
npm test

# Run specific test
npm test -- fonts.test.ts

# Run integration tests
npm test -- tests/integration/cli-integration.test.ts

# Watch mode
npm run test:watch

# Run with coverage
npm run test:coverage

Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Ensure all tests pass
5. Submit a pull request

See CONTRIBUTING.md for details.

🗺️ Roadmap

Completed ✅

• Official App Store specifications
• Layout v2 fixed zones (header/footer/screenshot-only)
• Intelligent caption autocomplete
• Apple Watch optimizations
• Gradient presets system (24+ gradients)
• AI-Powered Translations (GPT-4o, GPT-5, o1, o3)
• Comprehensive Font System (v0.4.0)
• Frame-Only Mode (v0.8.0)
• MCP Server with 17 tools (v2.0.0)
• Claude Code Skill (v2.0.0)
• Fastlane Export Integration
• Professional Template System (v2)
• Auto-Caption from Filenames

In Progress 🚧

• Claude Desktop MCP compatibility ✅ (v2.0.0)
• Android Device Support (Google Play Store)

Planned 📋

• GitHub Actions Marketplace Action
• CI/CD Templates (Jenkins, GitLab CI, CircleCI)
• AI-Powered Caption Enhancement (OpenAI)
• WebP/AVIF Support
• Screenshot A/B Testing Framework
• Differential Builds

📄 License & Support

License

MIT © Chris Van Buskirk

Support

• 🐛 Report Issues
• 💡 Request Features
• 📚 Documentation Wiki
• 💬 Discussions

Security

For security vulnerabilities, please see SECURITY.md.

NPM Package

• 📦 appshot-cli on NPM
• 🔄 Latest version: 2.0.0

---

Built with ❤️ for developers and AI agents who automate everything.