# CLI reference URL: /docs/cli 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 ` 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 ` | 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 to a config file (otherwise auto-discovered). | | `--cwd ` | Working directory. | | `--asset ` | Only generate this asset. Repeatable. Dependencies of selected assets are pulled in automatically. | | `--concurrency ` | Override `settings.concurrency`. | | `--skip-browser` | Skip the Chromium check/install. | | `--skip-server` | Skip the [managed server](/docs/configuration#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`](#pro-visu-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 to a config file. | | `--cwd ` | Working directory. | ## `pro-visu list` (alias `ls`) Print the assets recorded in the manifest (id, generator, file, dimensions, size). | Flag | Meaning | | ----------------- | -------------------------------------------------------------- | | `--config ` | Path to a config file. | | `--cwd ` | 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 ` escapes the folder convention. See [Configuration](/docs/configuration) for details.