The Mac app

The Mac app runs the same engine as the CLI, on the same project files, with a window: a live capture matrix with before-and-after review, locales side by side in Compose, creative assets with Apple’s safe areas, and the App Store Connect plan as a table.

Anything you do in the app, you can do in the CLI, and the other way round. A capture started in either one shows up in the other’s files.

The app is always dark, whatever your Mac’s appearance. Every status is shown as a glyph and a word, never by colour alone.

It needs macOS 26 or later on an Apple silicon Mac. See Installing Shotlist.

Welcome window

The Welcome window opens when you start the app with no project open. Reopen it with File › Welcome to Shotlist (⇧⌘1).

Control	What it does
Open Project… (⌘O, also in the File menu)	Choose the folder that holds your app’s Xcode project and Shotlist/.
Set Up a Project…	Choose that folder for a project without Shotlist yet. Runs shotlist init there and opens the project. Then add ShotlistKit and write your scenes; see Setting up a project.
Check This Mac	Runs the same checks as shotlist doctor and lists them, each with a glyph and OK, Warning or Failed.
Recent Projects	The last eight projects you opened. Click one to open it.

Each project opens in its own window, and open windows come back when you relaunch the app.

To open a project from a terminal or script, pass its folder at launch:

open -a Shotlist --args -openProject ~/Developer/MyApp

The project window

A narrow rail on the left switches between five screens:

Screen	Shortcut	For
Scenes	⌘1	The sequence and each scene’s capture state.
Matrix	⌘2	Capturing and reviewing every cell.
Compose	⌘3	Captions and composed screenshots, locales side by side.
Creative	⌘4	Header and search art.
Publish	⌘5	Verify, the App Store Connect plan, and upload.

The window’s subtitle names the screen you’re on.

Scenes

A table of your sequence, in product-page order:

Column	Shows
#	The position, 01 to 10.
Scene	The scene id.
Template	The entry’s template, or caption-top.
Appearance	The entry’s appearance, or All.
Captured	“All 16” when every applicable cell has a capture, “12 of 16” otherwise, or “2 failed · 12 of 16”.

Scenes are code: add or change them in your app’s Screenshots.swift, then list their ids in sequence. Reload reads shotlist.json and the manifest again after you edit them.

Matrix

The Matrix shows one size at a time: locales down the side, scenes across the top. Each cell is a thumbnail of its capture with its status as a glyph and a word:

Status	Meaning
New	Captured for the first time.
Changed	Different from the last run.
Unchanged	Identical to the last run, or different only by rendering noise.
Failed	Couldn’t be captured. Hover over it for the reason, or select it.
Waiting	Queued in the current run.
Not captured	No capture yet.
Not used here	The scene doesn’t run in this slot’s posture (iPhone Duo).

Cells fill in live as each one lands.

Toolbar

Control	What it does
Size picker	Chooses which slot the matrix shows.
Needs Attention	Shows only new, changed and failed cells; the rest are dimmed. If none need attention: “Nothing Needs Attention: Every cell at this size matches the last run.”
Last run and counts	“Last run 1 Nov, 10:42 · 32 captured”, and the number of new, changed and failed cells. During a run, progress per simulator instead: “iPhone 6.3″ 5/16”.
Run Log	Opens the log in an inspector, as it runs: the newest 500 lines.
Capture (⌘R)	Builds the app and captures every cell, as shotlist capture does. During a run it becomes Stop (⌘.).

The app always builds before capturing. For --skip-build, --keep-warm or a filtered run, use the CLI.

If the iPhone Duo needs unfolding by hand, a banner above the matrix says so; see iPhone Duo. If a run can’t start, a banner gives the reason.

Moving around

Click a cell to select it. The arrow keys move between cells, and the selection scrolls into view. Control-click a cell for Recapture and Show in Finder.

Before and after

The strip below the matrix shows the selected cell:

• its locale, scene, size and appearance;
• its status, and an explanation: “Changed since the last run: perceptual distance 3 of 64.”, “Unchanged. 214 pixels differed by rendering noise alone (2 levels at most), so the last run’s file was kept.”, or a failure’s full reason;
• Before · last run and After · this run, either Side by Side or Swipe: one image over the other with a divider you drag, before on the left;
• Recapture (⇧⌘R), which captures just this cell: its slot, locale and scene;
• Show in Finder, which reveals the capture.

There’s nothing to accept. The next run compares against what’s there now.

Compose

Compose shows one scene at one size, in up to four locales side by side, at their true aspect ratio.

Toolbar

Control	What it does
Scene	Which scene to show.
Size	Which slot.
Locales	Choose up to four locales to compare.
Changed Only	On by default: compose re-renders only screenshots whose capture, caption or template changed. Turn it off for a full compose, for example after removing scenes from the sequence.
Inspector	Shows or hides the inspector.
Compose (⌘B)	Renders composed screenshots and creative assets, as shotlist compose does.

Under each locale’s screenshot is its caption state (Reviewed, Needs review or Missing). A locale whose caption overflows is outlined and says why: “Overflows: …”.

Inspector

Template. The selected scene’s template: its layout, caption size, smallest caption size, most lines and subtitle size, as percentages of the canvas’s shorter side. Show Templates in Finder opens Shotlist/Templates/. Edit templates there; see Templates.

