Copy page

Reference

CLI

The recit command is provided by @recit/cli:

Bash
pnpm add -D @recit/cli
npx recit --help

Commands

The file defaults to slides.md (story.md for init --format motion); .mdx and JSON stories (kind: "story") are accepted everywhere. The motion commands (render, dur, and dev, convert, validate on a motion story) also accept a motion render model (<name>.film.json).

Options

Examples

Bash
npx recit init talk.md --config
npx recit dev talk.md --port 4000 --open
npx recit build talk.md -o public/talk --base /talk/
npx recit export talk.md --notes --theme light -o talk.pdf
npx recit export talk.md --html -o talk.html
npx recit convert talk.md -o talk.json
npx recit validate talk.json talk.md
npx recit build talk.md --locale fr -o dist/fr
npx recit i18n extract talk.md --locale de
npx recit i18n check

Motion:

Bash
npx recit init --format motion
npx recit dev story.md
npx recit validate story.md
npx recit dur story.md
npx recit render story.md --aspect 1:1 --output out/
npx recit convert film.json -o story.md
npx recit convert story.md --to film -o film.json
npx recit extract handover scenes.json -o story.md
npx recit schema motion-film -o film.schema.json
claude mcp add recit -- npx recit mcp serve

JSON and languages

Every Markdown story has a typed JSON equivalent. recit convert writes it in its canonical form, with a $schema (https://recit.dev/schema/v1/<format>.json) for completion in editors. Both compile to the same story, scene ids included.

Next to talk.md:

• talk.json with "kind": "sidecar" completes the story by scene id (fields, data, strings inserted with :t[key]);
• in a multilingual project (an i18n section in recit.config), talk.fr.md is the French variant and talk.fr.json a French companion. A missing language falls back to the default one.

recit i18n check fails when a variant has missing, extra or reordered scenes, or different structural attributes (layout, cols…). Text identical to the default language is a warning, an error with --strict or i18n.strict. Without an i18n section, there is nothing to check.

Motion

A motion story (format: motion, see Motion) is written in Markdown, in its typed JSON, or as a motion render model (<name>.film.json). Every command reads them the same way, through parseDeck, so an error names the line of the scene (story.md:14 (stat): label is required) or its JSON pointer.

• recit dev story.md opens a browser preview that plays the film with the blocks engine of @recit/motion-blocks and the scene timing of recit dur. Space plays or pauses, ← and → change scene, R restarts, F goes full screen. Saving the story or recit.config reloads it in place. Relative media (src: assets/logo.svg) load from the story folder. ?scene=<n or id> opens a scene, ?settled=1 shows its final state, paused.
• recit render loads @recit/motion-render on demand. It pulls in Remotion and a headless Chrome, so it is an optional package: install it next to the CLI (pnpm add -D @recit/motion-render). Without it, recit render says what to install.
• recit mcp serve starts the server of @recit/mcp, also optional, on stdio. Its tools read and write only inside one root — the current directory, or --root <dir>. A path that climbs out of it, points at a hidden file or has an unexpected extension is refused: an agent acts on content it did not write, so a path it passes is untrusted input.
• recit convert writes a film.json as its canonical Markdown story: the whole story is regenerated, so comments and layout are not kept.

Exit codes

The exit code is 1 when the file is missing, compilation fails, the port is busy, Playwright is missing (PDF), an optional package is missing (render, mcp serve), build hits a blocking density error (see Density rules), or validate and i18n check find an error.