Appshot 📸

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

🌐 https://appshot.sh

![CI](https://github.com/chrisvanbuskirk/appshot/actions/workflows/ci.yml)
![npm version](https://www.npmjs.com/package/appshot-cli)
![npm downloads](https://www.npmjs.com/package/appshot-cli)
![Node.js Version](https://nodejs.org)
![License: MIT](https://opensource.org/licenses/MIT)

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

$3

- 🤖 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 |
| --- | --- | --- |
| !Ocean Header | !Sunset Footer | !Clean Screenshot |
| Pastel Header | Noir Footer | Silver Header |
| !Pastel Header | !Noir Footer | !Silver Header |
| Slate Footer | Midnight Header | Tropical 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

$3

- 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

$3

``bash

`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

`$3`

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 setsresolution- Generates captions (from filenames or manual entry) - Localizes + enhances (optional) - Builds in one pass

`bash

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

`$3`

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

The fastest way to get professional screenshots:

`bash

`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:

`bash

`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!


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

`bash

`Frame a single screenshot`


appshot frame screenshot.png
Batch frame a directory

appshot frame ./screenshots --recursive
✨ Framed PNGs with transparent backgrounds ready!


$3
Automatically process screenshots as they're added:

`bash

`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

$3

`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`

`$3`

When you want a clean slate without deleting screenshots:

`bash

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

`$3`

Claude Code (recommended):`bash

`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:`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.

`$3`

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

`$3`

`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 }`

`$3`

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

`bash

`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
$3
- 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
$3
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

`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: 2configs only allow styling, not layout proportions - Docs: Seedocs/layout-v2.md for full rules

`$3`

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)

`$3`

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

`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" }`

`$3`

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`

`$3`

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

`bash

`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

`bash

`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:

`bash

`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:

`json // 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 / } } }`

`$3`

Appshot includes 24+ professional gradient presets organized by category:

#### Browse & Apply Gradients

`bash

`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

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

`$3`

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//background.png2. Global:screenshots/background.png3. Custom: Path specified via config or CLI

#### Background Commands

`bash

`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

`bash

`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:

`bash

`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

`json { "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.

`$3`

Version 0.4.0 introduces comprehensive font management with intelligent fallbacks.

#### Font Commands

`bash

`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):`bash appshot fonts --set "Helvetica" appshot fonts --set "SF Pro" --device iphone`

2. Interactive Selection:`bash appshot fonts --select appshot style --device iphone # Also includes font selection`

3. Manual Configuration:`json { "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_profilerfor complete font list - Linux: Usesfc-listfor fontconfig fonts - Windows: PowerShell queries font registry

`$3`

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

`bash

`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

 - Output directory (default: same as input)
-

-d, --device

 - Force device type (iphone|ipad|mac|watch)
-

-r, --recursive

 - Process directories recursively
-

-f, --format

 - Output format: png (default) or jpeg
-

--suffix

 - Filename suffix (default: "-framed")
-

--overwrite

 - Overwrite original file name
-

--dry-run

 - Preview without processing
-

--verbose

 - Show detailed information
#### Examples

`bash

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

`$3`

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.

`bash

`Disable frames entirely`


appshot build --no-frame
Frame-only mode (no captions or gradients)

appshot frame ./screenshots


$3
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.

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

Tips: - Useappshot build --dry-run --verboseto inspect computed regions and sizes. - Useappshot styleto pick layout + gradient + caption color. - Useappshot caption to edit caption text per device.

`$3`

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

#### Caption Autocomplete

The caption command includes intelligent autocomplete:

`bash 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
$3
Appshot integrates with OpenAI for instant caption translation.
#### Setup

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

#### Real-Time Translation

`bash

`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

`bash

`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

$3

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

`$3`

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

`$3`

`bash

`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
$3
| 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 |
$3
#### 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

`bash

`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

$3

`bash

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

`$3`

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

`$3`

`bash

`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

$3

The appshot export command bridges Appshot and Fastlane:

`bash

`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

$3

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:`json { "languageMappings": { "en": "en-GB", "custom": "x-special" } }`

`$3`

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`

`$3`

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

#### Symlinks vs Copying - Default: Creates symlinks (saves disk space, instant) - CI/CD: Use--copyfor portable archives - Clean: Use--clean to remove old exports before creating new ones

`$3`

> 📌 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

`bash

`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.jsonand intelligently handles: - Files with existing numeric prefixes (prevents double-prefixing like01_01_home.png) - Mixed naming conventions in your source files - New screenshots added after initial ordering

#### Quick Order Setup

Create a standard order configuration:`bash 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`

`$3`

> 🔍 Key Discoveries from Real-World Integration

#### 1. Nested Directory Limitations Problem: Fastlane'sdeliver command struggles with nested device directories inside language folders.

Solution: Appshot automatically flattens the structure during export:`bash

`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:

`ruby 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 yourapi_key.json to version control!

`bash

`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)

$3

`bash

`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

$3

`yaml

`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`

`$3`

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

`bash

`Preview and validate`


appshot export --dry-run --verbose
Check what would be exported

appshot export --dry-run --json | jq

$3

With --generate-config, Appshot creates: - Deliverfile: Screenshot configuration - Fastfile: Upload lanes - README.md: Instructions - .gitignore: Excludes screenshots

Example generated Deliverfile:`ruby

`Generated by Appshot`


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

$3

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

`📝 Command Reference`

`$3`

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

`bash appshot quickstart [options]`

Options: ---template - Template to use (default: ocean-header) ---caption - 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:`bash

`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


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

`bash appshot wizard [options]`

Options: ---devices - Comma-separated device list (default: iphone) ---layout - header | footer | screenshot-only ---template - Apply a v2 template preset (ocean-header, sunset-footer, clean-screenshot, etc.) ---caption-source - filenames | manual ---langs - Languages to build (default: en,es,fr) ---model - 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:`bash

`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


$3
Apply professional screenshot templates for instant visual styling.

`bash 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 - Preview template configuration ---caption - Add caption to all screenshots ---device - Apply to specific device only ---no-backup- Skip config backup ---dry-run - Preview without applying

Examples:`bash

`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


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

`bash appshot preset [options]`

Arguments: - - Template to use (ocean-header, sunset-footer, clean-screenshot, pastel-header, noir-footer, silver-header, tropical-header, slate-footer, midnight-header)

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

Examples:`bash

`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!
$3
Generate final screenshots with frames, gradients, and captions.

`bash appshot build [options]`

Options: ---devices - Comma-separated device list (default: all) ---preset - Use App Store presets (e.g., iphone-6-9,ipad-13) ---config - Custom config file (default: .appshot/config.json) ---langs - Build for specific languages (if not specified, auto-detects) ---preview- Generate low-res previews ---concurrency - 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--langsis not specified, appshot automatically determines languages in this order: 1. Languages found in caption files (if using multi-language captions) 2.defaultLanguagesetting in config.json 3. System locale (e.g.,frfor French systems) 4. Fallback toen

Examples:`bash

`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

`$3`

Add or edit captions with autocomplete and AI translation.

`bash appshot caption --device [options]`

Options: ---device - Device name (required) ---lang - Primary language (default: en) - --translate - Enable real-time AI translation - --langs - Target languages for translation - --model - 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: `bash

`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
`
$3
Enhance existing captions using OpenAI without translating languages.`bash
appshot caption enhance --device  [options]
`
Options:
- --device  - Device name (required)
- --lang  - Primary language (default: en)
- --langs  - Languages to enhance (comma-separated)
- --model  - OpenAI model (default: gpt-5-mini)
- --dry-run - Preview changes without writing
Examples:
`bash
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
`
$3
Validate project configuration and assets.`bash
appshot check [options]
`
Options:
- --fix - Attempt automatic fixes
Checks:
- Configuration file validity
- Screenshot presence
- Frame availability
- Directory structure
- Caption files
$3
Remove generated files and temporary data.
`bash
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:
`bash
Clean output only

appshot clean
Full reset

appshot clean --all --yes
Reset but keep screenshots

appshot clean --reset --yes
Clear history

appshot clean --history
`
$3
Run comprehensive system diagnostics to verify appshot installation and dependencies.`bash
appshot doctor [options]
`
Options:
- --json - Output results as JSON for CI/automation
- --verbose - Show detailed diagnostic information
- --category  - 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:
`bash
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
`
$3
Browse, validate, and set fonts for captions. Includes 8 high-quality embedded fonts for consistent rendering across all platforms.
`bash
appshot fonts [options]
`
Options:
- --all - List all system fonts
- --embedded - Show embedded fonts bundled with appshot
- --recommended - Show recommended fonts only (default)
- --validate  - Check if font is available (embedded or system)
- --set  - Set the caption font
- --select - Interactive font selection
- --device  - 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:
`bash
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
`
$3
Apply device frames to screenshots with transparent backgrounds (no gradients or captions).`bash
appshot frame  [options]
`
Arguments:
-  - Input image file or directory
Options:
- -o, --output 
 - Output directory (default: same as input)
- -d, --device  - Force device type (iphone|ipad|mac|watch)
- -r, --recursive - Process directories recursively
- -f, --format  - Output format: png or jpeg (default: png)
- --suffix  - Filename suffix when not overwriting (default: "-framed")
- --overwrite - Overwrite original file name
- --dry-run - Preview files without processing
- --frame-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 batchesExamples:
`bash
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
`
$3
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.`bash
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.
`bash
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.
$3
Install the appshot skill for Claude Code. The skill provides workflow guidance, template recommendations, and troubleshooting help.
`bash
appshot skill [options]
`
Options:
- --force - Overwrite existing installation
- --uninstall - Remove the skill
- --path 
 - Custom installation pathExamples:
`bash
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
$3
Capture screenshots from iOS simulators.
`bash
appshot device  [options]
`
Commands:
- capture - Capture screenshot from device
- list - List available devices
- prepare - Boot simulators
Capture Options:
- -d, --device  - Device name or alias
- --all - Capture from all devices
- --simulators - Filter simulators
- --booted - Currently booted simulators
- --process - Auto-process with frames
- --app  - Launch app before capture
Examples:
`bash
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
`
$3
Monitor directories for new screenshots with automatic processing.`bash
appshot watch  [options]
`
Commands:
- start - Start watching directories
- stop - Stop the watch service
- status - Check service status
- setup - Interactive configuration
Start Options:
- -d, --dirs  - Directories to watch
- --devices  - Device names for processing
- --process - Auto-process with frames
- --frame-only - Frames only (no gradient/caption)
- --background - Run in background
- --verbose - Detailed output
Examples:
`bash
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
`
$3
Manage gradient presets.`bash
appshot gradients [options]
appshot gradients select
`
Options:
- --list - List all presets (default)
- --category  - Filter by category
- --preview  - Generate preview image
- --sample - Generate all samples with HTML
- --apply  - Apply preset to project
Examples:
`bash
Browse all

appshot gradients
Apply preset

appshot gradients --apply ocean
Interactive selection

appshot gradients select
Generate samples

appshot gradients --sample
`
$3
Initialize new project with scaffolding.`bash
appshot init [options]
`
Options:
- --force - Overwrite existing files
Creates:
- .appshot/config.json
- .appshot/captions/
- screenshots/ directories
- Default configuration
$3
Batch translate all captions using AI.
`bash
appshot localize --langs  [options]
`
Options:
- --langs  - Target languages (required)
- --device  - Specific device only
- --model  - OpenAI model (default: gpt-4o-mini)
- --source  - Source language (default: en)
- --review - Review before saving
- --overwrite - Replace existing translations
Examples:
`bash
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
`
$3
Manage App Store screenshot presets.`bash
appshot presets [options]
`
Options:
- --list - List all presets (default)
- --required - Show required only
- --generate  - Generate config for presets
- --category  - Filter by device type
- --output  - Output file for config
Examples:
`bash
View all

appshot presets
Required only

appshot presets --required
Generate config

appshot presets --generate iphone-6-9,ipad-13
`
$3
Display complete Apple App Store screenshot specifications.`bash
appshot specs [options]
`
Options:
- --device  - 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:
`bash
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
$3
Validate screenshots against App Store requirements.
`bash
appshot validate [options]
`
Options:
- --strict - Validate required presets only
- --fix - Show fix suggestions
Validates:
- Resolution compliance
- Aspect ratios
- Required presets
- File formats
⚙️ Configuration Reference
`json
{
  "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
$3
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
$3
Most commands support JSON output for parsing:
`bash
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
`
$3
| 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 |
$3
`bash
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
`
$3
#### GitHub Actions`yaml
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
`bash
#!/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
`
$3
Works with Model Context Protocol tools:`bash
MCP captures screenshot

mcp-screenshot capture --output ./screenshots/iphone/home.png
Appshot processes

appshot build --devices iphone --no-interactive
`
$3
`python
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)
`
$3
``javascript
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': {

`Appshot 📸`

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

🌐 https://appshot.sh

![CI](https://github.com/chrisvanbuskirk/appshot/actions/workflows/ci.yml) ![npm version](https://www.npmjs.com/package/appshot-cli) ![npm downloads](https://www.npmjs.com/package/appshot-cli) ![Node.js Version](https://nodejs.org) ![License: MIT](https://opensource.org/licenses/MIT)

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

`$3`

- 🤖 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 | | --- | --- | --- | | !Ocean Header | !Sunset Footer | !Clean Screenshot | | Pastel Header | Noir Footer | Silver Header | | !Pastel Header | !Noir Footer | !Silver Header | | Slate Footer | Midnight Header | Tropical 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`

`$3`

- 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

`$3`

``bash

`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
$3
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
`bash
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.
$3
#### Option 1: Quick Start with Templates (NEW! 🎨)
The fastest way to get professional screenshots:
`bash
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:`bash
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!

`
$3
Need just device frames without the full treatment? Use the new frame command:`bash
Frame a single screenshot

appshot frame screenshot.png
Batch frame a directory

appshot frame ./screenshots --recursive
✨ Framed PNGs with transparent backgrounds ready!

`
$3
Automatically process screenshots as they're added:`bash
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
`
$3
`
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
`
$3
When you want a clean slate without deleting screenshots:
`bash
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.
$3
Claude Code (recommended):
`bash
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:
`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.
$3
| 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 |
$3
`
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
}
`
$3
For Claude Code users, install the appshot skill for guided workflows:
`bash
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
$3
- 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
$3
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
`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
$3
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)
$3
All settings are stored in .appshot/config.json:
`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"
}
`
$3
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
$3
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
`bash
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
`bash
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:`bash
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:`json
// 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 / }
  }
}
`
$3
Appshot includes 24+ professional gradient presets organized by category:
#### Browse & Apply Gradients
`bash
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`json
{
  "gradient": {
    "colors": ["#FF5733", "#FFC300", "#FF1493"],
    "direction": "diagonal"  // top-bottom, left-right, diagonal
  }
}
`
$3
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//background.png
2. Global: screenshots/background.png  
3. Custom: Path specified via config or CLI
#### Background Commands
`bash
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`bash
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:
`bash
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`json
{
  "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.
$3
Version 0.4.0 introduces comprehensive font management with intelligent fallbacks.
#### Font Commands
`bash
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):
   `bash
   appshot fonts --set "Helvetica"
   appshot fonts --set "SF Pro" --device iphone
   `
2. Interactive Selection:
   `bash
   appshot fonts --select
   appshot style --device iphone  # Also includes font selection
   `
3. Manual Configuration:
   `json
   {
     "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
$3
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
`bash
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 
 - Output directory (default: same as input)
- -d, --device  - Force device type (iphone|ipad|mac|watch)
- -r, --recursive - Process directories recursively
- -f, --format  - Output format: png (default) or jpeg
- --suffix  - Filename suffix (default: "-framed")
- --overwrite - Overwrite original file name
- --dry-run - Preview without processing
- --verbose - Show detailed information
#### Examples`bash
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 pixelsWhen dimensions are ambiguous, use --device to specify the target device.
$3
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.
`bash
Disable frames entirely

appshot build --no-frame
Frame-only mode (no captions or gradients)

appshot frame ./screenshots
`
$3
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.`json
{
  "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.
$3
Browse the current v2 template gallery in template-samples/index.html.
#### Caption Autocomplete
The caption command includes intelligent autocomplete:
`bash
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
$3
Appshot integrates with OpenAI for instant caption translation.
#### Setup`bash
export OPENAI_API_KEY="your-api-key-here"
`
#### Real-Time Translation
`bash
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`bash
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
`
$3
| 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 |
$3
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
$3
`bash
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
$3
| 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 |
$3
#### 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`bash
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
`
$3
`bash
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.
$3
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
$3
`bash
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
`
$3
The appshot export command bridges Appshot and Fastlane:
`bash
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
`
$3
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:
`json
{
  "languageMappings": {
    "en": "en-GB",
    "custom": "x-special"
  }
}
`
$3
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
`
$3
#### 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
$3
> 📌 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
`bash
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:
`bash
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
`
$3
> 🔍 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:
`bash
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:
`ruby
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!
`bash
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)

`
$3
`bash
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
`
$3
`yaml
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
`
$3
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
`bash
Preview and validate

appshot export --dry-run --verbose
Check what would be exported

appshot export --dry-run --json | jq
`
$3
With --generate-config, Appshot creates:
- Deliverfile: Screenshot configuration
- Fastfile: Upload lanes
- README.md: Instructions
- .gitignore: Excludes screenshots
Example generated Deliverfile:
`ruby
Generated by Appshot

screenshots_path "./screenshots"
languages ["en-US", "es-ES", "fr-FR"]
skip_binary_upload true
skip_metadata true
overwrite_screenshots true
`
$3
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
$3
Get started with App Store screenshots in seconds with interactive setup.
`bash
appshot quickstart [options]
`
Options:
- --template  - Template to use (default: ocean-header)
- --caption  - 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:
`bash
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
`
$3
One-shot v2 flow that sets layout, captions, translations, enhancement, and build in a single pass.`bash
appshot wizard [options]
`
Options:
- --devices  - Comma-separated device list (default: iphone)
- --layout  - header | footer | screenshot-only
- --template  - Apply a v2 template preset (ocean-header, sunset-footer, clean-screenshot, etc.)
- --caption-source  - filenames | manual
- --langs  - Languages to build (default: en,es,fr)
- --model  - 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:
`bash
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
`
$3
Apply professional screenshot templates for instant visual styling.`bash
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  - Preview template configuration
- --caption  - Add caption to all screenshots
- --device  - Apply to specific device only
- --no-backup - Skip config backup
- --dry-run - Preview without applying
Examples:
`bash
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
`
$3
Ultra-simple one-line commands to generate App Store screenshots with professional templates.`bash
appshot preset  [options]
`
Arguments:
-  - Template to use (ocean-header, sunset-footer, clean-screenshot, pastel-header, noir-footer, silver-header, tropical-header, slate-footer, midnight-header)
Options:
- -c, --caption  - Add caption to all screenshots
- -d, --devices  - Comma-separated device list
- -l, --langs  - Comma-separated language codes
- -o, --output  - Output directory (default: ./final)
- --dry-run - Preview without building
- -v, --verbose - Show detailed output
Examples:
`bash
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!
$3
Generate final screenshots with frames, gradients, and captions.`bash
appshot build [options]
`
Options:
- --devices  - Comma-separated device list (default: all)
- --preset  - Use App Store presets (e.g., iphone-6-9,ipad-13)
- --config  - Custom config file (default: .appshot/config.json)
- --langs  - Build for specific languages (if not specified, auto-detects)
- --preview - Generate low-res previews
- --concurrency  - 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:
`bash
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
$3
Add or edit captions with autocomplete and AI translation.
`bash
appshot caption --device  [options]
`
Options:
- --device  - Device name (required)
- --lang  - Primary language (default: en)
- --translate - Enable real-time AI translation
- --langs  - Target languages for translation
- --model  - 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:
`bash
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
`
$3
Enhance existing captions using OpenAI without translating languages.`bash
appshot caption enhance --device  [options]
`
Options:
- --device  - Device name (required)
- --lang  - Primary language (default: en)
- --langs  - Languages to enhance (comma-separated)
- --model  - OpenAI model (default: gpt-5-mini)
- --dry-run - Preview changes without writing
Examples:
`bash
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
`
$3
Validate project configuration and assets.`bash
appshot check [options]
`
Options:
- --fix - Attempt automatic fixes
Checks:
- Configuration file validity
- Screenshot presence
- Frame availability
- Directory structure
- Caption files
$3
Remove generated files and temporary data.
`bash
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:
`bash
Clean output only

appshot clean
Full reset

appshot clean --all --yes
Reset but keep screenshots

appshot clean --reset --yes
Clear history

appshot clean --history
`
$3
Run comprehensive system diagnostics to verify appshot installation and dependencies.`bash
appshot doctor [options]
`
Options:
- --json - Output results as JSON for CI/automation
- --verbose - Show detailed diagnostic information
- --category  - 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:
`bash
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
`
$3
Browse, validate, and set fonts for captions. Includes 8 high-quality embedded fonts for consistent rendering across all platforms.
`bash
appshot fonts [options]
`
Options:
- --all - List all system fonts
- --embedded - Show embedded fonts bundled with appshot
- --recommended - Show recommended fonts only (default)
- --validate  - Check if font is available (embedded or system)
- --set  - Set the caption font
- --select - Interactive font selection
- --device  - 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:
`bash
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
`
$3
Apply device frames to screenshots with transparent backgrounds (no gradients or captions).`bash
appshot frame  [options]
`
Arguments:
-  - Input image file or directory
Options:
- -o, --output 
 - Output directory (default: same as input)
- -d, --device  - Force device type (iphone|ipad|mac|watch)
- -r, --recursive - Process directories recursively
- -f, --format  - Output format: png or jpeg (default: png)
- --suffix  - Filename suffix when not overwriting (default: "-framed")
- --overwrite - Overwrite original file name
- --dry-run - Preview files without processing
- --frame-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 batchesExamples:
`bash
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
`
$3
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.`bash
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.
`bash
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.
$3
Install the appshot skill for Claude Code. The skill provides workflow guidance, template recommendations, and troubleshooting help.
`bash
appshot skill [options]
`
Options:
- --force - Overwrite existing installation
- --uninstall - Remove the skill
- --path 
 - Custom installation pathExamples:
`bash
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
$3
Capture screenshots from iOS simulators.
`bash
appshot device  [options]
`
Commands:
- capture - Capture screenshot from device
- list - List available devices
- prepare - Boot simulators
Capture Options:
- -d, --device  - Device name or alias
- --all - Capture from all devices
- --simulators - Filter simulators
- --booted - Currently booted simulators
- --process - Auto-process with frames
- --app  - Launch app before capture
Examples:
`bash
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
`
$3
Monitor directories for new screenshots with automatic processing.`bash
appshot watch  [options]
`
Commands:
- start - Start watching directories
- stop - Stop the watch service
- status - Check service status
- setup - Interactive configuration
Start Options:
- -d, --dirs  - Directories to watch
- --devices  - Device names for processing
- --process - Auto-process with frames
- --frame-only - Frames only (no gradient/caption)
- --background - Run in background
- --verbose - Detailed output
Examples:
`bash
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
`
$3
Manage gradient presets.`bash
appshot gradients [options]
appshot gradients select
`
Options:
- --list - List all presets (default)
- --category  - Filter by category
- --preview  - Generate preview image
- --sample - Generate all samples with HTML
- --apply  - Apply preset to project
Examples:
`bash
Browse all

appshot gradients
Apply preset

appshot gradients --apply ocean
Interactive selection

appshot gradients select
Generate samples

appshot gradients --sample
`
$3
Initialize new project with scaffolding.`bash
appshot init [options]
`
Options:
- --force - Overwrite existing files
Creates:
- .appshot/config.json
- .appshot/captions/
- screenshots/ directories
- Default configuration
$3
Batch translate all captions using AI.
`bash
appshot localize --langs  [options]
`
Options:
- --langs  - Target languages (required)
- --device  - Specific device only
- --model  - OpenAI model (default: gpt-4o-mini)
- --source  - Source language (default: en)
- --review - Review before saving
- --overwrite - Replace existing translations
Examples:
`bash
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
`
$3
Manage App Store screenshot presets.`bash
appshot presets [options]
`
Options:
- --list - List all presets (default)
- --required - Show required only
- --generate  - Generate config for presets
- --category  - Filter by device type
- --output  - Output file for config
Examples:
`bash
View all

appshot presets
Required only

appshot presets --required
Generate config

appshot presets --generate iphone-6-9,ipad-13
`
$3
Display complete Apple App Store screenshot specifications.`bash
appshot specs [options]
`
Options:
- --device  - 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:
`bash
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
$3
Validate screenshots against App Store requirements.
`bash
appshot validate [options]
`
Options:
- --strict - Validate required presets only
- --fix - Show fix suggestions
Validates:
- Resolution compliance
- Aspect ratios
- Required presets
- File formats
⚙️ Configuration Reference
`json
{
  "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
$3
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
$3
Most commands support JSON output for parsing:
`bash
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
`
$3
| 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 |
$3
`bash
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
`
$3
#### GitHub Actions`yaml
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
`bash
#!/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
`
$3
Works with Model Context Protocol tools:`bash
MCP captures screenshot

mcp-screenshot capture --output ./screenshots/iphone/home.png
Appshot processes

appshot build --devices iphone --no-interactive
`
$3
`python
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)
`
$3
``javascript
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': {