Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install screenforge

It will make the screenforge command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall screenforge uninstalls.

Back to the crate overview.

Readme

Screenforge

A Rust CLI for generating App Store-style marketing screenshots.

Features

Capture screenshots from files or iOS simulators
Render deterministic backgrounds (mesh gradients, stripes)
Auto-extract color palettes from screenshots
Composite phone mockups with accurate device frames
Render Dynamic Island for supported devices
Add headline and subheadline text overlays
Generate HTML preview gallery
Support for transparent PNG frame overlays

Installation

cargo install --path .

Or build from source:

cargo build --release

Quick Start

Run the full pipeline from a config file:

screenforge run --config screenforge.yaml
open output/index.html

Capture a framed screenshot from a running iOS simulator:

screenforge snap "iPhone 16 Pro" --headline "Your App" --subheadline "Tagline here"

List booted simulators:

screenforge snap --list

Commands

run

Execute the full pipeline: capture, background, compose, and preview.

screenforge run --config ./screenforge.yaml

snap

Capture and frame a screenshot from a running iOS simulator. Auto-detects device model.

screenforge snap "iPhone 16 Pro"
screenforge snap "My-Simulator" --output hero.png
screenforge snap --raw                           # Raw screenshot without framing
screenforge snap --auto-colors --auto-strategy analogous

Options:

--output - Output file path (default: snap_output.png)
--raw - Capture raw screenshot without framing
--model - Override auto-detected phone model
--headline / --subheadline - Text overlays
--background - Background template (mesh or stripes)
--seed - Background seed for deterministic generation
--colors - Comma-separated hex colors
--auto-colors - Extract colors from screenshot
--auto-strategy - Color strategy (monochromatic, analogous, complementary, triadic)
--width / --height - Output canvas dimensions
--settle-ms - Wait time before capture (default: 500ms)
--format - Output format (text or json)

devices

List built-in phone model presets.

screenforge devices

Supported models:

iphone_16_pro
iphone_16_pro_max
iphone_17_pro
iphone_17_pro_max

import-frames

Import transparent PNG frame overlays into assets/frames.

screenforge import-frames --source ~/Downloads/frames
screenforge import-frames --source ./frames --dest assets/frames --overwrite

convert-frames

Convert mockup frames with white screens to transparent overlays.

screenforge convert-frames --source ./mockups
screenforge convert-frames --source ./mockups --white-threshold 240

verify-overlay

Validate overlay files referenced by config scenes.

screenforge verify-overlay --config screenforge.yaml
screenforge verify-overlay --config screenforge.yaml --strict

Checks:

Overlay file exists
Overlay decodes correctly
Overlay has transparent pixels
Overlay dimensions match phone dimensions (warning unless --strict)

Configuration

Full Example

output_dir: ./output

scenes:
  - id: home_screen
    capture:
      adapter: file
      path: ./screenshots/home.png
    output:
      filename: 01-home.png
      width: 1290
      height: 2796
    background:
      template: mesh
      seed: 42
      colors:
        - "#0B1022"
        - "#16479A"
        - "#2B8CD6"
        - "#A9E7FF"
    phone:
      model: iphone_16_pro
      x: 170
      y: 430
      width: 950
      height: 1980
    copy:
      headline: "Your Headline"
      subheadline: "Your subheadline text here."
      color: "#FFFFFF"
      x: 86
      y: 94
      headline_size: 120
      subheadline_size: 56
      line_gap: 24

Capture Adapters

File adapter - Load an existing image:

capture:
  adapter: file
  path: ./screenshots/home.png

Simctl adapter - Capture from iOS simulator:

capture:
  adapter: simctl
  device: "booted"      # or simulator UDID
  settle_ms: 1200       # wait before capture

Background Options

Mesh gradient:

background:
  template: mesh
  seed: 42
  colors:
    - "#0B1022"
    - "#16479A"
    - "#2B8CD6"
    - "#A9E7FF"

Stripes:

background:
  template: stripes
  seed: 99
  colors:
    - "#04172B"
    - "#0773B8"
    - "#37C4AA"
    - "#D0FFF1"

Auto-extracted colors:

background:
  template: mesh
  seed: 42
  auto_colors: true
  auto_strategy: analogous  # monochromatic | analogous | complementary | triadic

Color strategies:

monochromatic - Variations of the dominant color
analogous - Adjacent colors on the color wheel
complementary - Opposite colors for high contrast
triadic - Three equally spaced colors

Phone Configuration

phone:
  model: iphone_16_pro       # optional, enables preset styling
  x: 170                     # horizontal position
  y: 430                     # vertical position
  width: 950                 # phone width
  height: 1980               # phone height
  corner_radius: 116         # optional, defaults from model
  frame_color: "#7A7F89"     # optional, defaults from model
  frame_border_width: 13     # optional, defaults from model
  shadow_offset_y: 24        # optional, defaults from model
  shadow_alpha: 82           # optional, defaults from model
  overlay: ./frames/custom.png  # optional transparent frame overlay

If overlay is not specified, Screenforge looks for assets/frames/<model>.png.

Text Configuration

copy:
  headline: "Your Headline"
  subheadline: "Supporting text"
  color: "#FFFFFF"
  x: 86
  y: 94
  headline_size: 120           # font size in pixels
  subheadline_size: 56
  headline_weight: bold        # regular | medium | semi_bold | bold
  subheadline_weight: regular
  line_gap: 24                 # gap between headline and subheadline
  max_width: 1000              # optional, for text wrapping

Frame Overlays

For pixel-perfect device frames, use transparent PNG overlays:

Import existing overlays:

screenforge import-frames --source ~/Downloads/frames

Or convert white-screen mockups:

screenforge convert-frames --source ./mockups

Validate overlays:

screenforge verify-overlay --config screenforge.yaml --strict

Overlays are auto-loaded from assets/frames/<model>.png when available.

Output

Running the pipeline generates:

Individual PNG files in output_dir
index.html preview gallery

License

MIT