CLI

The commands, options and their wording are generated on each build from the built CLI’s --help; which command reads which option comes from src/cli.ts, and the build fails when the two disagree.

showcase <command> [options]

Run it with your package manager: npx showcase, pnpm exec showcase or bunx showcase. It needs Playwright with Chromium (npx playwright install chromium), or an installed browser set through browser.channel in the config.

Options

Option	Applies to	Meaning
-c, --config <file>	capture, frame, portfolio, hero, record, readme, all	Config file (default: showcase.config.{ts,mts,mjs,js} in the current directory or a parent, up to the project root)
--only <ids>	capture, frame, portfolio, record, readme, all	Comma-separated shot or clip ids
--langs <codes>	capture, frame, record, all	Comma-separated languages
--lang <code>	readme	Language for readme (default: the first in langs)
--layout <name>	readme	Layout for readme: table, rows, featured, details or list (default table)
--cols <n>	readme	Images per row for readme (default 2)
--base <dir>	readme	Directory the README is in, for relative image paths
--source <png>	icons	Square source image, 1024px or larger
--preset <name>	icons	web, electron or tauri
--out <dir>	icons	Output directory (default: icons)
--ts	init	Write showcase.config.ts instead
--tty	init	Start from a terminal app config
--force	init	Overwrite an existing config
--verbose	every command	Show the start command's output and debug detail
--quiet	every command	Only print warnings and errors
-h, --help	any command line: prints, then exits without running a command	Show this help
-v, --version	any command line: prints, then exits without running a command	Show the version

Config lookup. Without --config, the kit looks for showcase.config.ts, .mts, .mjs or .js (in that order) in the current directory, then in each parent, up to the project root: the first directory that has a package.json or a .git. A config above that belongs to another project and is not used. In a monorepo, run the command from the package that has the config, or pass --config. A --config path is relative to the current directory, and relative paths inside the config resolve against the config file’s directory.

Selecting. --only and --langs take comma-separated lists. A name the config does not know is an error rather than a silent no-op, so a typo does not capture nothing.

Exit codes. Every command exits with code 1 when it fails, and 0 otherwise. Errors the kit expects (a bad config, a missing file, a shot that timed out) print one message without a stack trace. A failed shot does not stop the others: the rest are still written, then the run fails with the list of what went wrong. Clips work the same way.

showcase, showcase help and showcase --help all print the help. An unknown command, or an extra argument after the command, is an error.

capture

Screenshot every shot in every language (raw PNGs). Reads the config file.

showcase capture [options]

Option	Meaning
-c, --config <file>	Config file (default: showcase.config.{ts,mts,mjs,js} in the current directory or a parent, up to the project root)
--only <ids>	Comma-separated shot or clip ids
--langs <codes>	Comma-separated languages
--verbose	Show the start command's output and debug detail
--quiet	Only print warnings and errors

Screenshots every shot in every language into outputs.raw, as PNG. In url mode it starts the app with target.start, unless target.reuseExisting is on (the default) and an app already answers on target.url; in cdp mode it attaches to the running app; in tty mode it runs target.command in a pseudo terminal.

frame

Turn raw captures into framed README images. Reads the config file.

showcase frame [options]

Option	Meaning
-c, --config <file>	Config file (default: showcase.config.{ts,mts,mjs,js} in the current directory or a parent, up to the project root)
--only <ids>	Comma-separated shot or clip ids
--langs <codes>	Comma-separated languages
--verbose	Show the start command's output and debug detail
--quiet	Only print warnings and errors

Frames the raw captures into outputs.readme (.webp or .png). With outputs.readme: false it does nothing.

portfolio

Export fixed-size portfolio images, thumbnail and gallery JSON. Reads the config file.

showcase portfolio [options]

Option	Meaning
-c, --config <file>	Config file (default: showcase.config.{ts,mts,mjs,js} in the current directory or a parent, up to the project root)
--only <ids>	Comma-separated shot or clip ids
--verbose	Show the start command's output and debug detail
--quiet	Only print warnings and errors

