CLI

npx kinetograph <command> [entry] [options]
npx kinetograph <command> --help

The entry is a .tsx, .ts, .jsx or .js project file, a .json scene, or an HTML page (its index.html, or the directory that holds it). HyperFrames projects are HTML pages and render as they are. See HyperFrames projects.

Shared behaviourCopy Anchor Link

• --json prints one JSON object on stdout instead of text. Progress goes to stderr, which stays quiet with --json except for the update notice below. A failure prints { "error": { "code", "message" } }.
• Once a day the CLI checks npm for a newer kinetograph and looks for installed agent skills older than the CLI. It prints one line on stderr, and adds a notices array to the --json result. It never installs anything. CI or KINETOGRAPH_NO_UPDATE_CHECK=1 turns it off.
• --help or -h prints a command's usage. kinetograph --help lists the commands.
• kinetograph --version or -v prints the package version.
• Exit code 0 is success. Exit code 1 is an error, or a failed check: check with type errors, lint with errors, snapshot with a mismatch.

Without -o, still, strip, onion and render write under out/ in the project folder (the folder of the nearest package.json): out/stills/, out/sheets/ and out/renders/, named after the composition.

Commands that open a project take two more options. These are still, render, strip, onion, inspect, lint, bench, audio analyze, snapshot and doctor.

Frames and rangesCopy Anchor Link

A frame is a whole number from 0. A range is written a..b.

• 10..40 is frames 10 to 39. 10..=40 is frames 10 to 40.
• ..40 starts at 0. 10.. runs to the last frame.
• --frames takes a comma-separated list, such as 0,30,60.

initCopy Anchor Link

Creates a project folder with a starter title card.

npx kinetograph init [dir] [--html]

It writes src/index.tsx, src/scenes/Title.tsx, package.json, tsconfig.json and .gitignore, and makes the src/, public/ and out/ folders. With --html it writes html/index.html instead of the TSX files. dir defaults to the current folder. Files that already exist are skipped, never overwritten. It does not run npm install.

addCopy Anchor Link

Installs a component, template or taste from the Kinetograph registry into the project.

npx kinetograph add <name...> [--overwrite] [--yes] [--dir <folder>]
npx kinetograph add --list [--type component|template|taste]

Components go to src/components/<name>/, templates to src/templates/<name>/, tastes to src/tastes/<name>/, and their pictures, fonts and audio to public/<kind>/<name>/. Items an item depends on are installed first. A file that already exists is skipped and reported; --overwrite replaces it. If the item needs npm packages the project lacks, the command shows them and asks before installing (--yes skips the question; with --json or no terminal it only prints the install command). Run it inside a project made by init. An item that is not published yet says so and installs nothing.

compositionsCopy Anchor Link

Lists the compositions in a project, with size, frame rate and length.

npx kinetograph compositions <entry>

stillCopy Anchor Link

Renders one frame to a PNG.

npx kinetograph still <entry> <frame> [-o <output.png>] [options]

renderCopy Anchor Link

Renders frames to a video with audio.

npx kinetograph render src/index.tsx

For a HyperFrames page, render first downloads what the page loads from the web. Add --offline to skip that step. A directory that holds the index.html works too.

The general form is:

npx kinetograph render <entry> [-o <output.mp4>] [options]

A bad combination of export flags is refused before bundling, and the message names the flag to change.

Choose an encoderCopy Anchor Link

The built-in ffmpeg handles decoding and its own encoders. An encoder it lacks runs in a separate ffmpeg program: the one in the platform package, or the one KINETOGRAPH_FFMPEG names, then an ffmpeg on your PATH that has libx264. Name h264_videotoolbox or hevc_videotoolbox for the Mac's hardware encoders.

To use your system ffmpeg, set KINETOGRAPH_FFMPEG=$(which ffmpeg). This gives you libx264, and on Intel and AMD GPUs under Linux h264_vaapi, hevc_vaapi, h264_qsv and hevc_qsv (see What works). Licences are under FFmpeg licence.

stripCopy Anchor Link

Writes a contact sheet of evenly spaced frames, labelled with frame number and time.

npx kinetograph strip <entry> -n 12 [-o <sheet.png>] [options]

onionCopy Anchor Link

Blends frames of a range over one another, to show a motion path.

npx kinetograph onion <entry> <a..b> -n 6 [-o <onion.png>] [options]

inspectCopy Anchor Link

