CLI reference
The pro-visu commands — init, generate, doctor, and list — 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 --version prints the
version; --help, alone or after any command, prints usage.
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. It
detects your package manager, framework, and dev port (e.g. Next.js on 3000, Vite on 5173) and
scaffolds the config to match. When pro-visu isn't installed as a project dependency (npx / global
use), it automatically falls back to the JSON config, since the TS template's
import { defineConfig } from "pro-visu" wouldn't resolve.
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 — plain log lines instead of the live dashboard. |
Before any heavy work, generate validates every selected asset's options and — when no managed
server is configured — probes the asset URLs, so a typo'd option or a dev server that isn't
running fails in seconds with a pointed message. (For a full read-only checkup and the resolved
plan, run doctor.)
generate also self-heals on startup: if a previous run was killed hard (crash or forced
quit), the orphaned server process tree and temp dirs it recorded are cleaned up automatically
before the new run starts. Heavy frame-stepped plans (real media walls) re-exec the CLI with a
larger Node heap sized from your machine's RAM, so big renders don't hit Node's default limit.
On an interactive terminal, a live dashboard shows setup (build/server) and per-asset progress —
bar, current step, ETA where determinate — with a done/total header rollup, windowed to the
terminal height. Keys: Esc/Ctrl+C cancel (again to force-quit), ↑/↓ or PgUp/PgDn scroll,
f resume following the running rows. A summary panel with dimensions/sizes prints at the end.
Set PRO_VISU_LIVE=0 to force plain logs or PRO_VISU_LIVE=1 to force the dashboard.
pro-visu doctor
Check the setup without generating anything: Node version, config discovery + validation (including every asset's generator options and the dependency graph), Chromium, ffmpeg, the resolved plan (each asset, its target URL, and the server decision), and — when no managed server is configured — whether the asset URLs actually respond. Exits non-zero when something needs fixing, so it also works as a CI gate.
| Flag | Meaning |
|---|---|
--config <path> | Path to a config file. |
--cwd <dir> | Working directory. |
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. |
--json | Print the manifest as JSON (machine-readable, for scripts/CI). |
JSON Schema (automatic)
pro-visu init --json writes a pro-visu.schema.json next to the JSON config and references it
via "$schema" — editors then give the same autocomplete + validation the typed defineConfig
path gets. The schema is generated from the installed tool's own validation schemas and is
refreshed automatically: whenever generate or doctor runs after an upgrade, a stale
schema file is rewritten to match the new version. There is nothing to re-run by hand.
Update notifications
The CLI checks npm at most once a day (in a detached background process — it never blocks or slows a command) and, if a newer release exists, prints a small notice after the command finishes:
Update available 0.5.0 → 0.6.0
Run npm i pro-visu@latest (or your package manager's equivalent) to update.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 or pass --no-update-notifier on any
run.
Config discovery
Without --config, the CLI looks inside the pro-visu/ folder for
pro-visu.config.{ts,js,mjs,cjs,json}, .pro-visurc, or .pro-visurc.json. An explicit
--config <path> escapes the folder convention. See
Configuration for details.