CLI

The cinecode binary has a small set of subcommands. Run cinecode --help or cinecode <command> --help for the built-in usage.

`cinecode new`

Scaffold a new project.

cinecode new <name>

Argument	Description
`<name>`	Directory to create, containing `codescene.toml`, `scenes/`, and `src/`.

The scaffold also creates assets/ and shaders/, then prints the check, preview, and render commands to run next.

`cinecode add scene`

Create a scene file and append it to an existing project's manifest.

cinecode add scene <name> [--project <path>] [--template <template>]

Option	Description
`<name>`	Display name; converted to a safe lowercase file slug.
`-p, --project <path>`	Project directory or `codescene.toml` (default `.`).
`--template <template>`	`blank`, `code-walkthrough`, or `before-after-diff`.

The update is atomic and validated. Existing files, duplicate manifest entries, unsafe names, or a template that cannot build cause an error with no partial manifest change.

`cinecode render`

Render a project to a video (or image sequence).

cinecode render <project> -o <output> [flags]

Flag	Description
`<project>`	Path to the project folder (containing `codescene.toml`).
`-o, --output <path>`	Output file (`.mp4`) or directory (with `--format png`).
`-s, --scene <name\|index>`	Render only this scene. Index is 1-based.
`--from <frame>`	First output frame to render (0-based, inclusive; default `0`).
`--to <frame>`	Stop before this output frame (exclusive; defaults to the end).
`--gpu`	Use the GPU backend (required for shaders/bloom).
`--bloom <n>`	Bloom intensity for the GPU backend.
`--crf <18–28>`	H.264 quality; lower is better/larger.
`--preset <p>`	ffmpeg speed preset (`ultrafast` … `veryslow`).
`--ssaa <1–4>`	CPU supersampling (anti-aliasing). Default 2.
`--format png`	Export numbered PNG frames instead of a video.
`-q, --quiet`	Minimal output.
`-v, --verbose`	Detailed output.

Scene selection is 1-based. -s 1 is the first scene; -s 0 errors.

The CPU backend renders each frame at ssaa× the output resolution and box- averages it down, which smooths every edge — strokes, glyphs, and rounded panels — and keeps camera zooms from shimmering or "crawling".

Value	Use
`1`	Native resolution, fastest. Edges may alias under zoom.
`2`	Default. The sweet spot — smooth, modest cost.
`3`–`4`	Final/hero exports. Sharper still, but `4×` renders 16× the pixels.

--ssaa applies to the CPU backend. The default of 2 is why fresh renders already look anti-aliased — pass --ssaa 1 to opt out, or --ssaa 4 for a final pass.

Quick previews with frame ranges

--from and --to slice the assembled output timeline by frame number. They do not select scene names; use --scene for that. The start is inclusive and the end is exclusive, so this renders frames 90 through 149:

cinecode render my-video --from 90 --to 150 -o preview.mp4

Examples

cinecode render my-video -o out.mp4
cinecode render my-video -s intro -o intro.mp4
cinecode render my-video -s 3 -o scene3.mp4
cinecode render my-video --from 90 --to 180 -o preview.mp4
cinecode render my-video -o final.mp4 --crf 18 --preset slow
cinecode render my-video -o effects.mp4 --gpu --bloom 0.8
cinecode render my-video -o hero.mp4 --ssaa 4 --crf 18 --preset slow
cinecode render my-video --format png -o frames/

`cinecode check`

Parse the manifest and all scene scripts and report errors without rendering. Beyond load errors (missing scene/source files, bad .ccs syntax, missing fonts), it reports per-scene warnings (zero-frame or empty scenes, mismatched dimensions, duplicate node ids) and whether ffmpeg is on your PATH.

cinecode check <project>

`cinecode dump-ir`

Build the project and print its Scene Document (the engine IR) as JSON — useful for debugging what the scripts produced, or for caching a built document.

cinecode dump-ir <project> [--scene <name|index>] [--output ir.json]

Flag	Description
`-s, --scene <name\|index>`	Limit to one scene.
`-o, --output <path>`	Write to a file instead of stdout.

`cinecode explain-frame`

Evaluate a single frame of a scene and print each node's resolved animation state (opacity, offset, scale, focus line, dim, highlight bar, typewriter / reveal progress, blur) plus the camera framing — a fast way to see exactly what the renderer "sees" at a moment, without producing pixels.

cinecode explain-frame <project> [--scene <name|index>] --frame <n>

Example output:

Scene "Run" (id scene_0) @ frame 80/210 (2.67s @ 30fps), 1280x720
Camera: none (identity framing, zoom 1.0)
Nodes (5):
  [code_2] code        op 1.00 focus L1.0 dim 0.55 bar 1.00 type 100%
  [var_3] text        op 0.00 scale 0.70  (hidden)

`cinecode preview`

Open an interactive window playing a scene, re-rendered on the CPU in real time (no SSAA, no MP4 encode) — the fast iteration loop.

cinecode preview <project> [--scene <name|index>]

Key	Action
`Space`	Play / pause
`←` / `→`	Step one frame back / forward (pauses)
`R`	Reload — re-run the scripts to pick up `.ccs` edits
`S`	Save the current frame as `preview_<scene>_<frame>.png`
`Esc`	Quit

Preview needs a display (it won't run headless). It previews one scene at a time — pass --scene to pick which. Saving a PNG uses ffmpeg.

`cinecode themes`

List available project and code highlight themes.

cinecode themes

`cinecode languages`

List the languages available for syntax highlighting.

cinecode languages