CLI commands

Run any command with npx @genmotion/cli <command> from anywhere inside a project. --help prints a command's options.

JSON output#

Every command accepts --json and prints exactly one JSON object on stdout. Progress goes to stderr. This is how agents and scripts read results.

{ "ok": true, "output": "/path/to/my-video/exports/my-video.mp4", "width": 1920, "height": 1080, "frames": 270, "durationSeconds": 9 }

Failures say what went wrong and how to fix it, and exit with code 1:

{ "ok": false, "error": { "message": "Not inside a GenMotion project (no project.json here or above)", "fix": "npx @genmotion/cli init my-video && cd my-video" } }

Commands#

dev#

npx @genmotion/cli dev --open

The studio plays, scrubs and steps frames under a timeline: a ruler, the scene track, and every audio lane from project.json with its waveform. Click or drag anywhere on the timeline to seek, and click a scene to jump to its start. Audio plays in sync with the picture, with each clip's volume, fades and mute applied as the render mixes them; m turns the sound off.

Two buttons sit at the top right. Export MP4 runs the same render as render, saves it in exports/ and downloads it through your browser; click it again while it runs to cancel. Edit in studio opens the project in the GenMotion app, or links to the download when the app isn't installed.

Saving a file reloads the studio at the frame you were on, so the timeline updates as your agent adds scenes and audio. Editing happens through the agent or the audio command, not by dragging.

check#

Runs, in order: project.json parses and every scene exists; every scene compiles and follows the determinism rules; every scene renders its first, middle and last frame in headless Chromium without throwing, logging errors or drawing an empty frame.

still#

npx @genmotion/cli still --at 0 --at 50% --at 100%

scene add#

npx @genmotion/cli scene add "Hero reveal" --duration 4s --after intro

audio#

npx @genmotion/cli audio add assets/music.mp3 --fade-in 0.5s --fade-out 1s --volume 0.3
npx @genmotion/cli audio add https://example.com/whoosh.mp3 --at 4s
npx @genmotion/cli audio set music --at 1s --duration 8s
npx @genmotion/cli audio remove whoosh-3f2a
npx @genmotion/cli audio list

add takes a file inside the project, or a URL, which is saved into assets/ first. Clips go on up to four lanes, and a clip never overlaps another on its own lane: add picks a free lane, and a clip that would run into the next one is shortened (the result says so). set and remove take a clip's id or its --name.

Times use the same spellings as everywhere else: 48 (frames), 2s, 500ms, and 50% for --at.

x-video#

npx @genmotion/cli x-video https://x.com/someone/status/1988283207138324487

Takes the link to the post, not a media URL: the MP4 sits behind an id only the post knows. The post is resolved through X's own embed endpoint, so there is no key, no account and no login, and the file comes straight from X into assets/.

--quality smallest takes the lowest rendition instead of the best, which is what you want for a clip that plays inside a phone mock. --index <n> picks one video out of a post that carries several, and --filename <name> overrides the default x-<handle>-<quality>.mp4.

An animated GIF comes back as a silent MP4, which is what X stores. The clip's own audio is not mixed into a render: pull it out with ffmpeg and place it with audio add if it matters.

skills#

See Skills.

mcp#

npx @genmotion/cli mcp [--dir <project>]

Speaks MCP over stdio. Never writes anything else to stdout. See MCP tools.

Environment variables#