Showpiece help

Your screenshots in device frames, with captions, in every size and language the App Store asks for.

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 every slide appears on every device. Turn off Show on Apple Watch (or iPad, and so on) at the top of the inspector to leave a slide out of that device's screenshots, so a watch can have fewer slides, or slides of its own with shorter captions. The size you're viewing decides which device the switch is for; slides left out are dimmed. Each device's screenshots are numbered on their own when exported.

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. Project Settings sets each kind of phone and tablet upright or on its side.

Presets with an angled device (Tilted, Perspective and Lemonade) fan it across the set: leaning right, upright, then leaning left, in threes, so the first three slides lean in toward the middle one. Across Slides, in the inspector's Placement section, chooses Fan, Pendulum (leaning, upright, the other way, upright) or the same angle on every slide, for a preset's angle or one of your own. Giving an upright slide an angle of its own takes it out of the pattern.

iPhone Duo

Add the iPhone Duo's outer and inner displays in Project Settings. Each has its own screenshots and layout, because your app shows different screens folded and open, and both displays are much squarer than other iPhones. The open display is often shown on its side, so set its orientation to Landscape while your iPhones stay upright. Uploading sends each display's screenshots to its own place on your App Store listing.

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.

Creative assets

On iOS and iPadOS 27 and later, the App Store can show a wide image across the top of your product page and another in place of your screenshots in search results. Add them with the + menu under the slide list, in Creative Assets for iOS 27. They sit in their own section below your screenshots and are designed the same way, with text, a device, a background and layers.

• Product Page Header: 21:9, across the top of your product page.
• Search Results: 3:2, in place of screenshots in search results.
• Universal: 16:9, which App Store Connect crops to serve as both. The canvas shows where each crop falls, so keep your text and device inside both.
• Event Card and Event Details: 16:9 and 9:16 images for an in-app event.

A new creative asset starts with your first slide's design and captions, with the text beside the device on wide ones. The Device picker in the inspector chooses which device it shows; each has a screenshot of its 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.

Turn on Include Creative Assets to save them as well, as PNGs at Apple's largest sizes, in a Creative Assets/<language> folder next to the screenshots.

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. Each project remembers the app it was uploaded to, and where in it (the product page, a custom product page or a product page optimization treatment), and a new project starts on the app you uploaded to last.

Upload To chooses where the screenshots go:

• Product Page: an app version that's still being prepared, or was rejected.
• Custom Product Page: the version of a custom product page that's being prepared. App Store Connect decides which devices a custom product page takes; Showpiece says if any of your sizes aren't among them.
• Product Page Optimization: one treatment of a product page optimization that's still being prepared. Each is for one platform, so only that platform's screenshots go. The treatment is given each of your languages that the product page has.

Create the page, optimization or treatment in App Store Connect first.

You can choose to replace the screenshots already there for the sizes and languages you send. Other sizes and languages are left alone. Screenshots go into your app's asset library in App Store Connect; when they're replaced, the ones Showpiece uploaded are deleted from it, and any others stay there.

Only what's changed is sent. A screenshot that's already showing stays where it is, and one already in your asset library, from an earlier upload, another page or another language, is reused rather than sent again.

If your app has an iMessage extension, turn on Also Use for iMessage to put your iPhone and iPad screenshots on its iMessage App Store listing too. They're the same images, so they're only uploaded once. Showpiece remembers the choice for each app.

With Include Creative Assets on, the header and search results images go up too, if the page takes them. Each place holds one image, so they always replace what's there. If the project has event artwork, choose the in-app event it goes on; it's placed in each language the event has.

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. Showpiece --help gives the full list.

For product page optimization or a custom product page, ask your agent for a variant: an alternative set that names only what differs, such as another preset, a new first caption or a different order. Each variant gets a project of its own beside yours, and compare draws the first slides of every set side by side. Open a variant's project and upload it to its treatment or page.

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.

Contact

For questions or problems, email hello@showpiecestudio.app.