Showpiece Help

Getting started

A project is a set of slides. Each slide becomes one App Store image, rendered at every size you export. The App Store takes up to ten per device, and the slide list shows how many you have.

1. Pick a template in the welcome window (iPhone, iPhone & iPad, Mac, Apple Watch, Apple TV or Apple Vision Pro) to start with the sizes App Store Connect requires.
2. Add screenshots. Drag images onto the canvas or onto a slide, or choose File › Import Screenshots… (⇧⌘I). Several images fill several slides in order.
3. Choose a look with Slide › Choose Presets… (⇧⌘P), then adjust anything in the inspector.
4. Write captions in the Text tab. Wrap a word in asterisks to highlight it, as in Track every *mile*.
5. Export with File › Export Screenshots… (⌘E).

Projects are saved as .showpiece files with your original screenshots inside, so you can reopen, edit and export them again for each release.

Designing slides

The inspector on the right edits the selected slides. Select several (⇧- or ⌘-click) to change them all at once.

Text

Title and subtitle, whether they sit at the top or bottom and how they align, and each one’s font, weight, size, color, highlight color, line spacing and letter spacing.

Device

Show the screenshot in a drawn device frame, as a bare screenshot with rounded corners, or hide the device to make a text-only slide. On the canvas, drag the device to move it, drag a corner to resize it, and drag the knob above it to rotate it. The arrow keys nudge it (hold ⇧ for bigger steps). 3D Turn and 3D Tilt give it an angle. Project Settings chooses the frame style for each kind of device, or a frame picture of your own: a PNG whose screen area is transparent.

Background

A solid color, a linear or radial gradient, or an image. Choose Continue from Previous Slide (or Slide › Join with Previous Slide, ⌘J) to make two or more slides one wide panorama that runs across them in the App Store.

Layers

Extra devices, images (badges, logos) and text labels on top of or behind the main device.

Other devices

By default a slide looks the same on every device, scaled to fit. Turn on Separate Layout for iPad (or Mac, and so on) to arrange a device family differently.

Reusing a look

Slide › Apply Design to All Slides copies the selected slide’s design to the rest. Edit › Copy Style and Paste Style (⌥⌘C, ⌥⌘V) copy it between slides or projects. In the preset gallery you can save the current design as a preset of your own.

Languages

Add languages in Project Settings (⇧⌘,) and switch between them in the toolbar. Each language has its own captions and can have its own screenshots. Anything missing falls back to the base language.

Slide › Translate Captions… translates missing captions with Apple’s on-device translation. Translated captions are marked for review until you choose Slide › Mark Translations as Reviewed.

Exporting

Export saves one image for each slide, size and language, at the exact pixel sizes App Store Connect accepts. Images are PNG or JPEG, in sRGB or Display P3, with no transparency. Files are arranged as <language>/<size>_<number>.png, the layout fastlane’s deliver uploads from. Before you export, Showpiece lists anything App Store Connect would reject, like a missing screenshot, along with suggestions, like captions too small to read in search results.

Uploading to App Store Connect

File › Upload to App Store Connect… (⇧⌘U) sends the images straight to an app version that is still being prepared. It needs an App Store Connect API key, which the Account Holder or an Admin can make:

1. In App Store Connect, open Users and Access, then Integrations. If your team has never made a key, the Account Holder needs to click Request Access first.
2. Under Team Keys, click Generate API Key (or +), name it Showpiece, and give it the App Manager role.
3. Copy the Issuer ID shown above the list of keys, and the new key’s Key ID from the list.
4. Click Download beside the key to get its .p8 file. Apple lets you download it only once.

Enter the Issuer ID and Key ID in Showpiece and choose the file. Showpiece saves the key in your keychain, so you only need to do this once on each Mac. Use a Different Key… removes it.

You can choose to replace the screenshots already on the version for the sizes and languages you send. Other sizes and languages are left alone.

Showpiece Pro

Designing is free, including every preset, frame and language, and the command line’s contact sheets. Exporting and uploading need Showpiece Pro, which shows its current plans and prices when you choose to buy it. Choose Showpiece › Showpiece Pro… to buy it, restore a purchase on another Mac, or manage your subscription. It also comes up if you try to export or upload without it.

The command line can export on any Mac where you’ve opened Showpiece since buying Pro. Without it, export and apply --export stop with exit status 3. Everything else still works.

Using Showpiece with coding agents

A coding agent like Claude Code, Codex or Cursor can update a project’s screenshots and captions from your app’s repository, and even choose a design for a new project. Showpiece’s command line does the work. You review the result in the app and export when you’re happy.

The quickest way to set this up is Help › Use with Coding Agents… with your project open. It does the steps below for you and writes the prompt to give your agent.

1. Save the project somewhere in your app’s repository, for example AppStore/AppStore.showpiece.
2. Allow its folder. The App Store version of Showpiece can only read and write in folders you’ve allowed in Settings › Folder Access. Allow the folder the project is in. The agent keeps its screenshots and manifest there too.
3. Give your agent the prompt from Use with Coding Agents. It tells the agent where Showpiece is and to read agent-guide, which explains everything else.
4. Optionally, keep the guide for next time. Save it for Claude Code (in ~/.claude/skills/showpiece), or copy it into AGENTS.md or wherever your agent keeps its rules.

How it works

The agent writes a small manifest, showpiece.json, listing the languages, sizes, slides and captions, and where the raw screenshots are. Then it uses

/Applications/Showpiece.app/Contents/MacOS/Showpiece apply showpiece.json

which updates the project to match. Slides are found by a short key, so running it again for the next release replaces the screenshots and captions and leaves your design alone. A project that is open in Showpiece updates as the agent works. Other commands let the agent look at its work: render --sheet draws all slides side by side, presets --catalog draws every preset on a real screenshot, and lint reports problems. Run Showpiece --help for the full list.

Agents never upload to App Store Connect, and only export when you ask them to.

Keyboard shortcuts

VoiceOver

Each slide is read by its number and captions, followed by anything missing, such as a screenshot for the current device. Use the VoiceOver actions menu (VO-⌘-Space) on a slide to move, duplicate or delete it. The selected device’s Size and Rotation are adjustable with VO-↑ and VO-↓, and its Position offers Move Left, Right, Up and Down actions. Every setting is also in the inspector as a slider with a number field.

Privacy

Your projects and screenshots stay on your Mac. Showpiece sends anonymous counts of which features get used, like exports and presets, and short codes for errors, to see what’s worth improving. They never include your captions, screenshots, file names or anything that identifies you. You can turn this off in Settings. The command line also sends nothing when the DO_NOT_TRACK environment variable is set. Purchases are handled by Apple, and RevenueCat keeps track of whether you have Showpiece Pro. The full privacy policy has the details.

Troubleshooting

“Showpiece can only use folders you’ve allowed”

The command line tried to read or write outside the folders in Settings › Folder Access. Add a folder that contains the path it names (usually your app’s repository) and run the command again.

“Exporting needs Showpiece Pro”

The command line hasn’t seen a purchase on this Mac. Open Showpiece and choose Showpiece › Showpiece Pro… to buy or restore it. A subscription that renewed while the app was closed is picked up the next time Showpiece opens.

“No iPhone screenshot on slide 2”

That slide has no screenshot for the device family being exported. Add one, or hide the device on that slide if it’s meant to be text only.

An agent’s changes don’t appear

Check that the agent is updating the same .showpiece file you have open. If the window still shows the old version, close the project and open it again.