Installing Shotlist

Shotlist comes in two parts that share one engine:

• The Mac app, for working in a window: a live capture matrix, before-and-after review, captions side by side, creative assets and the App Store Connect plan.
• The shotlist CLI, for the terminal, scripts, CI and coding agents.

Install either or both. They read and write the same project files, and one licence activation on a Mac covers both.

Before you start, install Xcode 27 or later and its iOS 27 simulator runtimes. See Requirements.

Install Xcode and the simulator runtimes

1. Install Xcode 27 or later. To capture the iPhone Duo you need Xcode 27.1, because the Duo simulator runs only on iOS 27.1.

2. Make it the active developer directory, so xcodebuild and simctl find it:

   sudo xcode-select -s /Applications/Xcode.app

3. In Xcode › Settings › Components, install the iOS 27 simulator runtimes. With Xcode 27.1, iOS 27.1 supports only the iPhone Duo; every other device needs iOS 27.0.

4. Open Xcode once and let it finish installing its components.

Shotlist picks the newest installed runtime that supports each device, so you don’t choose runtimes yourself.

Where to download

Both downloads are attached to every release on Shotlist’s releases page, which the Shotlist page links to:

File	What it is
Shotlist-<version>.dmg	The Mac app.
shotlist-cli-<version>.zip	The shotlist command-line tool.

Install the Mac app

The app needs macOS 26 or later on an Apple silicon Mac.

1. Download Shotlist-<version>.dmg from the latest release.
2. Open it and drag Shotlist to Applications.
3. Open Shotlist from Applications. The Welcome window appears.

The app is signed and notarised. It keeps itself up to date through Sparkle: choose Shotlist › Check for Updates… at any time.

Install the CLI

The CLI comes as a zip download only, for now. It holds one universal binary, for Apple silicon and Intel Macs, signed and notarised.

1. Download shotlist-cli-<version>.zip from the latest release.

2. Unzip it and put shotlist somewhere on your PATH:

   unzip shotlist-cli-<version>.zip
   sudo mkdir -p /usr/local/bin
   sudo mv shotlist /usr/local/bin/

3. Check it runs:

   shotlist --version

A bare executable can’t carry a stapled notarisation ticket, so macOS checks the ticket online the first time you run it. Run it once while you’re online.

To update the CLI, download the new release’s zip and replace the binary the same way.

Help for every command

Every command and subcommand has built-in help:

shotlist --help
shotlist help capture
shotlist captions draft --help

Every command also takes --project-dir <folder>, the folder that holds Shotlist/ (the current folder by default), and --json, which prints the result as JSON for scripts and agents. See CI and automation.

Activate your licence

Capturing, composing and uploading need a Shotlist subscription. Setting up, doctor, verify, captions and the publish plan are free, so you can try everything up to the first capture without one. See Subscription for the details.

Your licence key is in your Polar receipt. One key covers up to 3 Macs, and activating it once on a Mac covers both the app and the CLI there.

In the CLI:

shotlist licence activate <key>

It prints ✓ Activated <key> on <this Mac's name>. The Mac’s name comes from System Settings › General › Sharing, and it’s how you tell your activations apart.

Check it at any time:

shotlist licence status

shotlist license works as well as shotlist licence.

In the Mac app: try a paid action, such as Capture, and the subscribe sheet appears. Paste your key and choose Activate. You can also activate in Shotlist › Settings… (⌘,), which shows a key field when this Mac has no subscription.

The licence is kept in your login Keychain, where the app and the CLI share it. The first time the other one reads it, macOS asks whether it may use the Keychain item. Choose Always Allow, or it asks every time.

Check the Mac

Run doctor from your app’s repo, or from any folder:

shotlist doctor

In the Mac app, choose Check This Mac in the Welcome window. It runs the same checks.

A typical report:

✓ OK    Xcode: Xcode 27.1
✓ OK    shotlist.json: 2 slots, 1 locales, 1 scenes
✓ OK    Project: MyApp.xcodeproj
✓ OK    Runtime for iphone-6.9: iPhone-17-Pro-Max on iOS 27.0
✓ OK    Runtime for iphone-6.3: iPhone-17-Pro on iOS 27.0
✓ OK    Free disk: 247 GB free; each simulator takes 2 to 6 GB
✓ OK    Shotlist simulators: none yet; capture creates them

Check	What it looks at	When it fails or warns
Xcode	xcodebuild -version	Fails if Xcode is missing, not selected, or older than 27.
shotlist.json	Loads and validates Shotlist/shotlist.json, if there is one	Fails with the validation error. Without a Shotlist/ folder, the check is skipped.
Project	The project or workspace named in shotlist.json	Fails if it isn’t found next to Shotlist/.
Runtime for each slot	Installed iOS runtimes, for every slot in shotlist.json (every slot Shotlist knows, without a project)	Fails if no installed runtime supports that slot’s device.
Free disk	Space on your home volume	OK at 15 GB or more, a warning from 5 GB, a failure below 5 GB.
Shotlist simulators	Simulators whose names start with Shotlist ·	Never fails; lists them with their state.
iPhone Duo posture	Whether this process may use Accessibility (only when a Duo slot is listed)	Warns that the unfold will be a guided step if Accessibility isn’t granted.
Screen	Whether the Mac’s screen is locked (Duo only)	Warns that inner-display captures need it unlocked.
Device Hub	Device Hub inside Xcode.app (Duo only)	Warns if it isn’t at the usual path.

doctor exits 1 if any check fails, and 0 otherwise. Warnings don’t fail it. shotlist doctor --json prints the checks as JSON.

Allow Accessibility for the iPhone Duo

Only needed if you capture the Duo’s inner display. Shotlist unfolds the Duo by pressing Device Hub’s own posture buttons through the Accessibility API. Without permission, it asks you to unfold the Duo by hand once per run instead.

1. Open System Settings › Privacy & Security › Accessibility.
2. Turn on the app that runs Shotlist: Terminal (or iTerm, or whichever terminal runs the CLI), and Shotlist.app if you use the Mac app.
3. Run shotlist doctor again. The iPhone Duo posture check should say “automatic”.

See iPhone Duo.

Uninstalling

• Mac app: drag Shotlist from Applications to the Bin.
• CLI: delete the binary: sudo rm /usr/local/bin/shotlist.
• Licence: run shotlist licence deactivate (or Deactivate This Mac in the app’s Settings) first, to free this Mac’s place for another Mac.
• Simulators: Shotlist’s simulators stay until you delete them. List them with xcrun simctl list devices | grep "Shotlist ·", and delete one with xcrun simctl delete <udid>. Never delete simulators that don’t start with Shotlist · : those are yours.
• Project files: Shotlist/ and .shotlist/ in your repo.