@devmotion/cli

DevMotion Local Studio. The DevMotion editor, renderer and MCP server, running on a project folder on your machine. Generation (voiceover, images, video, music, captions, dubbing…) and the DevMotion chat run on devmotion.app with your account; the chat can also drive the Claude Code or Codex you already have installed.

npx @devmotion/cli init my-video
cd my-video
npx @devmotion/cli          # opens the Studio in your browser

Install

npm i -g @devmotion/cli     # then: devmotion …
# or without installing
npx @devmotion/cli <command>

Requires Node.js ≥ 20. ffmpeg ships with the package (@ffmpeg-installer/ffmpeg), and a postinstall step downloads Playwright Chromium (~150 MB, once) for rendering. Skip it with DEVMOTION_SKIP_POSTINSTALL=1; devmotion render fetches it on first use.

Commands

| Command | Purpose | | ------------------------------------------------------------- | --------------------------------------------------------------------- | | devmotion | Open the Studio on the project in this folder (or show help) | | devmotion init [dir] [--name] [--size 1920x1080] [--fps 30] | Create a project, .gitignore and agent setup (--no-agent to skip) | | devmotion studio [dir] [--port 4747] [--no-open] | Run the Studio: editor, renderer and MCP server (alias preview) | | devmotion render [dir] [-o file.mp4] [--port] | Render to renders/ (uses the running Studio or starts one) | | devmotion login / logout / whoami | Your devmotion.app account: generation credits and the cloud chat | | devmotion doctor | Check ffmpeg, Chromium, login, server compatibility and local agents |

| devmotion render --changed [-c config] | Render only stale/missing/modified targets, update the lock | | devmotion render --all / --target a,b / --watch | Render every / chosen targets; re-render a target when it changes | | devmotion check [-c config] | No render: exit 1 listing stale, missing or modified targets | | devmotion lock [-c config] | Record the current outputs in the lock without rendering |

The Studio listens on 127.0.0.1:4747 by default — one port, one project. Run a second project with --port.

Render targets and the lock

Declare outputs once in devmotion.config.json (paths relative to the file). Several targets can share a project; a variant is a target with other values or range.

{
  "version": 1,
  "lock": "devmotion.lock.json",
  "targets": {
    "intro": {
      "source": "videos/intro",
      "values": { "headline": "Hello" },
      "range": { "start": 0, "end": 8 },
      "audio": false,
      "encode": { "crf": 23, "maxCrf": 35, "maxBytes": 1572864 },
      "output": "public/intro.mp4",
      "poster": { "path": "public/intro.jpg", "time": 5 }
    }
  }
}

devmotion render --changed hashes every target and renders only those that need it. A target's sourceHash is the sha256 over its project files (sorted; renders/, .devmotion/, node_modules/ excluded), values, range, audio, encode, poster time and the renderer version (CLI major.minor). devmotion.lock.json is committed:

{
  "lockVersion": 1,
  "renderer": "1.1",
  "targets": {
    "intro": {
      "sourceHash": "<sha256>",
      "outputs": { "public/intro.mp4": { "sha256": "<sha256>", "bytes": 123456 } }
    }
  }
}

A target is stale when its hash differs or it is not locked, missing when an output is gone, and modified when an output's checksum differs from the lock. devmotion check runs in CI with no renderer installed. After a minor CLI upgrade, run devmotion render --changed (or devmotion lock if the outputs are unchanged).

Programmatic use: import { loadConfig, readLock, checkTargets, recordTarget, writeLock } from '@devmotion/cli' (same as @devmotion/cli/lock).

Project folder

my-video/
├── project.json        # the project (the same JSON devmotion.app stores)
├── scenes/<layerId>/   # HTML / CSS / script sources of scripted scenes
├── assets/             # your media, referenced as /local-assets/<path>
├── renders/            # rendered MP4s
└── .devmotion/         # local state (chat history, cloud cache) — not versioned

Edit in the Studio, with an agent, or by hand: the Studio reloads when files change. Scene sources are plain files (index.html, style.css, script-<n>.js), referenced from project.json as { "$file": "scenes/<layerId>/index.html" }.

Agents (MCP)

The Studio serves the DevMotion MCP server at http://127.0.0.1:4747/mcp — the same tools as devmotion.app (get_design_guide, get_project, upsert_layer, write_layer_source, instantiate_block, inspect_frames, action_*…), writing to the project folder. devmotion init writes the config for Claude Code (.mcp.json) and Codex (.codex/config.toml), plus a short skill. Keep the Studio running while the agent works.

Cloud features

devmotion login opens devmotion.app to create an API key for this machine (stored in ~/.config/devmotion/credentials.json). Then everything generative in the Studio and in the MCP action_* tools runs on devmotion.app with your plan's credits; inputs are uploaded once and results are downloaded into assets/generated/. Your project stays local.

Environment overrides: DEVMOTION_API_KEY (use this key) and DEVMOTION_API_URL (another DevMotion server).

Chat

The chat panel offers the DevMotion cloud models (needs login) and, when installed and logged in on your machine, Claude Code and Codex: the Studio runs them against its own MCP server, and the editor follows their edits live.

License

Apache-2.0. See LICENSE.