tweens-cli

Tweens local motion engine

Create editable animations through a CLI or an MCP client. No app window, model API key, account, or WebMCP-enabled browser is required for authoring. Rendering uses isolated headless Chromium and the same evaluator, artwork adapter, GIF encoder and MP4 encoder as the editor.

Package: tweens-cli. The repository's visibility and proprietary license remain unchanged. server.json carries the separate MCP Registry metadata. Public setup does not require access to the source documentation.

After the npm release is visible, install the pinned version with npm install -g tweens-cli@0.1.0. Do not use an unpinned package version in automated setups.

Build and run today

Use Node.js 22 LTS or newer. From a checkout of the repository:

npm ci
npm run build --workspace tweens-cli
npx playwright install chromium
mkdir -p work/my-animation
node packages/cli/dist/cli.mjs tools
node packages/cli/dist/cli.mjs call create_project '{"file":"demo.tweens"}' --workspace work/my-animation
node packages/cli/dist/cli.mjs call get_editor_state '{"file":"demo.tweens"}' --workspace work/my-animation

Use IDs from the read result, never names or guessed IDs. Every edit needs file, revision, compositionId, and any state/layer IDs in its schema. Use the returned revision for the next edit. Inspect a particular state by passing stateId to get_editor_state; this read does not change anything.

tweens call TOOL @arguments.json --workspace DIRECTORY reads a JSON argument file (up to 1 MiB), useful for batches. --workspace=DIRECTORY is also supported. CLI results are JSON on stdout; failures set a nonzero exit code. No command executes JavaScript supplied by an agent.

Connect an MCP client

Add a stdio server using absolute paths. This is a generic MCP configuration example; your client's settings format may differ:

{
  "mcpServers": {
    "tweens": {
      "command": "/absolute/path/to/node",
      "args": [
        "/absolute/path/to/tweens/packages/cli/dist/cli.mjs",
        "mcp",
        "--workspace",
        "/absolute/path/to/animation-workspace"
      ]
    }
  }
}

Grant a dedicated, existing directory, not your home directory. The engine does not install itself in any client. It exposes 20 tools through tools/list, with JSON Schema validation and structured results. Stdio stdout contains only protocol messages; diagnostic logging goes to stderr. It does not start an HTTP MCP endpoint.

The authoring loop

• list_projects or create_project; then get_editor_state.
• create_layer for rectangles, ellipses, polygons, stars or text; set_background for a solid state background.
• create_state duplicates an existing state. Copies preserve stable identity so they animate together. Do not independently recreate matching layers by name.
• Change the destination with move_layer, resize_layer, rotate_layer, style_layer or reorder_layer. tweens_transform combines supported transform fields.
• Use set_transition_duration and set_easing for the motion. tweens_media_timing edits supported timing on already imported media.
• apply_commands makes up to 64 edits atomically. Commands inherit scope and revision; omit both inside each command. Newly created IDs are returned for subsequent calls, not referenced symbolically inside that batch.
• validate_project; render_preview at the start, midpoint and end. Look at the returned images, not just a success flag.
• Make targeted repairs, re-render, then export_animation to GIF or MP4. Every output needs a new filename.
• Open the .tweens file in the app for human review and finishing. Right-click the blank canvas → Open .tweens project…, or drop the file on the canvas. Save .tweens project downloads the editable document. Opening is undoable; autosave is still browser-local. The app does not live-sync the disk file.

Example prompt for a connected agent:

Use Tweens to make a 1.5-second blue geometric logo reveal with a short headline. Create a Start state, duplicate it, and use the same layer IDs in the end state. Inspect the start, midpoint and end PNGs and repair any clipping or overlap you observe. Export a GIF and MP4 plus the editable .tweens project. Ask before replacing any of my existing work.

render_preview returns inline PNG content to image-capable clients and a local file. Exports return the artifact path and dimensions. Validation checks schema, references, limits and evaluation at the requested time; it does not certify visual quality, all timestamps or every codec.

Safety and limits

• Basename-only .tweens files in the chosen directory; no recursive browsing, symlink reads, remote assets, arbitrary URLs, shell or JavaScript tools.
• Document size ≤20 MiB, ≤16 compositions, ≤1000 canonical nodes across the project, ≤100 states per composition, dimensions ≤4096px, duration ≤120 seconds per composition. Projects above these bounds remain a web-editor workflow.
• Artifact size ≤64 MiB; output ≤1280px; integer FPS 1–30; render runtime ≤2 minutes. Chromium is launched only for preview/export and closed afterward.
• Mutations use optimistic disk revisions, an exclusive cooperating-writer lock and atomic file replacement. Stale input and failed batches do not save partial edits. This is not an OS-level compare-and-swap against unrelated programs ignoring the lock.
• Existing artifact/project names are not overwritten on creation. delete_state is separate and requires confirmation; deleting the first state retains its frame but empties its contents. There is no project-file deletion tool.
• One operation at a time; serialize requests. MCP cancellation aborts before commit where possible and closes in-flight Chromium. Cancellation racing an already completed disk commit does not undo it: re-read the file to determine the outcome. Do not blindly repeat writes after an uncertain response.
• A crashed process may leave a .lock file. Confirm no writer remains before manually removing that specific lock. The engine never guesses it is stale.
• The in-memory engine supports transactional undo, but the file MCP adapter has no persistent history tool. Keep backups or use source control for important documents.
• No unattended publishing/upload, asset URL import, remote server, embedded model, or AI taste scoring. New nested compositions, vector editing, masks and advanced asset authoring are not exposed as commands yet. Existing supported document content still uses the shared renderer.
• Local fonts vary by machine. GIF is silent. MP4 requires Chromium H.264 support; sound additionally needs AAC support. Media must be embedded in the project; external network requests are blocked. TWEENS_CHROME can point to a compatible installed Chrome executable.

Verification and release

From the repository root, npm run test:agents tests a real MCP client and real PNG/GIF/MP4 exports. With TWEENS_TEST_URL set to a local development server it also tests browser import and undo/redo. Outputs stay in work/.

npm pack --workspace tweens-cli --pack-destination work builds a distributable tarball including the engine, renderer and dependency notices. Install that exact tarball to test it outside the monorepo. See the engine and distribution plan before npm/Registry publication or a Homebrew tap.