FAQ

Does any of this end up in my App Store build?

No. Everything in ShotlistKit, ShotlistDependencies and ShotlistTCA is inside #if DEBUG, and so are your Screenshots.swift and the host code in your entry point (@Shot puts it there for you; ShotlistMacros itself declares only the macro). A Release build contains none of it. check-release-symbols.sh proves it in CI; see CI and automation.

Does it affect normal Debug runs?

No. The host only takes over when Shotlist.isActive is true, which is only when the Shotlist engine launched the app. Running from Xcode, tests and previews are unaffected.

Do I need TCA?

No. Shotlist works with SwiftUI and @Observable, with UIKit, and with TCA. TCAScene is a shortcut for TCA apps, in its own product. See Writing scenes.

Do I need a UI test target?

No. Scenes are built in the app itself, from your real root, with state you pass in. There are no taps, gestures or element queries.

Will it touch my simulators?

No. Shotlist creates and uses its own, named Shotlist · <slot> · <runtime>, and addresses every simulator by its UDID. Your simulators and the apps on them are never touched, even while they’re running. The one thing to avoid: quitting Device Hub during a run shuts down every booted simulator, yours included.

Can I capture on a real device?

No. Shotlist captures on simulators, which give Apple’s exact sizes natively and can be driven unattended.

Can I run two captures at once?

Not on one Mac. Every project shares Shotlist’s simulators, so a second capture stops at once and says another is running. compose, verify, captions and publish can run alongside a capture.

How long does a run take?

On an Apple silicon Mac, a 16-cell run with booted simulators takes about 90 seconds, and 192 cells about 6 minutes. The first run is slower: it builds the app and creates the simulators. See Capturing.

Why wait 2.5 seconds after a launch, if there are no sleeps?

iOS fades out the home indicator about 2 s after an app opens, and nothing signals it. So the first capture after each launch must come from a stable pair of frames that starts at least 2.5 s after the launch. It’s the one duration-based wait in Shotlist, and it’s still bounded by the frame check. See Making runs identical.

My dark screenshots aren’t in the composed set. Why?

Compose makes one screenshot per sequence entry. An entry without its own appearance is composed in the first appearance in appearances. To publish a screenshot in dark, give its entry "appearance": "dark". See Configuration.

Can I have more than 10 screenshots?

No: App Store Connect takes at most 10 per size and locale, so sequence has at most 10 entries.

Do I have to capture every size?

No. List only the slots you need. Apple currently requires iphone-6.3 for iPhone, ipad-13 if the app runs on iPad, and both iPhone Duo sizes from April 2027 for apps built with the iOS 27.1 SDK. See Slots.

What about landscape?

iPhone and iPad slots capture as the simulator is held: portrait. The iPhone Duo’s inner display can be landscape (the default) or portrait.

Can I use my own fonts in captions?

Not yet. Captions are always SF Pro, in the weight the template sets. Backgrounds, colours, sizes and layouts are yours to change. See Templates.

Can I use device frames?

Shotlist draws the capture with the device’s corner radius and a soft shadow (frameless). Device bezels aren’t included.

Where do my files go?

Raw captures to Shotlist/Output/raw/, composed screenshots to Shotlist/Output/composed/<locale>/<slot>-NN.png, and creative assets to Shotlist/Output/creative/. See Where things live.

Can I use the output with fastlane or another tool?

Composed screenshots follow fastlane’s <locale>/ folder layout, so tools that read fastlane screenshot folders can read them. You can use Shotlist for capture and composing, and upload some other way.

What should I commit?

Everything in Shotlist/ except Output/ (already in its .gitignore): shotlist.json, Captions.xcstrings, Fixtures/, Templates/ and published.json. Also your Screenshots.swift. .shotlist/ ignores itself.

Does Shotlist submit my app for review?

No. It uploads screenshots and places creative assets on an editable version, and that’s all. You submit the version yourself.

Will it delete screenshots I uploaded by hand?

Not unless you pass --prune (or turn on Delete screenshots Shotlist didn’t upload in the app). Without it, your own uploads are kept, after Shotlist’s. See Pruning.

Why are the iPhone Duo’s inner screenshots not uploaded?

App Store Connect’s API has no display type for the inner display. The plan marks them as export; upload them by hand. The outer display can be uploaded with --experimental-duo. See iPhone Duo.

What data leaves my Mac?

• Capture and compose: nothing. Builds, simulators and fixtures are local. (Your build may fetch its packages.)
• captions draft: with Apple’s on-device Translation, nothing. With the Claude API, the source captions, the target language and your --context go to Anthropic, under your own API key.
• publish: your composed screenshots and creative assets go to App Store Connect, under your own key.
• Subscription checks: your licence key, and when activating this Mac’s name, go to Polar.

Your App Store Connect key stays on your Mac: in the Keychain for the app, at the path you give for the CLI. It never appears in logs, output or the project.

Can a coding agent use Shotlist?

Yes. Every command takes --json, exits non-zero on failure, and names what to fix in its errors. See CI and automation.

Does it work offline?

Capturing and composing do, and a subscription keeps working for 14 days without reaching Polar. See Working offline.

What doesn’t Shotlist do?

Android or Google Play, 3D device rendering, App Preview videos, keyword or metadata optimisation, TestFlight, and submitting for review.