CLI reference
The showcase commands — init, generate, list, and reset — and their flags.
The CLI is pro-visu (available as npx pro-visu once installed). Every command accepts
--cwd <dir> to run against a different working directory.
pro-visu init
Scaffold config, gitignore the output dir, wire a package script, and ensure a browser.
| Flag | Meaning |
|---|---|
--cwd <dir> | Working directory. |
--no-script | Do not add a "pro-visu" script to package.json. |
--skip-browser | Do not install Chromium / ffmpeg now (they're fetched on first generate). |
--json | Scaffold a dependency-free pro-visu.config.json + a sibling pro-visu.schema.json instead of the TS defineConfig file. Ideal for npx / global use. |
init is idempotent — it leaves an existing config untouched and only creates what's missing.
pro-visu generate (alias gen)
Run the generators defined in your config; writes assets and manifest.json into outDir.
| Flag | Meaning |
|---|---|
--config <path> | Path to a config file (otherwise auto-discovered). |
--cwd <dir> | Working directory. |
--asset <name> | Only generate this asset. Repeatable. Dependencies of selected assets are pulled in automatically. |
--concurrency <n> | Override settings.concurrency. |
--skip-browser | Skip the Chromium check/install. |
--skip-server | Skip the managed server — capture an already-running site. |
--skip-build | Keep the managed server but skip its build step (fast iteration when the site is unchanged). |
--draft | Draft quality: faster, lower-fidelity renders for iteration. |
--cache | Skip assets whose inputs + options + tool fingerprint are unchanged. |
--verbose | Verbose (debug) logging. |
On an interactive terminal, a live dashboard groups setup (build/server) and per-asset
progress, each row with a progress bar, its current step, and elapsed time. Frame-stepped
video captures show a real percentage and ETA; realtime recordings and stills show an
indeterminate indicator. A header rollup tracks overall done/total (and cached) progress, and
the layout adapts to the terminal width — when there are more assets than fit, the rows show a
window around the running ones with ↑ N more / ↓ N more markers.
Keys:
- Esc / Ctrl+C — cancel: in-flight captures are aborted promptly (the frame loop stops and ffmpeg is killed), then the server/browser are torn down; press again to force-quit.
- ↑ / ↓ (and PgUp / PgDn) — scroll the asset window; this pauses auto-follow.
- f — resume following the running rows.
When the run finishes, a summary panel lists each asset's dimensions and size with totals.
Set SHOWCASE_LIVE=0 to force plain logs, or SHOWCASE_LIVE=1 to force the dashboard on a
terminal that mis-reports as non-interactive.
pro-visu list (alias ls)
Print the assets recorded in the manifest (id, generator, file, dimensions, size).
| Flag | Meaning |
|---|---|
--config <path> | Path to a config file. |
--cwd <dir> | Working directory. |
pro-visu schema
Write a JSON Schema for pro-visu.config.json so editors give autocomplete + validation for a
dependency-free (JSON) config — the same authoring help the typed defineConfig gives, without
installing the package. Reference it from the config with "$schema": "./pro-visu.schema.json"
(pro-visu init --json wires this up for you). Re-run after upgrading the tool to refresh the
schema to the new version.
| Flag | Meaning |
|---|---|
--cwd <dir> | Working directory. |
--out <path> | Output path (default pro-visu.schema.json). |
The schema is generated from the installed tool's own validation schemas, so it always matches your
version and includes per-generator options (the right options autocomplete once you set
generator).
pro-visu reset
Tear down anything a previous generate left running if it was killed hard (crash or a
forced quit): the managed-server and browser process trees, plus the run's temp directories,
recorded in a run-state file under outDir. A clean exit removes that file, so there's
normally nothing to do.
| Flag | Meaning |
|---|---|
--config <path> | Path to a config file. |
--cwd <dir> | Working directory. |
--force | Clean up even if a run still looks active. |
Update notifications
The CLI checks npm at most once a day for a newer release and, if one exists, prints a small notice after the command finishes:
Update available 0.2.0 → 0.3.0
Run `pnpm add -D pro-visu@latest` to updateThe check runs in a detached background process and is fully best-effort — it never blocks, slows,
or fails a command. It stays quiet automatically in CI, in non-interactive (piped) output, and on
an unpublished local build. To turn it off, set NO_UPDATE_NOTIFIER=1, pass --no-update-notifier
on any run, or opt out permanently via the configstore file noted in the
update-notifier docs.
Config discovery
Without --config, the CLI looks for pro-visu.config.{ts,js,mjs,cjs,json}, .pro-visurc,
.pro-visurc.json, or a pro-visu key in package.json. See
Configuration for details.