# Framevideo CLI > FrameVideo CLI dev loop — `npx framevideo` for scaffolding (init), validation (lint, inspect), preview, render, and environment troubleshooting (doctor, browser, info, upgrade). Use when running any of these commands or troubleshooting the FrameVideo build/render environment. For asset preprocessing commands (`tts`, `transcribe`, `remove-background`), invoke the `framevideo-media` skill instead. - Skill: `chanjing-ai/framevideo-cli` (Agent Skill) - Install (CLI): `npx skillmds@latest add chanjing-ai/framevideo-cli` - Raw SKILL.md: https://api.skillmd.com/api/skills/chanjing-ai/framevideo-cli/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: chanjing-ai (https://skillmd.com/u/chanjing-ai) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/chanjing-ai/framevideo-cli --- # FrameVideo CLI ## When To Use Use this skill for: - **Project scaffolding** — `init` to create new projects - **Validation** — `lint` to check structure, `inspect` for visual QA - **Preview** — `preview` to test compositions in browser - **Rendering** — `render` to export final video - **Troubleshooting** — `doctor`, `browser`, `info` for environment issues - **Upgrading** — `upgrade` to update FrameVideo CLI ## Do NOT Use Avoid this skill for: - **Asset preprocessing** — use `framevideo-media` (tts, transcribe, remove-background) - **Writing composition HTML** — use `framevideo` - **Chanjing integration** — use `chanjing-digital-human` - **Visual QA methodology** — use `framevideo-visual-qa` (this skill only runs commands) --- ## Quick Start Complete dev workflow: ```bash # 1. Create project npx framevideo init my-video # 2. Edit composition (see `framevideo` skill) # Edit index.html... # 3. Validate npx framevideo lint # Check structure npx framevideo inspect # Visual QA # 4. Preview npx framevideo preview # Test in browser # 5. Render npx framevideo render . --output video.mp4 ``` **Common options:** - `--example ` — use template (blank, warm-grain, product-promo, etc.) - `--tailwind` — include Tailwind v4 browser runtime - `--video ` — include video file - `--audio ` — include audio file (auto-transcribes) --- ## Workflow 1. **Scaffold** — `npx framevideo init my-video` 2. **Write** — author HTML composition (see the `framevideo` skill) 3. **Lint** — `npx framevideo lint` 4. **Visual inspect** — `npx framevideo inspect` 5. **Preview** — `npx framevideo preview` 6. **Render** — `npx framevideo render` Lint and inspect before preview. `lint` catches missing `data-composition-id`, overlapping tracks, and unregistered timelines. `inspect` opens the rendered composition in headless Chrome, seeks through the timeline, and reports text spilling out of bubbles/containers or off the canvas. ## Scaffolding ```bash npx framevideo init my-video # interactive wizard npx framevideo init my-video --example warm-grain # pick an example npx framevideo init my-video --video clip.mp4 # with video file npx framevideo init my-video --audio track.mp3 # with audio file npx framevideo init my-video --example blank --tailwind # with Tailwind v4 browser runtime npx framevideo init my-video --non-interactive # skip prompts (CI/agents) ``` Templates: `blank`, `warm-grain`, `play-mode`, `swiss-grid`, `vignelli`, `decision-tree`, `kinetic-type`, `product-promo`, `nyt-graph`. `init` creates the right file structure, copies media, transcribes audio with Whisper, and installs AI coding skills. Use it instead of creating files by hand. When using `--tailwind`, invoke the `tailwind` skill before editing classes or theme tokens. The scaffold uses Tailwind v4.2 via the browser runtime, not Studio's Tailwind v3 setup. ## Linting ```bash npx framevideo lint # current directory npx framevideo lint ./my-project # specific project npx framevideo lint --verbose # info-level findings npx framevideo lint --json # machine-readable ``` Lints `index.html` and all files in `compositions/`. Reports errors (must fix), warnings (should fix), and info (with `--verbose`). ## Visual Inspect ```bash npx framevideo inspect # inspect rendered layout over the timeline npx framevideo inspect ./my-project # specific project npx framevideo inspect --json # agent-readable findings npx framevideo inspect --samples 15 # denser timeline sweep npx framevideo inspect --at 1.5,4,7.25 # explicit hero-frame timestamps ``` Use this after `lint` and `validate`, especially for compositions with speech bubbles, cards, captions, or tight typography. It reports: - Text extending outside the nearest visual container or bubble - Text clipped by its own fixed-width/fixed-height box - Text extending outside the composition canvas - Children escaping clipping containers Errors should be fixed before rendering. Warnings are surfaced for agent review; add `--strict` to fail on warnings too. Repeated static issues are collapsed by default so JSON output stays compact for LLM context windows. If overflow is intentional for an entrance/exit animation, mark the element or ancestor with `data-layout-allow-overflow`. If a decorative element should never be audited, mark it with `data-layout-ignore`. `npx framevideo layout` remains available as a compatibility alias for the same visual inspection pass. ## Previewing ```bash npx framevideo preview # serve current directory npx framevideo preview --port 4567 # custom port (default 3002) ``` Hot-reloads on file changes. Opens the studio in your browser automatically. If a video workflow needs Chanjing OAuth login and auth is missing, use preview as the preferred setup surface: 1. Run `npx framevideo preview` in the project. 2. Open the Studio project URL in the Codex in-app browser. 3. Navigate to the Voice, Digital Human, or account area that requires Chanjing access. 4. Click the login control so the OAuth login dialog is visible and the browser authorization flow starts. 5. Let the user complete the authorization page, then re-run the auth/status check before continuing. Only fall back to command-line OAuth login guidance when preview is unavailable or the user explicitly asks not to use the browser UI. Never log tokens or credential-store contents. When handing a project back to the user, use the Studio project URL, not the source `index.html` path: ```text http://localhost:/#project/ ``` Use the actual port from the preview output and the project directory name. For example, after `npx framevideo preview --port 3017` in `codex-openai-video`, report `http://localhost:3017/#project/codex-openai-video`. Treat `index.html` as source-code context only. It is fine to link it as an implementation file, but do not label it as the project or preview surface. ## Rendering ```bash npx framevideo render # standard MP4 npx framevideo render --output final.mp4 # named output npx framevideo render --quality draft # fast iteration npx framevideo render --fps 60 --quality high # final delivery npx framevideo render --format webm # transparent WebM npx framevideo render --docker # byte-identical ``` | Flag | Options | Default | Notes | | -------------------- | --------------------- | -------------------------- | ------------------------------------------------------------------ | | `--output` | path | renders/name_timestamp.mp4 | Output path | | `--fps` | 24, 30, 60 | 30 | 60fps doubles render time | | `--quality` | draft, standard, high | standard | draft for iterating | | `--format` | mp4, webm | mp4 | WebM supports transparency | | `--workers` | 1-8 or auto | auto | Each spawns Chrome | | `--docker` | flag | off | Reproducible output | | `--gpu` | flag | off | GPU-accelerated encoding | | `--strict` | flag | off | Fail on lint errors | | `--strict-all` | flag | off | Fail on errors AND warnings | | `--variables` | JSON object | — | Override variable values declared in `data-composition-variables` | | `--variables-file` | path | — | JSON file with variable values (alternative to `--variables`) | | `--strict-variables` | flag | off | Fail render on undeclared keys or type mismatches in `--variables` | **Quality guidance:** `draft` while iterating, `standard` for review, `high` for final delivery. **Parametrized renders:** the composition declares its variables on the `` root with **`data-composition-variables`** — a JSON **array of declarations** (`{id, type, label, default}` per entry) that defines the schema. Scripts inside read the resolved values via `window.__framevideo.getVariables()`. The CLI **`--variables '{"title":"Q4 Report"}'`** is a JSON **object keyed by id** that overrides those declared defaults for one render; missing keys fall through, so the same composition runs unchanged in dev preview and in production. (Sub-comp hosts can also override per-instance with **`data-variable-values`** — same object shape, scoped to one mount of the sub-composition. See the `framevideo` skill for the full pattern.) ## Asset Preprocessing `npx framevideo tts`, `transcribe`, and `remove-background` produce assets (narration audio, word-level transcripts, transparent video) that get dropped into a composition. Each downloads its own model on first run. For voice selection, whisper model rules (the `.en`-translates-non-English gotcha), output format choice (VP9 alpha WebM vs ProRes), and the TTS → transcribe → captions chain, invoke the `framevideo-media` skill. ## Troubleshooting ```bash npx framevideo doctor # check environment (Chrome, FFmpeg, Node, memory) npx framevideo browser # manage bundled Chrome npx framevideo info # version and environment details npx framevideo upgrade # upgrade CLI and refresh FrameVideo skills ``` Run `doctor` first if rendering fails. Common issues: missing FFmpeg, missing Chrome, low memory. ## Upgrade Workflow When the user asks to upgrade FrameVideo from Codex, Claude Code, Cursor, or another agent tool, handle it as an implementation task, not just advice: 1. Check the available version with `npx framevideo upgrade --check` or `framevideo upgrade --json`. 2. Briefly tell the user the upgrade plan: update the CLI package, refresh FrameVideo skills, then verify the installed command. 3. Run `framevideo upgrade --yes`. 4. If the command did not refresh skills automatically, run `npx skills add chanjing-ai/framevideo --all`. 5. Verify with `framevideo --version` and `framevideo --help`. If any step fails, stop and report the failed step plus the manual command to retry. Do not claim the upgrade completed until the CLI version and skills refresh have both succeeded or the user explicitly accepts a partial upgrade. ## Other ```bash npx framevideo compositions # list compositions in project npx framevideo docs # open documentation npx framevideo benchmark . # benchmark render performance ```