@agent-motion/cli

Create a structured Remotion project, then install editable, agent-ready components from the Agent Motion registry when you need them.

npx @agent-motion/cli create remotion my-remotion-video
npx @agent-motion/cli create remotion my-remotion-video --no-install
npx @agent-motion/cli scene from-image screenshot.png --name product-dashboard --cwd ./my-remotion-video --json
npx @agent-motion/cli list
npx @agent-motion/cli search "growth chart"
npx @agent-motion/cli suggest hook --intent "dashboard automation"
npx @agent-motion/cli info area-chart
npx @agent-motion/cli doctor --json
npx @agent-motion/cli add [email protected] --dry-run
npx @agent-motion/cli add [email protected]

create remotion scaffolds a neutral Remotion project with dedicated directories for assets, compositions, reusable components, and shared utilities. It installs dependencies by default. Pass --no-install for agents or CI that only need the project files, or --dry-run to inspect the file plan without writing. The older create <directory> form remains a deprecated compatibility alias.

Editable scenes from screenshots

scene from-image reconstructs a product UI screenshot as editable Remotion source. It creates a typed React component, a machine-readable scene.json, and a reference image under the target project's public assets:

# ./my-remotion-video/.env.local
OPENAI_API_KEY=...

Then preview and generate the scene:

npx @agent-motion/cli scene from-image screenshot.png \
  --name meeting-assistant \
  --cwd ./my-remotion-video \
  --dry-run \
  --json
npx @agent-motion/cli scene from-image screenshot.png \
  --name meeting-assistant \
  --cwd ./my-remotion-video \
  --json

Generated elements have stable data-agent-motion-id attributes. The component accepts layerStyles for frame-driven transforms and opacity, text for content overrides, and textProgress for deterministic typewriter reveals. The command does not choose animation timing; the calling agent applies the video's direction with useCurrentFrame(), interpolate(), and spring().

Readable text is reconstructed as editable text. Complex non-text graphics can remain exact crops of the reference image. Pass --dry-run to validate the image, project, target paths, and conflicts without sending the image or writing files. Existing scene files are never overwritten unless --force is explicitly passed.

Screenshot analysis uses the OpenAI Responses API and sends the supplied image to the configured API endpoint. The CLI automatically reads OPENAI_API_KEY, OPENAI_BASE_URL, and AGENT_MOTION_VISION_MODEL from <project>/.env.local. Process environment variables override that file, and --model has the highest priority for the model. The generated project template ignores .env.local in Git and includes a safe .env.local.example. Never pass a key as a CLI argument.

Add --json to any discovery command for ranked machine-readable results. Search responses include a relevance score and matchedBy evidence so an agent can explain why it selected a component.

Use suggest <beat> [--intent "..."] while turning a beat sheet into a scene plan. It returns several visual treatments plus ranked registry candidates for the 15 supported narrative beats: hook, context, problem, stakes, reveal, capability, mechanism, benefit, outcome, proof, differentiation, objection, offer, cta, and close. Compound beats such as hook/capability are supported.

Suggestions are advisory and many-to-many: a beat is a communication job, not a component name. Compare the candidates against the scene's actual message, inspect the selected component with info, and create a custom visual when it communicates the beat more clearly. Add --json for a structured result.

Run doctor before installation to check the target project's Remotion, React, TypeScript, source layout, package manager, and previously installed Agent Motion components.

Successful installs update .agent-motion/lock.json with the exact component version, registry source, and SHA-256 digest of every installed file.

Components are copied into src/remotion/components. The installer validates the target Remotion and React versions, verifies downloaded files with SHA-256, and refuses to overwrite existing files unless --force is explicitly passed.

Errors with --json have a stable, actionable shape:

{
  "ok": false,
  "error": {
    "code": "FILE_CONFLICT",
    "message": "Refusing to overwrite existing files.",
    "action": "Review the conflicting files. Run again with --force only after explicit approval.",
    "retryable": false,
    "details": {"files": ["src/remotion/components/area-chart/AreaChart.tsx"]}
  }
}

Agents should branch on error.code, show error.message to the user, follow error.action, and retry automatically only when error.retryable is true.

Registry and interactive previews: https://agent-motion.com