Skip to Content
Automation APIThe CLI (local renders)

The CLI — headless renders

Render a .motion project to a file without opening the editor. The app executable is the command line:

Premation render Promo.motion --comp Main --out promo.mp4

It drives the same deterministic frame loop, the same GPU render graph and the same ffmpeg encode the Export dialog uses. There is no second renderer that can drift out of step — the file the CLI writes is the file the editor would have written.

This page is the local, on-your-machine sibling of the hosted Automation API: same idea, no server, no account.

The four commands

CommandWhat it does
render <project>Renders one composition to one file. With no --out, writes beside the project (Promo.motion → Promo.mp4).
reframe <project> --aspect 9:16Auto-reframes the composition to another shape, then renders it. Aspects: 9:16, 1:1, 4:5, 16:9, 4:3.
captions <project> --out subs.srtTranscribes the composition’s audio to .srt or .vtt. Needs an OpenAI key in the desktop keystore.
comps <project>Lists the compositions — name, size, fps, duration, id — so a script can discover what to render.

To burn subtitles into a render, pass --captions subs.srt to render.

The options you will actually use

premation render Promo.motion \
  --comp Main --range 0-119 --scale 0.5 --format webm --transparent \
  --out preview.webm
OptionMeaning
--comp <name|id>Which composition. Matched by id, then exact name, then case-insensitively.
--formatmp4, mov, webm, gif, hdr10, hlg, png-sequence, jpg-sequence, exr-sequence, png. Usually inferred from --out.
--range 0-119Inclusive frame range.
--scale / --width / --heightOutput size. One dimension keeps the aspect.
--qualityhigh (default), medium, draft.
--proresmov only: proxy, lt, 422, hq, 4444.
--transparentForce an alpha channel on.
--jsonOne JSON object per line, for scripts.
--quiet / --log <file>Silence progress / mirror output to a file.

--out overwrites. The in-app Render Queue never does — it suffixes (2) to protect files — but a pipeline needs its artifact at a known path, so the CLI takes the opposite side of that trade.

Batch renders from a spreadsheet

Author one composition, expose the layers you want driven as template fields, and render one file per row:

premation render LowerThird.motion --data people.csv --out "out/{index}-{name}.mp4"
name,role
Ada Lovelace,Mathematician
Grace Hopper,Rear Admiral

Columns fill the template fields with the same id; extra columns are ignored; missing columns keep the authored value. --from-row 40 resumes a crashed batch without re-rendering the first 39. The --out pattern must contain a {token} so rows cannot overwrite each other — the CLI refuses to run otherwise.

Good to know

  • A window flickers open on some platforms — that is normal. The renderer is a real browser pipeline (real fonts, real video elements), so a headless render is the actual engine in a hidden window, not a lookalike. That is what guarantees CLI pixels match preview pixels.
  • Exit codes are honest. A bad command line exits 2 immediately — a typo does not cost a GPU boot to discover. A silent composition passed to captions is reported, not written out as an empty file.
  • It runs while the editor is open. Each render is its own process.
Last updated on
OverviewQuickstart