@altavinci/cli

Node-compatible command-line tools for Altavinci scene diagnostics and deterministic frame export.

Install

npx @altavinci/cli --help

Installed bin:

alt <command>

Development from the workspace root:

bun packages/cli/src/index.ts <command>

Commands

alt init <name> [--json]
alt compile <scene.html> [--json]
alt frame <scene.html> --at <time> --out <file.png> [--json] [--width 1920] [--height 1080] [--scale 1] [--bridge-port <port>]
alt frames <scene.html> --at <time,time,...> --out-dir <dir> [--json] [--width 1920] [--height 1080] [--scale 1] [--bridge-port <port>]
alt render <path> [--api-key <token>] [--api-url <url>] [--entry scene.html] [--duration <time>] [--fps 60] [--width <px>] [--height <px>] [--quality standard] [--codec h264] [--format mp4] [--scene <name>] [--callback-url <https>] [--wait] [--out <file.mp4|directory>] [--poll-interval <ms>] [--timeout <time>] [--json]
alt render status <renderId> [--api-key <token>] [--api-url <url>] [--out <file.mp4|directory>] [--json]
alt render download <renderId> --out <file.mp4|directory> [--api-key <token>] [--api-url <url>] [--json]

Init

Create a new Altavinci project and install the skill for agents:

alt init hello-scene

This writes:

• hello-scene/scene.html
• hello-scene/.agents/skills/altavinci/**

Compile

Compile an HTML scene and print diagnostics.

alt compile apps/playground/scenes/html/01-basic.html
alt compile apps/playground/scenes/html/01-basic.html --json

The command reads the scene directory, compiles with rich text run support, and exits 0 only when there are no error diagnostics.

Frame

Render one exact scene-time frame to PNG.

alt frame apps/playground/scenes/html/01-basic.html \
  --at 250ms \
  --out /tmp/frame.png \
  --width 1920 \
  --height 1080 \
  --scale 1 \
  --json

Time values support 7240ms, 7.24s, or bare millisecond numbers such as 7240.

Frames

Render multiple exact scene-time frames over one bridge connection.

alt frames apps/playground/scenes/html/01-basic.html \
  --at 0ms,250ms,1s \
  --out-dir /tmp/frames \
  --width 1920 \
  --height 1080 \
  --scale 1 \
  --json

Output filenames are deterministic:

frame-000-0ms.png
frame-001-250ms.png
frame-002-1000ms.png

Render

Zip a scene folder and render it through the Altavinci Render API.

alt render ./my-scene \
  --wait \
  --out /tmp/scene.mp4 \
  --api-key "$ALTAVINCI_API_KEY"

Auth comes from --api-key <token> or ALTAVINCI_API_KEY in the environment or .env. Override the API with --api-url <url> or ALTAVINCI_API_URL; the default is https://altavinci-api.nouro-flow.workers.dev.

<path> can be a scene directory or an HTML file. Directories use scene.html unless --entry <file.html> is passed. The CLI compiles the entry first, derives duration, fps, width, and height from the scene when possible, then uploads a multipart ZIP with renderer options.

Renderer flags: --duration <time>, --fps <int>, --width <int>, --height <int>, --quality draft|standard|high, --codec h264, --format mp4, --scene <name>, and --callback-url <https>. Explicit flags override values derived from the scene.

--wait polls until completion and prints render stats. --out <file.mp4|directory> implies --wait, downloads the MP4, and creates parent directories. When --out points at an existing directory or ends with a slash, the CLI writes <directory>/<renderId>.mp4. Use --poll-interval <ms>, --timeout <time>, and --json for automation.

Already have a render id? Use alt render status <renderId> to fetch the current state and formatted metrics. Add --out <file.mp4|directory> to download a completed render while showing status. alt render download <renderId> --out <file.mp4|directory> is the download-only spelling and fails if the render is not completed yet.

ZIP packaging includes binary assets such as fonts and static raster images. It excludes .agents, .git, .turbo, dist, node_modules, .env*, .DS_Store, and video/GIF preview files because the worker rejects those media inputs.

Render bridge

frame and frames compile the scene first, then send render requests over a local WebSocket bridge to a running Studio or Playground tab. The browser tab renders the compiled runtime AST and returns PNG bytes to the CLI.

Default bridge URL:

ws://127.0.0.1:53847

If the default port is busy, pass --bridge-port <port> and open the Studio or Playground URL printed by the command. The protocol is Node-compatible and uses node:http plus ws, so the published CLI runs under Node through npx @altavinci/cli.