@ui2v/cli

Command-line interface for validating, previewing, inspecting, and rendering ui2v animation JSON projects.

Most users should install the short package name:

npm install -g @ui2v/cli
# or: bun install -g ui2v
ui2v --version

This implementation package can also be installed directly:

npm install -g @ui2v/cli

First Render

ui2v doctor
ui2v validate examples/library-timeline/animation.json --verbose
ui2v preview examples/library-timeline/animation.json --pixel-ratio 2
ui2v render examples/library-timeline/animation.json -o .tmp/examples/library-timeline.mp4 --quality high

Run without a global install:

npx @ui2v/cli --version
npx @ui2v/cli render examples/library-timeline/animation.json -o library-timeline.mp4 --quality high

Commands

The preview command opens a local Studio UI with a searchable JSON project list, timeline scrubbing, fit/theater/fullscreen controls, runtime debug overlay, and an Export MP4 action.

ui2v doctor
ui2v init my-video
ui2v validate animation.json --verbose
ui2v preview animation.json --pixel-ratio 2
ui2v inspect-runtime animation.json --time 0 --time 1
ui2v render animation.json -o output.mp4
ui2v info

Render Options

ui2v render animation.json -o output.mp4 --quality high --fps 60
ui2v render animation.json -o output.mp4 --width 1280 --height 720 --render-scale 2
ui2v render animation.json -o output.mp4 --codec avc --bitrate 8000000
ui2v render animation.json -o output.mp4 --timeout 300 --no-headless

render currently targets MP4. AVC/H.264 is the default codec. HEVC can be requested only when the local browser supports it.

Local Development

bun install
bun run build
node packages/cli/dist/cli.js doctor

If no browser is found, install Chrome, Edge, or Chromium locally. If auto-detection fails, set one of these environment variables:

PUPPETEER_EXECUTABLE_PATH=/path/to/chrome node packages/cli/dist/cli.js doctor
CHROME_PATH=/path/to/chrome node packages/cli/dist/cli.js doctor

License

MIT