Captions. One row per locale: Ready, “3 need review” or “2 missing”.

• Mark Reviewed… appears beside a locale with machine drafts. It asks first: “Only do this once someone who reads de-DE has checked all 3 machine-drafted captions. Reviewed captions can be published.” It’s shotlist captions review for that locale.
• Draft Missing Captions machine-translates every missing caption, as shotlist captions draft does. Drafts stay marked for review.
• Open Captions.xcstrings opens the catalogue, normally in Xcode.

Last Compose. The last compose’s summary: how many were composed and unchanged, the creative files, every failure, content rule findings and warnings.

Creative

The product page header and search results art for one locale.

Control	What it does
Locale	Which locale’s art.
Asset	Header or Search.
16:9	Shows the 5244 × 2950 alternative.
Safe Areas	Shows the art with Apple’s safe area drawn on.

With Search chosen, the art at search-results size is pinned beside it, at a tenth of its size: “1/10 scale. The headline should still read here: 14 px or more.” Any legibility warning from the last compose shows below it.

If there’s nothing yet: “Not composed yet. Compose writes the creative assets.” Compose in the app also writes the safe-area copies this screen shows.

See Creative assets.

Publish

Toolbar

Control	What it does
Verify	Runs shotlist verify and shows the report in the inspector.
Plan	Compares your composed screenshots and creative assets with App Store Connect, and changes nothing.
Inspector	Shows or hides the inspector.
Upload…	Carries out the plan, after a confirmation. Available once a plan has changes to make.

The plan

Above the table: the version and its state (“Version 2.1, Prepare For Submission”), and “4 changes to make”, or Uploaded after an upload. Any problem is listed there too.

The table has a row per locale and size under Screenshots, and per locale and kind under Creative:

Column	Shows
Locale	The locale.
Size	The slot, or Header or Search.
Action	Add, Replace, Reorder, Unchanged, Delete, Export, Skip or Blocked, each with its glyph.
Files	How many files, and how many are live now.
Detail	What it would do, or why it can’t.

See The plan for what each action means.

Inspector

App Store Connect Key. Enter the Key ID and Issuer ID, then Choose .p8 File…. The key goes into your login Keychain and nowhere else; the inspector then says “Kept in your Keychain”. Remove Key… takes it out of the Keychain after asking; the .p8 file isn’t touched. The CLI doesn’t use this key; see The API key.

Options.

• Delete screenshots Shotlist didn’t upload: --prune.
• Upload the Duo’s outer display (experimental): --experimental-duo.

Changing either discards the plan, so you plan again before uploading.

Verify. The last verify report: “64 files pass”, or the problems (the first 40, and how many more). Upload refuses while verify has problems, unreviewed captions included. The app has no equivalent of --allow-unreviewed.

Uploading

Upload… asks first, naming the version and counting the changes:

Upload to version 2.1? 12 screenshots in 3 sets across 2 locales. 2 creative asset changes. This changes the listing in App Store Connect. Nothing is submitted for review.

With pruning on, it adds: “Screenshots Shotlist didn’t upload will be deleted from these sets.” Choose Upload to go ahead, or Cancel.

Settings and subscription

Capture, Recapture, Compose and Upload need a subscription. The first time you try one without a subscription, the subscribe sheet appears, saying what you tried to do:

Button	What it does
Start Free Trial…	Opens the checkout in your browser. Your licence key arrives in the receipt.
Activate	Activates the licence key you’ve pasted into the sheet.
Not Now	Closes the sheet.

Shotlist › Settings… (⌘,) shows the licence on this Mac:

• with a subscription: its status, the key (all but its end hidden), the account email, Manage Subscription… (Polar’s customer portal), Check Now (asks Polar straight away) and Deactivate This Mac (frees this Mac’s place on the key);
• without one: Start Free Trial… and a field for your licence key.

Browsing a project (the matrix, before and after, composed screenshots, creative art, the plan) is always free. See Subscription.

Updates

Shotlist › Check for Updates… checks for a new version and installs it.

Keyboard shortcuts

Shortcut	Action
⌘O	Open Project…
⇧⌘1	Welcome to Shotlist
⌘1 to ⌘5	Scenes, Matrix, Compose, Creative, Publish
⌘R	Capture
⌘.	Stop the capture
Arrow keys	Move between matrix cells
⇧⌘R	Recapture the selected cell
⌘B	Compose
⌘,	Settings

Accessibility

• Every status, in every screen, is a glyph and a word.
• Every toolbar button has a text label.
• Matrix cells read as “locale, scene, status” to VoiceOver, and activate like buttons.
• The matrix takes keyboard focus, with a visible focus ring, so the arrow keys move between cells.

Using the app and the CLI together

• They share the project files, so you can capture in the terminal and review in the app. Choose Reload in Scenes to pick up a run made outside the app.
• One capture runs at a time on a Mac, whichever started it. Starting a second shows “another shotlist capture is running on this Mac”.
• One licence activation covers both.
• They keep the App Store Connect key separately: the app in the Keychain, the CLI in environment variables or ~/.config/shotlist/asc.json.
• For the iPhone Duo’s automatic unfold, each needs its own Accessibility permission: Shotlist.app for the app, your terminal for the CLI.