Vize
CLI Reference
Most application workflows should install the vize npm package and run it through package.json
scripts. This page describes the lower-level Rust-native vize binary for LSP, IDE management, check-server, profiling, and other direct CLI workflows. The npm package exposes shared config helpers plus NAPI-backed build, fmt, lint, check, clean, ready, and upgrade commands.
For a higher-level explanation of the analysis pipeline, see Static Analysis.
Application Package Scripts
For apps, install from npm and wire stable commands into project scripts:
vp install -D vize
{
"scripts": {
"vize:build": "vize build src",
"vize:fmt": "vize fmt --write src",
"vize:lint": "vize lint --preset happy-path src",
"vize:check": "vize check src",
"vize:ready": "vize ready src"
}
}
vp run vize:lint
vp run vize:check
vp run vize:ready
Use vp exec vize ... for one-off debugging; prefer named scripts for documented workflows and CI.
Rust Binary Installation
For v1 alpha, use the prebuilt GitHub release binaries or the Nix entry point. The Rust CLI is not a supported crates.io install channel yet.
nix run github:ubugeeei-prod/vize#vize -- --help
You can also download platform-specific binaries from GitHub Releases.
For local development inside this repository, install the workspace build:
cargo install --path crates/vize --force --locked
npm Package Scripts vs Rust CLI
| Need | Recommended entry point |
|---|---|
| Package scripts for build, format, lint, check, ready, and upgrade | vp run vize:* from the npm package |
Project-backed type checking across .vue, .ts, .tsx, and .d.ts |
Rust vize check |
LSP, IDE setup, check-server, and profiling artifacts |
Rust vize binary |
| Shared Vite plugin, npm package command, and Rust CLI settings | vize.config.* |
Commands
vize [COMMAND]
When invoked without a command, vize defaults to build.
| Command | Description |
|---|---|
build |
Compile Vue SFC files |
fmt |
Format Vue SFC files |
lint |
Lint Vue SFC files |
check |
Type check Vue SFC, TS, TSX, and .d.ts inputs |
doctor |
Analyze whole-application health |
inspector |
Create playground compiler inspector payloads |
clean |
Remove Vize-generated cache artifacts |
ready |
Run fmt, lint, check, and build |
upgrade |
Update the installed CLI |
check-server |
Start the Unix JSON-RPC typecheck server |
content-mapper |
Start the TypeScript content-mapper server |
musea |
Musea subcommands and scaffolding |
lsp |
Start the language server |
ide |
Install or manage editor integrations |
Build
vize build src/**/*.vue
vize build --ssr
vize build --profile src
Key options:
| Option | Description |
|---|---|
-o, --output |
Source-relative output below the common input root; rejects collisions |
-f, --format |
Output format: js, json, stats |
--ssr |
Enable SSR compilation |
--custom-renderer |
Treat lowercase non-HTML tags as custom renderer elements |
--custom-elements <PATTERN> |
Tag patterns compiled as custom elements; repeat for multiple patterns |
--script-ext |
preserve or downcompile |
--declaration |
Emit .d.ts files for the built SFCs (alias: --dts) |
--declaration-dir |
Declaration output directory (default: the build output directory) |
-j, --threads |
Thread count override |
--profile |
Print timing profile |
--continue-on-error |
Keep compiling and report failures at the end |
Format
vize fmt --check src
vize fmt --write src
Key options:
| Option | Description |
|---|---|
--check |
Report files that would change |
-w, --write |
Write formatted output |
--single-quote |
Toggle string quote style |
--print-width |
Maximum line width |
--tab-width |
Indentation width |
--use-tabs |
Toggle tabs vs spaces |
--no-semi |
Omit semicolons |
--sort-attributes |
Sort template attributes |
--single-attribute-per-line |
Put one attribute per line |
--max-attributes-per-line |
Wrap after a given attribute count |
--normalize-directive-shorthands |
Normalize v-bind: / v-on: / v-slot: shorthands |
--profile |
Print timing profile |
Lint
vize lint src
vize lint --preset opinionated src
vize lint --help-level short src
Key options:
| Option | Description |
|---|---|
--fix |
Apply safe autofixes from rules that provide text edits, then report remaining diagnostics |
-f, --format |
Output format: text, ansi, plain, json, stylish, markdown, html, or agent |
--max-warnings |
Fail when warnings exceed the limit |
-q, --quiet |
Show summary only |
--help-level |
full, short, or none |
--preset |
happy-path, opinionated, essential, incremental, or nuxt |
--cross-file |
Enable opt-in cross-file checks |
--cross-file-tree |
Print the provide/inject tree when cross-file linting is enabled |
--strict-reactivity |
Enable native checker-backed reactivity-loss linting |
--profile |
Print timing profile |
--slow-threshold |
Slow file threshold for profile output |
Presets are intended for staged adoption:
| Preset | Use it when |
|---|---|
essential |
You want correctness-oriented diagnostics in CI |
happy-path |
You want the default recommended bundle |
opinionated |
You want stronger conventions, script rules, and type-aware candidates |
incremental |
You only want explicitly configured rules |
nuxt |
You want opinionated rules with Nuxt component assumptions |
Examples:
vize lint --preset essential --max-warnings 0 src
vize lint --preset opinionated --help-level short src
vize lint --cross-file --cross-file-tree src
vize lint --strict-reactivity src
vize lint --format agent src
Check
vize check
vize check src
vize check --tsconfig tsconfig.app.json
vize check --profile src
vize check is backed by vize_canon and Corsa project sessions exposed through corsa-bind. Vize generates virtual TypeScript for Vue SFCs, runs project diagnostics on a native path, and maps the results back to the original source locations.
When no explicit paths are given, vize check uses tsconfig.json files / include /
exclude if available. Explicit inputs may be files, directories, or globs and can include .vue,
.ts, .tsx, and .d.ts.
Key options:
| Option | Description |
|---|---|
-s, --socket |
Connect to a running check-server |
--tsconfig |
Override tsconfig.json |
-f, --format |
Output format: text or json |
--show-virtual-ts |
Print generated virtual TypeScript |
-q, --quiet |
Show summary only |
--profile |
Write profile artifacts under node_modules/.vize |
--corsa-path |
Override the Corsa executable path |
--servers |
Reserved Corsa server count; only 1 is supported |
--declaration |
Emit .d.ts output |
--declaration-dir |
Output directory for emitted declarations |
Use --corsa-path to pin a local Corsa build. The shared config key is typeChecker.corsaPath;
typeChecker.tsgoPath remains only as a compatibility alias.
Project-wide template values and Vue ambient types should be visible through TypeScript project
configuration. Include generated files such as auto-imports.d.ts, components.d.ts, or your own
declare module "vue" augmentations in the tsconfig.json include globs, then select that project
with --tsconfig when needed:
{
"include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue", "src/**/*.d.ts"]
}
Doctor
vize doctor
vize doctor src
vize doctor src packages/shared --format json
vize doctor builds one deterministic application graph across Vue SFCs and script modules. The
initial analyzers cover dependency injection, unique element IDs, server/client boundaries, reactivity
flow, asynchronous mutation risks, setup-context ownership, circular imports, and cross-component
prop contracts. Vue diagnostics map back to byte offsets in the authored .vue file, including
template prop usages and related defineProps declarations in components with both <script> and
<script setup>. Discovery follows source-control ignore files, rejects inputs outside the declared
workspace, fails closed when a component or script module cannot be parsed, and never writes files.
Key options:
| Option | Description |
|---|---|
--root |
Workspace boundary and base for report paths; defaults to the current directory |
-f, --format |
Output format: text (default) or versioned json |
--exit-zero |
Return success even when a proven error would normally block |
Exit status 0 means the gate passed, 1 means a certain or high-confidence error, and 2 means
discovery, parsing, analysis, serialization, or output failed. Warnings and lower-confidence findings
affect the health score but do not block by default. See Doctor diagnostics for precise
filter, changed-file, scoring, and automation contracts. The deterministic --format json report
carries explicit format and scoring versions and is the preferred interface for CI and AI tooling:
vize doctor src --format json > doctor-report.json
Inspector
vize inspector src/App.vue
vize inspector "src/**/*.vue" --target ssr
vize inspector src --format json --output inspector-payload.json
vize inspector src --format agent --output inspector-agent.json
vize inspector packages one or more .vue files into the payload consumed by the playground
compiler inspector. The browser then inspects Vue output, Vize output, Virtual TS, VIR, and the
cross-file graph, then produces a permalink plus a prefilled pull request link.
Use --format agent when another local tool or AI agent needs the same repro without opening the
browser. The report contains the exact payload, playground URL, summary metrics, and import graph.
Key options:
| Option | Description |
|---|---|
-f, --format |
Output format: url, json, or agent |
--target |
Compiler target: dom or ssr |
--playground-url |
Playground base URL for generated links |
--max-files |
Limit files included in a batch payload |
--custom-renderer |
Enable custom renderer comparison |
--template-syntax |
Choose standard, strict, or quirks |
-o, --output |
Write the URL or JSON payload to a file |
See Compiler Inspector for the contributor workflow.
Clean
vize clean
vize clean --dry-run
vize clean --scope node-modules
vize clean --scope project
vize clean --force
vize clean path/to/project
vize clean removes known Vize-owned local artifacts (profile outputs, Musea
reports/snapshots/tokens, Patina sessions, config schemas, LSP logs, socket leftovers, OXC dumps,
Oxlint workaround files, and materialized Corsa project files) for the selected project root, then
removes empty .vize and node_modules/.vize parents. Unknown entries under .vize are preserved
unless --force removes the artifact root wholesale. --dry-run prints the paths that would be
removed; --scope node-modules or --scope project limits cleanup to one artifact root.
Ready
vize ready src
vize ready --output dist src
vize ready runs fmt --write, lint, check, and build in order, stopping at the first failing
step.
Key options:
| Option | Description |
|---|---|
-o, --output |
Output directory for the build step |
--ssr |
Enable SSR compilation for build |
--script-ext |
preserve or downcompile |
Upgrade
vize upgrade
vize upgrade --dry-run
By default, vize upgrade updates the npm package through Vite+:
vp install -D vize@latest
Use --source cargo only for explicit local Cargo installs.
Musea
vize musea --help
vize musea serve --port 6006
vize musea new
The musea subcommand currently focuses on scaffolding and experimental entry points. For
day-to-day gallery development, prefer @vizejs/vite-plugin-musea. The npm package also exposes a
convenience vize musea command that runs Vite with the Musea plugin installed (vp exec vize musea, or add --build for a production build).
LSP and IDE
vize lsp
vize lsp --port 9527
vize ide vscode
vize ide zed
vize lsp starts the language server directly. vize ide adds editor-specific install and
management commands for the VS Code and Zed integrations.
Global Options
vize --help
vize --version
vize <command> --help