Use the CLI
Scaffold a project, preview scenes with hot reload, and render videos
The CLI is one command each for scaffolding, previewing, and rendering, driven by two code entrypoints instead of a config file:
bun create effect-motionThe wizard asks where to create the project, which package manager to use, and whether to set up Biome, then installs a ready-to-run project:
my-project/
├─ src/
│ ├─ scenes/hello-world.ts # a scene: a module exporting `scene`
│ ├─ assets/ # static files
│ └─ main.ts # the movie — a scene composing the others
├─ studio.ts # what `motion studio` previews
├─ render.ts # what `motion render` executes
├─ AGENTS.md # authoring rules for AI coding agents
├─ package.json # exact pins of effect-motion + effect
└─ tsconfig.jsonVersions are pinned exactly on purpose: the effect pin is a determinism
invariant (upgrading effect can change seeded random sequences), so a
scaffolded project upgrades both together, deliberately.
Both entrypoints are ordinary TypeScript that imports your scenes as values — which is what makes typed resources work end to end: a scene that declares fonts or images carries that requirement in its type, and the entrypoint won't compile until the loaders are provided.
Preview — studio.ts
motion studio # serves ./studio.ts
motion studio ./other.studio.tsstudio.ts default-exports the studio's registration — a record of scenes,
plus one layers covering all of them once any scene declares resources:
import { studioConfig } from "@effect-motion/cli";
import { scene as main } from "./src/main";
import { scene as helloWorld } from "./src/scenes/hello-world";
export default studioConfig({
scenes: {
"hello-world": helloWorld,
main: { scene: main, fps: 30 }, // per-entry player options
},
// layers: Layer.mergeAll(Font.layer(…), Image.layer(…)),
});Only registered scenes appear — registration is one import and one entry,
and it's what lets the compiler prove layers covers every scene. Hot
reload is plain Vite HMR over the entrypoint's import graph.
Render — render.ts
motion render # executes ./render.ts
motion render ./teaser.render.tsrender.ts is an ordinary program: it calls the
export API and default-exports the effect. The
CLI provides the platform and runs it — nothing more:
import { Video } from "@effect-motion/export";
import * as Effect from "effect/Effect";
import { scene as main } from "./src/main";
export default Effect.gen(function* () {
yield* Video.render(main, "./output/main.mp4", {
settings: { frameRate: 60 },
});
});There are no render flags: code is the config. Knobs you'd reach for as
flags (fps, seed, dpr, output paths) are values in render.ts — read
process.env there if you want them switchable. The same file runs without
the CLI: provide NodeServices.layer from @effect/platform-node and run
it with tsx render.ts. --verbose prints full error cause chains.
Sample frames — motion frames
motion frames # list the scenes in ./studio.ts with their lengths
motion frames hello-world # 6 evenly spaced PNG stills
motion frames hello-world --at 0,1.5s,50%,end
motion frames hello-world --count 9 --sheet
motion frames hello-world --count 5 --range 1s..2s --sheet
motion frames hello-world --at 50% --json -motion frames renders chosen frames of a scene registered in studio.ts
headlessly — no browser, no video. It runs the scene with the same settings
the studio uses for that entry (fps, layers).
| Flag | Meaning |
|---|---|
--at <selection> | Comma-separated frames: an index (30), a time (1.5s, 500ms), a percentage (50%), or end |
--count <n> | n evenly spaced frames, first and last included (default 6; clamps to every frame once) |
--range <from>..<to> | Spread --count over this span instead of the whole scene, both ends included; each end is any single selector (7.5s..8.5s, 50%..end, 120..180) |
--sheet | Write one contact sheet (sheet.png) instead of stills |
--json <path|-> | Write frame state as JSON to a file, or to stdout with - |
--out <dir> | Output directory (default .motion/frames/<scene>/) |
--dpr <n> | Supersampling factor for PNGs (default 1) |
--tile-width <px> | Max width of each sheet tile; larger frames are downscaled, aspect kept (default 480) |
--studio <file> | Studio entrypoint (default ./studio.ts) |
With no scene, it lists every scene key with its length in frames and seconds (each scene is run once to measure it; nothing is rendered).
Pass --at or --count/--range, not both. A time maps to frame
round(seconds × frameRate); frame 0 is the first rendered frame.
- Stills (the default) are written as
<frame>.png(e.g.0015.png), one per distinct frame; each path is printed with its frame and time. --sheetlays the frames out row-major in one grid and printstile=<i> frame=<f> time=<t>for every tile. Tiles are at most 480 px wide by default, so a nine-tile sheet of a 1080p scene stays around 1450 px wide; raise--tile-widthfor detail.--jsonwrites, per sampled frame, its index, time, width, height, frame rate, camera, and every instance's data. With--jsonalone no PNGs are written and the GPU renderer is never loaded. With-, stdout carries only the JSON; other output goes to stderr. Combine with--sheetto get both.
Fonts and images come from the studio's layers, the same ones the
studio previews with; stills and sheets need them, JSON does not.
The scene ends where its video ends: once the body and every fork are
done. end is that last frame; backgrounds and tails still running after
Scene.finish are cut there, in the video and the player too, so no sheet
shows them.
%, end and --count without --range need the scene's length, so they
fail for an infinite scene; indices, times and ranges of them still work. Out-of-range frames, bad
selectors and unknown scene keys exit non-zero with a message naming the
offender. See Preview frames without a browser
for the edit–check loop.