Prints the scene graph at one frame: each layer's id, type, bounds, effects, and text or file. With --json you get the full graph.

npx kinetograph inspect <entry> --frame 30

lintCopy Anchor Link

Checks a project at a few frames. It reports overflowing text, layers off the canvas, overlapping text, missing fonts and assets, type errors, and content the engine cannot draw. Each finding names its rule, layer and frames.

npx kinetograph lint <entry> --frames 0,30,60

Exit code 1 means at least one error. Warnings do not change it.

checkCopy Anchor Link

Runs tsc --noEmit with the nearest tsconfig.json. It catches misspelled props, which otherwise render without an error.

npx kinetograph check <entry>

There are no options. A scene file, or a JavaScript project without a tsconfig.json, has nothing to check.

benchCopy Anchor Link

Times each stage of drawing a frame in milliseconds: js, stringify, handoff, resolve, raster, composite, readback and total.

npx kinetograph bench <entry> --frame 30 --runs 10
npx kinetograph bench <entry> --range 40..90

bench uses React's development build unless NODE_ENV is set. For the production build, run NODE_ENV=production npx kinetograph bench ....

audio analyzeCopy Anchor Link

Mixes the project's audio and measures it: integrated loudness (LUFS), true peak (dBTP), clipped samples and silences. See Audio.

npx kinetograph audio analyze <entry> --scenes 0..90,90..180

snapshotCopy Anchor Link

Compares rendered frames with approved PNGs in a __snapshots__/ folder next to the entry. A file is named like card.Title.f30.png.

npx kinetograph snapshot <entry> --frames 0,30,60
npx kinetograph snapshot <entry> --update

A frame matches when no colour channel is off by more than 2 levels. A mismatch or a missing approved file exits with 1.

effectsCopy Anchor Link

Lists every effect with its type, description and fields.

npx kinetograph effects

doctorCopy Anchor Link

Runs every frame in the range without the GPU and reports what the engine cannot draw, and where. Use it before a long render. See What works.

npx kinetograph doctor src/index.ts --range 0..120

With no entry, doctor checks your install:

npx kinetograph doctor

It prints the Node version, the platform, whether the addon loaded, and which renderer draws (renderer). It also reports the CLI version against the latest on npm (cli) and each installed agent skill with its version and whether it is current (skills). If Skia falls back to the CPU, rendererReason (why not the GPU: in the text) says why: the device, the driver and what it lacks.

studioCopy Anchor Link

Opens the local editor in a browser. See Studio.

npx kinetograph studio <entry>

The studio is the @kinetographdev/studio package, which installs with kinetograph. Stop it with Ctrl-C.

The Available list in the Props tab comes from https://kinetograph.dev/api/catalog, cached in ~/.cache/kinetograph/plugin-catalog.json. --offline (or KINETOGRAPH_OFFLINE=1) never asks the site. KINETOGRAPH_CATALOG_URL reads the list from another address.

fetch-depsCopy Anchor Link

Downloads what a project loads from the web (CDN scripts, ES modules, remote pictures, media, Google Fonts) into the local cache. It pins each file in kinetograph.lock.json beside the entry.

render, still, doctor and studio do this first on their own. Run fetch-deps to do it ahead of time, such as in CI. With --offline on those commands, a file that is not cached is an error.

npx kinetograph fetch-deps src/index.ts --update

For a Remotion project, fetch-deps fetches the remote pictures and videos its bundle names. Only --update applies. --allow-host, --url and --max-media-mb are for HyperFrames pages.

mcpCopy Anchor Link

Runs the MCP server on stdio. It has one tool for each command except studio. See Use with agents.

npx kinetograph mcp

Export optionsCopy Anchor Link

The render codec and quality options follow Remotion's names. The defaults are:

• H.264: crf 18 with the software encoder (libx264). libopenh264 and the hardware encoders get a bit rate instead. VideoToolbox on macOS is opt-in with --encoder h264_videotoolbox and uses 0.2 bits per pixel per frame.
• libx264, libx265 and VP9 keep their own keyframe interval. Encoders that would take FFmpeg's 12 frames (VideoToolbox, OpenH264, hardware encoders) write one every 2 seconds.
• VP9: crf 30. H.265: crf 28.
• Audio: 96 kbit/s per channel.

--crf does not apply to prores or gif. The encoder choice for each codec is in AUTHORING.md, section 9.