Exports outputs.portfolio: one image per shot, thumbnail.<format>, and the gallery JSON (unless gallery: false). It renders from the raw captures, so it works without the README images.

readme

Print an HTML table of the framed images for a README. Reads the config file.

showcase readme [options]

Option	Meaning
-c, --config <file>	Config file (default: showcase.config.{ts,mts,mjs,js} in the current directory or a parent, up to the project root)
--only <ids>	Comma-separated shot or clip ids
--lang <code>	Language for readme (default: the first in langs)
--layout <name>	Layout for readme: table, rows, featured, details or list (default table)
--cols <n>	Images per row for readme (default 2)
--base <dir>	Directory the README is in, for relative image paths
--verbose	Show the start command's output and debug detail
--quiet	Only print warnings and errors

Prints the framed images as HTML to paste into a README: by default a table, with the captions under them in <sub>, or with --layout the rows, featured, details or list layout. Clips follow the shots. Image paths are relative to --base, which defaults to the config root.

record

Record animated clips of a terminal app (WebP and GIF, MP4 opt-in). Reads the config file.

showcase record [options]

Option	Meaning
-c, --config <file>	Config file (default: showcase.config.{ts,mts,mjs,js} in the current directory or a parent, up to the project root)
--only <ids>	Comma-separated shot or clip ids
--langs <codes>	Comma-separated languages
--verbose	Show the start command's output and debug detail
--quiet	Only print warnings and errors

Records the terminal clips into outputs.clips (WebP and GIF by default, MP4 when a clip lists it). Each clip starts a fresh app. When a clip asks for MP4 and ffmpeg is not on PATH, it stops before recording anything. Only tty mode has clips.

all

capture, frame, portfolio (if configured), then record (if clips exist). Reads the config file.

showcase all [options]

Option	Meaning
-c, --config <file>	Config file (default: showcase.config.{ts,mts,mjs,js} in the current directory or a parent, up to the project root)
--only <ids>	Comma-separated shot or clip ids
--langs <codes>	Comma-separated languages
--verbose	Show the start command's output and debug detail
--quiet	Only print warnings and errors

Runs capture, then frame, then portfolio when outputs.portfolio is set, then record when the config has clips. --only takes shot and clip ids together and passes each to the step it belongs to.

hero

Render a README banner: logo, name, tagline and stacked shots. Reads the config file.

showcase hero [options]

Option	Meaning
-c, --config <file>	Config file (default: showcase.config.{ts,mts,mjs,js} in the current directory or a parent, up to the project root)
--verbose	Show the start command's output and debug detail
--quiet	Only print warnings and errors

Renders the README banner to hero.output, from the raw captures of hero.shots.

icons

Generate an app icon set from one square image (no config needed).

showcase icons [options]

Option	Meaning
--source <png>	Square source image, 1024px or larger
--preset <name>	web, electron or tauri
--out <dir>	Output directory (default: icons)
--verbose	Show the start command's output and debug detail
--quiet	Only print warnings and errors

Generates an app icon set from one square image. It needs no config, but it needs both --source and --preset:

showcase icons --source assets/mascot.png --preset electron --out apps/desktop/resources

The presets are web, electron and tauri; see Icons for the files each one writes.

init

Write a starter showcase.config.mjs (--tty for a terminal app).

showcase init [options]

Option	Meaning
--ts	Write showcase.config.ts instead
--tty	Start from a terminal app config
--force	Overwrite an existing config
--verbose	Show the start command's output and debug detail
--quiet	Only print warnings and errors

Writes a starter showcase.config.mjs (or showcase.config.ts with --ts) into the current directory, filled in from its package.json. With --tty it starts from a terminal app config, with the command taken from the package’s bin, else its start or dev script. It refuses to overwrite an existing config unless you pass --force.