Documentation
CLI reference
Every vitrine command and option: new, validate, render, export, strings, import, frames, fonts, template, gallery, upload, mcp, install-cli.
The vitrine command line tool works on the same project folders as the app –
for scripts, CI and quick checks. It ships with the app; see
Install to make it available in your
terminal.
Each section below has the command’s complete --help text (click to open);
it is generated from the tool itself (scripts/docs/cli-help.sh).
Global options and exit codes
| Option | Meaning |
|---|---|
--project <DIR> | the project folder (the one with project.yaml); default: the current folder |
-q, --quiet | print only results and errors |
-v, --verbose | print more details (every exported file, image sizes) |
-V, --version | print the version |
Exit codes: 0 ok · 1 the project has problems (validation errors,
failed exports, blocked upload plan) · 2 the command could not run (wrong
arguments, project not found). Output is coloured on a terminal unless
NO_COLOR is set.
vitrine --help
Vitrine Studio command line interface
Usage: vitrine [OPTIONS] <COMMAND>
Commands:
new Create a new project folder from a template
render Render a preview PNG of a page, output image, canvas or store gallery
export Export pages, banners and gallery previews for targets and languages
validate Validate a project and report infos, warnings and errors
strings Exchange translations with translators (CSV, XLIFF)
import Import files into the project (`screenshots <dir>`: fastlane, Vitrine Studio or flat folders)
frames Import, list and remove device frames (Apple Product Bezels, own frame packs)
fonts List the font families text styles can use (bundled, project, system); store used system fonts in the project (`fonts embed`)
mcp Run the MCP server over stdio (for Claude Code / Claude Desktop)
upload Upload to App Store Connect / Google Play: `plan` (dry run + confirm token), `execute --confirm <token>`, `log`
template Templates: save canvases as a template, list, import, export, remove, insert into the project, new project from a template
gallery Template gallery (api.vitrinestudio.app): login with GitHub, logout, list, upload, download
install-cli Make `vitrine` available in terminals (macOS: symlink in /usr/local/bin; Windows: user PATH; Linux: ~/.local/bin)
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
-V, --version Print versionnew – create a project
vitrine new my-app # Phone template, English
vitrine new my-app --template minimal --lang en --lang de --lang fr
vitrine new my-app --template ./bold.vitrine-template --name "My App"
The folder must not exist or be empty. The first --lang is the default
language.
vitrine new --help
Create a new project folder from a template
Usage: vitrine new [OPTIONS] <DIR>
Arguments:
<DIR> Folder to create (must not exist or be empty)
Options:
--name <NAME> Project name (default: the folder name)
--template <NAME|FILE> Template: built in (`phone`, `minimal`), the id of an installed template (`vitrine template list`) or a `.vitrine-template` file [default: phone]
--lang <LANG> Project language; repeat for more. The first is the default language (fallback for texts and screenshots). Default: `en`
-h, --help Print helpvalidate – check a project
vitrine validate # every target × language
vitrine validate --target play-phone --lang de
vitrine validate --preview # missing screenshots are warnings
vitrine validate --strict # fail on warnings too (CI)
vitrine validate --format json
vitrine validate --format github # GitHub Actions annotations
vitrine validate --format junit -o validate.xml # report to a file, text to the log
Findings are listed per target and language as error, warn or info with a
code (see Troubleshooting). The CI
formats github, gitlab (Code Quality) and junit are described in
Automation.
vitrine validate --help
Validate a project and report infos, warnings and errors
Usage: vitrine validate [OPTIONS]
Options:
--target <ID>
Only this target; repeat for more (default: all targets)
--lang <LANG>
Only this language; repeat for more (default: each target's languages)
--format <FORMAT>
Output format (`github`, `gitlab`, `junit`: CI reports)
Possible values:
- text: Grouped by target and language
- json: The report with counts
- github: GitHub Actions annotations (workflow commands) plus the text report
- gitlab: GitLab Code Quality report (JSON)
- junit: `JUnit` XML (GitLab, Jenkins, Azure Pipelines, `CircleCI`, Bitrise)
[default: text]
-o, --output <FILE>
Write the `--format` report to this file and print the text report (e.g. `--format junit -o validate.xml`)
--preview
Validate for previewing: missing screenshots are warnings, not errors
--strict
Fail (exit code 1) on warnings too
--no-pixel-checks
Skip the rendered design checks (contrast, text near devices, screens, seams, corners, store background): faster, layout only
-h, --help
Print help (see a summary with '-h')render – a single preview PNG
vitrine render --target ios-iphone-69 --page 3 --width 600 -o page3.png
vitrine render --canvas --lang de # the whole canvas with hatched gaps
vitrine render --gallery --max-edge 800 # the store gallery, 800 px high
Prints the path of the written file. With --gallery, --max-edge is the
image height.
vitrine render --help
Render a preview PNG of a page, output image, canvas or store gallery
Usage: vitrine render [OPTIONS]
Options:
--target <TARGET> Target id (default: the first target of the project)
--lang <LANG> Language (default: the project's default language)
--page <N> The output image containing page N (1-based, as in export file names)
--image <N> Output image N (1-based: a page, a page group or the banner)
--canvas The whole canvas with page boundaries and hatched gaps
--gallery The store gallery preview (images side by side with the store gaps)
--width <PX> Width in px (images, canvas)
--max-edge <PX> Longer side in px (images, canvas); image height for the gallery
--scale <F> Factor of the target size (images, gallery) or px per lu (canvas)
-o, --output <FILE> Output PNG (default: `<project>/.cache/render/<target>_<lang>_<what>.png`)
-h, --help Print helpexport – write the images
vitrine export
vitrine export --target ios-iphone-69 --target play-phone --lang en
vitrine export --out dist/ --force
vitrine export --layout fastlane --out fastlane
See Export.
vitrine export --help
Export pages, banners and gallery previews for targets and languages
Usage: vitrine export [OPTIONS]
Options:
--target <ID> Only this target; repeat for more (default: all targets)
--lang <LANG> Only this language; repeat for more (default: each target's languages)
--out <DIR> Export folder (default: `<project>/export`, with `--layout fastlane` `<project>/export/fastlane`)
--layout <LAYOUT> Folder structure: `standard` (`<target>/<lang>/…`) or `fastlane` (`screenshots/<locale>/…` for deliver, `metadata/android/<locale>/ images/<type>/…` for supply; no gallery previews) [default: standard]
--no-html Do not write the `index.html` overview of the exported files
--no-gallery Do not write `_gallery.png` store gallery previews
--gallery-only Write only the `_gallery.png` previews (no page images; files of earlier exports are kept). Standard layout only
--force Render every file, ignoring the incremental export cache
--remove-foreign fastlane layout: delete the images in the deliver/supply folders written to that Vitrine Studio did not export (raw snapshot/ screengrab captures, frameit output), so deliver/supply upload only Vitrine Studio's images. Without it they are listed as warnings
--format <FORMAT> Output format (`json`: the full export report) [default: text] [possible values: text, json]
-h, --help Print helpstrings – translation exchange
vitrine strings export --format csv --delimiter semicolon --bom -o texts.csv
vitrine strings export --format xliff20 --missing-only --context -o xliff/
vitrine strings import xliff/*.xlf --dry-run
vitrine strings import texts.csv --create-keys --empty remove
vitrine strings export --helpExport translations for translators (CSV, XLIFF 1.2 or 2.0)
Usage: vitrine strings export [OPTIONS]
Options:
--format <FORMAT> File format [default: xliff20] [possible values: csv, xliff12, xliff20]
--lang <LANG> Target language; repeat for more (default: all but the default language)
-o, --out <PATH> Output file or folder (default: the current folder). XLIFF writes one file per language; with a file name `x.xlf` and several languages they become `x-<lang>.xlf`
--missing-only Only keys missing in a target language
--context Add context for translators (elements, pages, approximate max length)
--delimiter <DELIMITER> CSV delimiter (`semicolon` for Excel in locales with a decimal comma) [default: comma] [possible values: comma, semicolon, tab]
--bom CSV: write a UTF-8 byte order mark (Excel)
--plain-markup XLIFF: keep Vitrine Studio markup (`**bold**`, `[accent]…[/]`) as text instead of inline elements
--json Print the written files as JSON
-h, --help Print helpvitrine strings import --helpImport translated CSV/XLIFF files (prints a report; see --dry-run)
Usage: vitrine strings import [OPTIONS] <FILE>...
Arguments:
<FILE>...
CSV or XLIFF files (format from the extension or content)
Options:
--dry-run
Only print the report; change nothing
--create-keys
Create keys that are not in the project (else they are reported)
--empty <EMPTY>
Meaning of empty CSV cells
Possible values:
- keep: Empty cells change nothing
- remove: Empty cells remove the translation (fallback again)
[default: keep]
--no-layout-check
Skip the layout check (overflow, emergency breaks) after the import
--json
Print the report as JSON
-h, --help
Print help (see a summary with '-h')
import screenshots
vitrine import screenshots fastlane/ --dry-run
vitrine import screenshots shots/ --format flat --lang-map en-US=en --device-map "Pixel 9=android-phone"
See Screenshots.
vitrine import screenshots --help
Copy screenshots from a folder into `screenshots/<lang>/<variant>/<key>.png`
Usage: vitrine import screenshots [OPTIONS] <DIR>
Arguments:
<DIR> Source folder (fastlane `screenshots/`, a Vitrine Studio `screenshots/` tree or a folder of files)
Options:
--format <FORMAT> Source layout [default: auto] [possible values: auto, vitrine, fastlane, flat]
--lang-map <LOCALE=LANG> Locale → language, e.g. `de-DE=de`; repeat for more
--device-map <DEVICE=VARIANT> Device name → screenshot variant, e.g. `iPhone 16 Pro Max=ios-phone`
--key-map <SCREEN=KEY> Screen name → screenshot key, e.g. `01_home=home`
--include-framed Import frameit's `*_framed.png` instead of skipping them
--dry-run Only print the plan; copy nothing
--save-mapping Store the effective device/locale/key mapping in `project.yaml` (`import.fastlane`), so later imports map the same way
--format-output <OUTPUT> Output format (`json`: plan and apply report) [default: text] [possible values: text, json]
-h, --help Print helpframes – device frames
vitrine frames import /Volumes/Bezel-iPhone-18 # Apple bezels (folder, .zip, mounted .dmg)
vitrine frames import my-pack.zip --to project # own frame pack
vitrine frames list # installed Apple frames
vitrine frames list --packs # frame packs
vitrine frames remove --model iphone-island --color silver
vitrine frames remove --pack my-pack --from project
vitrine frames embed # store the used Apple bezels in the project (CI)
vitrine frames unembed # remove them again
See Devices & frames and, for embed,
Apple bezels in CI (private
repositories only).
vitrine frames import --helpImport a downloaded frame package (folder, .zip or, on macOS, .dmg) or an own frame pack (folder or .zip with `frame.yaml`)
Usage: vitrine frames import [OPTIONS] <PATH>
Arguments:
<PATH> The package: extracted folder, .zip or .dmg
Options:
--dry-run Only show what would be imported
--source <SOURCE> Frame source (rules in `crates/core/data/frame-import/<source>.yaml`) [default: apple]
--to <TO> Own frame packs (a folder or .zip with `frame.yaml`, ADR 0024): where to put it, `app` (this computer) or `project` (the project's `frames/` folder, travels with it) [default: app] [possible values: app, project]
--id <ID> Own frame packs: the pack id (default: from its name)
--format <FORMAT> [default: text] [possible values: text, json]
-h, --help Print helpvitrine frames list --helpList the installed frames
Usage: vitrine frames list [OPTIONS]
Options:
--source <SOURCE> [default: apple]
--packs List own frame packs (app-wide and the project's) instead
--format <FORMAT> [default: text] [possible values: text, json]
-h, --help Print helpvitrine frames remove --helpRemove installed frames
Usage: vitrine frames remove [OPTIONS]
Options:
--source <SOURCE> [default: apple]
--model <MODEL> Only this model
--color <COLOR> Only this colour id
--orientation <ORIENTATION> Only this orientation (`portrait`, `landscape`)
--bezel <BEZEL> Only this vendor model (`"iPhone 18 Pro"` or `iphone-18-pro`)
--all Required to remove everything of the source (no filter given)
--pack <ID> Remove the own frame pack with this id instead (see `--from`)
--from <FROM> With `--pack`: `app` or `project` [default: app] [possible values: app, project]
-h, --help Print helpvitrine frames embed --helpStore the imported frames the project uses in the project (`frames/imported/`), or update the stored copies, so that a build server (CI) without the app-wide frames renders the same images. Licence: keep such a project private
Usage: vitrine frames embed [OPTIONS]
Options:
--all-sizes Store every installed size (vendor model, e.g. iPhone 18 Pro and Pro Max) of the used models, colours and orientations, not only the bezels the targets draw (remembered for later updates)
--used-only Store only the bezels the targets draw (switches `--all-sizes` off)
--dry-run Only show what would be stored, updated or removed
--format <FORMAT> [default: text] [possible values: text, json]
-h, --help Print helpvitrine frames unembed --helpRemove the frames stored in the project (`frames/imported/`)
Usage: vitrine frames unembed [OPTIONS]
Options:
--dry-run Only show what would be removed
-h, --help Print help
fonts
Lists the font families text styles can use: the bundled ones and those in the
project’s fonts/ folder.
vitrine fonts --help
List the font families text styles can use (bundled, project, system); store used system fonts in the project (`fonts embed`)
Usage: vitrine fonts [OPTIONS] [COMMAND]
Commands:
embed Store the system fonts the project uses in `fonts/system/` (so a build server renders the same). Check the licences: most system fonts may not be redistributed – private repositories only
unembed Remove the system fonts stored in the project
help Print this message or the help of the given subcommand(s)
Options:
--format <FORMAT> [default: text] [possible values: text, json]
--installed Also list every font family installed on this computer
-h, --help Print helptemplate – templates
vitrine template list
vitrine template save --name "Bold gradient" --style bold --color dark -o bold.vitrine-template
vitrine template insert bold-gradient --dry-run
vitrine template import bold.vitrine-template --replace
vitrine template export bold-gradient -o bold.vitrine-template
vitrine template remove bold-gradient
vitrine template new my-app --template bold-gradient # same as vitrine new
See Templates & gallery.
vitrine template save --helpSave canvases of the project (default: all) as a template in the store
Usage: vitrine template save [OPTIONS] --name <NAME>
Options:
--name <NAME> Template name
--id <ID> Template id (default: derived from the name)
--description <DESCRIPTION> [default: ""]
--author <AUTHOR> [default: ""]
--style <STYLE> Style tag (1–2 for the gallery; `vitrine template tags`); repeat or separate with commas [possible values: minimal, bold, playful, elegant, realistic, illustrated, editorial, retro, futuristic, organic]
--color <COLOR> Colour tag (1–2 for the gallery) [possible values: light, dark, colorful, pastel, monochrome, gradient, neon, earthy]
--use <USE> App category tag (1–3 for the gallery) [possible values: games, productivity, business, finance, health-fitness, sports, education, kids, food-drink, travel, navigation, social, lifestyle, shopping, entertainment, music, photo-video, news, weather, utilities, developer-tools, medical, home-garden, books, events]
--sample-screenshots Pack the project's screenshots used by the canvases as sample screenshots (your own app screenshots, published as CC0 when uploaded), re-encoded as JPEG quality 60 to keep the package small (PNGs with transparency stay PNG); keys without a screenshot get placeholders
--skip-unlicensed-fonts Leave out project fonts whose licence does not allow sharing (not OFL) instead of refusing; the template lists them as required, not included (used where installed, else Inter)
--version <VERSION> Template version (default 1.0.0)
--canvas <ID> Canvas to save; repeat for more (default: all)
--replace Replace an installed template with the same id
-o, --output <FILE> Also write the package to this file
-h, --help Print helpvitrine template insert --helpInsert canvases of a template into the project (one step; ids, styles and texts that collide are renamed)
Usage: vitrine template insert [OPTIONS] <TEMPLATE>
Arguments:
<TEMPLATE>
Template id or `.vitrine-template` file
Options:
--canvas <ID>
Canvas of the template; repeat for more (default: all)
--styles <STYLES>
Possible values:
- rename: Keep both: the template's style is renamed (`accent-2`)
- use-project: The inserted canvases use the project's style
[default: rename]
--dry-run
Only show what would happen
--format <FORMAT>
[default: text]
[possible values: text, json]
-h, --help
Print help (see a summary with '-h')vitrine template list --helpList built-in and installed templates
Usage: vitrine template list [OPTIONS]
Options:
--format <FORMAT> [default: text] [possible values: text, json]
-h, --help Print helpvitrine template import --helpInstall a `.vitrine-template` file into the store (checked first)
Usage: vitrine template import [OPTIONS] <PATH>
Arguments:
<PATH> `.vitrine-template` file (or an extracted template folder)
Options:
--replace Replace an installed template with the same id
-h, --help Print helpvitrine template export --helpWrite a template as a `.vitrine-template` file (to share or upload)
Usage: vitrine template export [OPTIONS] --output <FILE> <ID>
Arguments:
<ID> Template id (installed or built in)
Options:
-o, --output <FILE> Output file (`.vitrine-template` is appended when missing)
-h, --help Print helpvitrine template remove --helpRemove an installed template
Usage: vitrine template remove [OPTIONS] <ID>
Arguments:
<ID>
Options:
-h, --help Print help
gallery – the template gallery
vitrine gallery list --tag dark
vitrine gallery download bold-gradient -o bold.vitrine-template
vitrine gallery login
vitrine gallery upload bold.vitrine-template
vitrine gallery logout
vitrine gallery list --helpList approved gallery templates (no login needed)
Usage: vitrine gallery list [OPTIONS]
Options:
--api <URL> API base URL (https, or http on 127.0.0.1/localhost). Default: `https://api.vitrinestudio.app` (`VITRINE_API_URL` overrides it with a loopback URL, for tests)
--query <QUERY> Search in name, description and tags
--tag <TAG> Any tag (facet value or device)
--style <STYLE> Style filter; repeat or separate with commas (any of them)
--color <COLOR> Colour filter
--use <USE> App category filter
--devices <DEVICES> Device filter (phone, tablet, watch, mac, web, tv, banner)
--limit <LIMIT> 1–100 [default: 50]
--offset <OFFSET> [default: 0]
--format <FORMAT> [default: text] [possible values: text, json]
-h, --help Print helpvitrine gallery download --helpDownload a template file (no login needed; checked after download)
Usage: vitrine gallery download [OPTIONS] <ID>
Arguments:
<ID> Template id
Options:
--api <URL> API base URL (https, or http on 127.0.0.1/localhost). Default: `https://api.vitrinestudio.app` (`VITRINE_API_URL` overrides it with a loopback URL, for tests)
-o, --output <FILE> Output file (default: `<id>.vitrine-template` in the current folder)
-h, --help Print helpvitrine gallery login --helpSign in with GitHub (device flow): shows a code to enter on github.com, then keeps the session in the system keychain
Usage: vitrine gallery login [OPTIONS]
Options:
--api <URL> API base URL (https, or http on 127.0.0.1/localhost). Default: `https://api.vitrinestudio.app` (`VITRINE_API_URL` overrides it with a loopback URL, for tests)
-h, --help Print helpvitrine gallery upload --helpUpload `.vitrine-template` files (checked locally first; the server checks them again and queues them for moderation). Continues after a failed file and ends with a summary
Usage: vitrine gallery upload [OPTIONS] <FILE>...
Arguments:
<FILE>... The `.vitrine-template` files (e.g. from `vitrine template export`)
Options:
--api <URL> API base URL (https, or http on 127.0.0.1/localhost). Default: `https://api.vitrinestudio.app` (`VITRINE_API_URL` overrides it with a loopback URL, for tests)
--dry-run Run every local check (package, tags, sample screenshots) and print the summary; send nothing (no login needed)
--confirm-own-screenshots Confirm that the sample screenshots in the templates are your own and published as CC0 (required for templates with samples)
--token-env <VAR> Read a static upload token from this environment variable instead of using the `vitrine gallery login` session
--format <FORMAT> [default: text] [possible values: text, json]
-h, --help Print helpvitrine gallery logout --helpRevoke the session on the server and remove it from the keychain
Usage: vitrine gallery logout [OPTIONS]
Options:
--api <URL> API base URL (https, or http on 127.0.0.1/localhost). Default: `https://api.vitrinestudio.app` (`VITRINE_API_URL` overrides it with a loopback URL, for tests)
-h, --help Print help
upload – store upload
vitrine upload plan --remote
vitrine upload execute --confirm <token> --yes
vitrine upload log --last --events
vitrine upload refdata # App Store asset types, read-only
See Store upload. In CI the keys come from environment variables instead of the keychain – see Automation.
vitrine upload plan --helpDry run: what would be uploaded, problems, and the confirm token
Usage: vitrine upload plan [OPTIONS]
Options:
--app-dir <DIR> App data folder (settings with the store accounts). Default: `$VITRINE_APP_DIR` or the platform folder
--store <STORE> Only this store (default: every store the project is mapped to) [possible values: apple, google]
--target <ID> Only this target; repeat for more
--lang <LANG> Only this language; repeat for more
--remote Also read the store state (network; uses the account's key)
--force Upload sets even when they look unchanged
--format <FORMAT> [default: text] [possible values: text, json]
-h, --help Print helpvitrine upload execute --helpUpload a plan: needs its confirm token (same project state, 30 min)
Usage: vitrine upload execute [OPTIONS] --confirm <TOKEN>
Options:
--app-dir <DIR> App data folder (settings with the store accounts). Default: `$VITRINE_APP_DIR` or the platform folder
--confirm <TOKEN> The `confirm_token` printed by `upload plan`
--yes Do not ask before uploading
--changes-not-sent-for-review Google: commit with "changes not sent for review"
--format <FORMAT> [default: text] [possible values: text, json]
-h, --help Print helpvitrine upload log --helpPast uploads from `<project>/.cache/uploads.sqlite`
Usage: vitrine upload log [OPTIONS]
Options:
--app-dir <DIR> App data folder (settings with the store accounts). Default: `$VITRINE_APP_DIR` or the platform folder
--last Only the last run
--limit <N> Number of runs (default 10)
--events Include the HTTP events (method, path, status)
--format <FORMAT> [default: text] [possible values: text, json]
-h, --help Print helpvitrine upload refdata --helpApp Store Connect asset types (read-only): the App Asset Library reference data – placement types, groups, display classes, image specs – and how Vitrine Studio's slots resolve against it (ADR 0019)
Usage: vitrine upload refdata [OPTIONS]
Options:
--account <ID> Apple account id (default: the project's, else the only one)
--app-dir <DIR> App data folder (settings with the store accounts). Default: `$VITRINE_APP_DIR` or the platform folder
--app <ID> App: numeric Apple ID or bundle id (default: the project's); also checks that the app can use the asset library
--format <FORMAT> [default: text] [possible values: text, json]
-h, --help Print help
mcp – MCP server over stdio
vitrine mcp # connect to the running app (start it if needed)
vitrine mcp --headless --project my-app # own session, no app
In this mode nothing but MCP messages is printed to stdout. See AI assistants.
vitrine mcp --help
Run the MCP server over stdio (for Claude Code / Claude Desktop)
Usage: vitrine mcp [OPTIONS]
Options:
--app-dir <DIR> App data folder (settings, recent projects, installed device frames). Default: `$VITRINE_APP_DIR` or the platform folder
--headless Work on the project folder directly with an own session, never through (or starting) the Vitrine Studio app. Default: connect to the running app, start it if needed, else headless
-h, --help Print helpinstall-cli
Makes vitrine available in every terminal (macOS: link in /usr/local/bin,
Windows: user PATH). The app’s Install command line tool… does the same.
vitrine install-cli --help
Make `vitrine` available in terminals (macOS: symlink in /usr/local/bin; Windows: user PATH; Linux: ~/.local/bin)
Usage: vitrine install-cli [OPTIONS]
Options:
--remove Remove the symlink / PATH entry instead
--status Only show the current state
-y, --yes Do not ask for confirmation
--format <FORMAT> Output format [default: text] [possible values: text, json]
-h, --help Print helpEnvironment variables
| Variable | Meaning |
|---|---|
VITRINE_APP_DIR | use this folder for the app data (settings, store accounts, frames, templates) instead of the platform folder |
NO_COLOR | no colours in the output |
VITRINE_KEYRING=mock | keep store keys in memory only (tests) – never touches the system keychain |
VITRINE_ASC_KEY_ID, VITRINE_ASC_ISSUER_ID, VITRINE_ASC_KEY / VITRINE_ASC_KEY_PATH | upload only: App Store Connect key from the environment (CI), instead of the project’s account – see Automation |
VITRINE_PLAY_SERVICE_ACCOUNT / VITRINE_PLAY_SERVICE_ACCOUNT_PATH | upload only: Google Play service account from the environment (CI) |