Studio Reference
Everything the editor does is also available from the appshot CLI, the MCP connector and the HTTP API. All three talk to the studio inside OpenConnect, using an API token.
CLI
Run appshot help for the built-in summary. Without npm run install:claude, run it as node studio/bin/appshot.mjs from your OpenConnect clone, or npm run appshot -- from its studio folder.
Arguments used throughout:
<app>: an app ID, its exact name, its bundle ID, or.for the app linked to the current folder.<slide>: a slide ID or its position, starting at 1.--in "<set>"on any command works on that screenshot set (ID or name) instead of the primary one.--lang <code>on any command works on that translation (for examplede-DE).--jsonon any command prints JSON instead of a summary.- In headlines,
*asterisks*highlight words and\nis a line break.
Apps
| Command | What it does |
|---|---|
status [app] | Lists apps, or shows one app's profile, style, slides and guideline issues. |
here | Shows the app linked to the current folder. |
create <name> [--preset p] [--subtitle s] [--icon file] [--devices iphone,duo,ipad,mac] [--project dir] | Creates an app. Presets: neutral, zinc, blue, green, rose, orange, violet, yellow, forest. |
profile <app> [--project dir] [--bundle-id id] [--app-store-url u] [--category c] [--description s] [--audience s] [--keywords a,b] [--brand-colors #hex,#hex] [--screens s] [--notes s] [--add-note s] | Shows or updates what's remembered about the app. --add-note appends a dated note. |
icon <app> <file> | Sets the app icon. |
data [app] | A clean JSON record of one app, or all apps. |
spec <app> | The raw app document as JSON. |
delete-app <app> | Deletes an app. |
Style
update <app> changes the app-wide style. Every flag is optional:
| Flags | What they set |
|---|---|
--preset p | A theme (colors and type). |
--layout top|bottom|side, --align left|center, --alternate on|off | Layout, alignment, alternating colors. |
--font f, --size n | Typeface and headline size. |
--scale 1.0, --offset 0, --text-offset 0 | Screenshot size, screenshot position and headline position (positive moves down). |
--frame outline|device, --device-color c | Outline or drawn device frame. |
--stroke-color c, --stroke-width n, --radius pct, --shadow 0-1 | The outline frame. |
--callout-scale 1.12, --callout-shadow 0-1, --callout-radius n | How callouts look. |
--badge none|rating|downloads|custom, --badge-title s, --badge-caption s, --lockup on|off, --tilt -6 | The hero design. |
--background solid|gradient|glow|mesh|photo|frosted, --mesh-colors base,blob,blob2, --shuffle | The main background fill. |
--panorama on|off, --texture none|grain|dots|grid|lines, --texture-strength 0.15, --texture-spacing 28, --vignette 0-1 | Background effects. |
--glow 0-1, --glow-size 1.2, --glow-color c|highlight | Glow behind the screenshot. |
--decor none|blobs|waves|rings|sparkles|confetti|bokeh, --decor-amount 1, --decor-size 1, --decor-opacity 0.5, --decor-color c|auto, --shuffle-decor | Decorations. |
--mark none|underline|double|circle|box|marker|strike|brackets|squiggle, --mark-width 6, --mark-roughness 1.4, --mark-padding 14, --mark-color c|highlight, --mark-recolor on|off | Headline marks. |
--marker-opacity 0-100, --marker-height 0.1-1.2, --marker-position -0.3-0.6, --marker-round 0-1, --marker-tilt -6-6 | The highlighter mark. |
--sticker-shadow 0-1 | Shadow under stickers. |
--name s, --subtitle s, --devices list | App name, subtitle and devices. |
--set path.to.key=value | Any other setting, for example --set theme.palettes.primary.accentColor=#F2DE8C. Repeatable. |
Screenshots
| Command | What it does |
|---|---|
add <app> <files...> [--device d] [--headlines "One|Two"] [--screens "Today|Stats"] | Fills slides missing a screenshot for that device, then adds new slides. |
capture <app> [--slide n] [--device d] [--udid id] [--clean-status-bar] [--headline s] [--screen name] | Captures the booted iOS Simulator into the app. |
capture <app> --mac "App Name" [--slide n] [--headline s] | Captures a running Mac app's window, without its shadow. |
shot <app> <slide> <file> [--device d] | Replaces one slide's screenshot. |
Slides
| Command | What it does |
|---|---|
slide <app> <slide> [--headline s] [--subtitle s] [--screen "Stats tab"] [--screen-notes s] [--hero on|off] [--callout x,y,w,h|off [--device d]] [--style path=value ...] [--reset-style [path]] | Edits a slide. --callout takes pixels of that screenshot or 0–1 fractions. --style overrides the app style on this slide only; --reset-style removes one override or all. |
new-slide <app> [--at n] [same flags as slide] | Adds a slide. |
rm-slide <app> <slide> | Deletes a slide. |
move <app> <slide> <position> | Moves a slide. |
apply <spec.json> [--app <app>] | Creates or updates an app from a JSON spec. See Building a Whole Set From a Spec. |
Screenshot Sets
| Command | What it does |
|---|---|
sets <app> | Lists sets. |
set-new <app> [name] [--from set] [--blank] | Copies a set (the primary by default) into a new one, or starts blank. |
set-rename <app> <set> <name> | Renames a set. |
set-rm <app> <set> | Deletes a set (not the primary). |
set-primary <app> <set> | Makes a set the primary one. The old primary becomes a set. |
Stickers
| Command | What it does |
|---|---|
emoji <words> | Finds emoji slugs, for example appshot emoji rocket. |
sticker <app> <slide> list | Lists a slide's stickers. |
sticker <app> <slide> add <emoji-slug|doodle> [--doodle] [--style 3d|color|flat|apple] [--x 0.8] [--y 0.2] [--size 200] [--rotate -8] [--layer front|back] [--color c] [--opacity 1] [--flip] | Adds a sticker. x and y are the center as fractions of the slide; size is in thousandths of the slide's short side. |
sticker <app> <slide> set <n> [same flags] | Changes a sticker. |
sticker <app> <slide> rm <n|all> | Removes one sticker or all. |
Doodles: arrow-curve, arrow-down, arrow-loop, arrow-straight, underline, squiggle, circle, star, star-filled, sparkle, burst, heart, heart-filled, spiral, check, cross, exclaim, lightning, crown, scribble, bracket.
Languages
| Command | What it does |
|---|---|
languages <app> [--add de-DE,ja] [--rm fr-FR] [--base en-US] | Shows or changes the app's languages. |
translations <app> [lang] | Base text next to each translation, and what's missing. |
translate <app> <lang> <file.json> | Sets many translations at once (- reads standard input). |
Product Page
| Command | What it does |
|---|---|
creative <app> header|search [--headline s] [--subtitle s] [--text left|center|none] [--lockup on|off] [--shots 1,2,3|1:ipad,2|auto] [--shot-scale 1.2] [--include on|off] | Edits the product page header or the search results asset. |
Output
| Command | What it does |
|---|---|
preview <app> [--device d] [--slide n] | Renders PNGs to disk and prints their paths. |
preview <app> --creative header|search | Renders a product page asset. |
export <app> [--device iphone,ipad] [--lang de-DE,ja] [--out dir] | Renders every chosen export size, in every language unless --lang picks some. |
open <app> | Opens the app in the editor. |
MCP Tools
The openappshot MCP connector (npm run install:desktop, see Use It From Claude on Your Mac) gives the Claude desktop app these tools. Most take an app, and the slide, style, product page, preview and export tools also take set and lang.
| Tool | What it does |
|---|---|
list_apps | Every app with per-device screenshot counts and its style. |
get_app | One app's full record: profile, style, devices and every slide. |
find_app_for_folder | The app linked to a folder, such as your Xcode project. |
create_app | Creates an app, with optional preset, devices, project folder, bundle ID and icon. |
update_app | Changes the app (name, subtitle, icon, devices, export sizes) or its style. |
update_profile | Saves what Claude learns about the app. |
add_screenshots | Adds image files from your Mac. |
capture_simulator | Captures the booted iOS Simulator into a new slide or an existing one. |
set_screenshot | Replaces one slide's screenshot for a device. |
update_slide | Edits a slide's words, screen info or hero role, or its own style overrides. |
add_slide, delete_slide, move_slide | Adds, deletes or moves a slide. |
set_callout | Sets or clears a slide's callout for a device. |
manage_sets | Lists, creates, renames, deletes or promotes screenshot sets. |
search_emoji | Finds emoji for stickers. |
stickers | Lists, adds, updates or removes a slide's stickers. |
update_creative | Edits the product page header or search results asset. |
preview_creative | Returns a product page asset as an image. |
preview_slide | Returns a slide as an image (30% scale by default). |
languages | Shows or changes the app's languages. |
translate | Reads or writes the translations for one language. |
export | Exports PNGs and a zip. |
open_editor | Opens the app in the editor. |
HTTP API
The API is at <OpenConnect>/studio/api, and the paths below are relative to <OpenConnect>/studio. Send an API token as Authorization: Bearer oc_…, or use it from a browser that's signed in. GET /studio/api lists every endpoint with a short description. Routes that work on slides, style or creatives take ?set= and ?lang=.
| Method | Path | What it does |
|---|---|---|
GET | /api/health | Server status and data folder. |
GET | /api/data | Every app as a clean record. |
GET | /api/apps/:app/data | One app as a clean record (:app is an ID, name or bundle ID). |
GET | /api/apps | Short app list. |
GET | /api/apps/:app | The raw app document. |
GET | /api/lookup?path= | The app linked to a source folder. |
POST | /api/apps | Creates an app: {name, preset, subtitle, devices, profile}. |
PATCH | /api/apps/:app | Deep-merges {name, profile, theme, devices, sizes, exportSizes, preset}. |
DELETE | /api/apps/:app | Deletes an app. |
POST | /api/apps/:app/apply | Applies a bulk spec. |
POST | /api/apps/:app/icon | Sets the icon (multipart file). |
POST | /api/apps/:app/screenshots | Adds screenshots (multipart files[], plus optional device, headlines, screens, source). |
POST | /api/apps/:app/slides | Adds a slide: {headline, subtitle, screen, index?}. |
PATCH | /api/apps/:app/slides/:slide | Updates a slide. |
DELETE | /api/apps/:app/slides/:slide | Deletes a slide. |
PUT | /api/apps/:app/slides/:slide/shot | Replaces a screenshot (multipart file and device). |
PUT | /api/apps/:app/order | Reorders slides: {order: [slideId]}. |
GET | /api/apps/:app/check | Guideline issues. |
GET | /api/apps/:app/slides/:slide/render/:device.png?scale= | A PNG of one slide. |
GET | /api/apps/:app/creatives/:creative/render.png?scale= | A PNG of header or search. |
POST | /api/apps/:app/preview | Renders previews to disk: {device?, slides?, scale?}. |
POST | /api/apps/:app/export | Exports PNGs and a zip: {devices?, sizes?, outDir?, creatives?, languages?}. |
GET | /api/emoji?q=&group=&limit= | Searches sticker emoji. |
GET | /api/apps/:app/sets | Lists sets. |
POST | /api/apps/:app/sets | Creates a set: {name?, from?, blank?}. |
PATCH | /api/apps/:app/sets/:set | Renames a set: {name}. |
DELETE | /api/apps/:app/sets/:set | Deletes a set (not the primary). |
POST | /api/apps/:app/sets/:set/primary | Makes a set the primary one. |
GET | /api/apps/:app/translations?lang= | Base text and translations, with what's missing. |
PUT | /api/apps/:app/translations/:lang | Sets many translations at once. |
GET | /api/events | Server-sent events whenever an app changes. |