---
title: Installation
description: Install and run Motionly locally.
---

# Installation

Motionly runs from npm through `npx` — no clone and no global install. You need Node.js `20.19.0` or newer.

## Create a project

```bash
npx @coppsary/motionly init my-video
```

`init` scaffolds the project and asks which agent you're using, then installs the Motionly agent skill for that agent (or pick "All supported agents"). Supported agents are **Codex, Claude Code, Gemini CLI, opencode, and Kiro**. The install is not a single file: it writes the `SKILL.md` contract plus a full `references/` library (`motion-dsl`, `svg`, `animation`, `easing`, `camera`, `composition`, `typography`, `transitions`, `timeline`, `assets`, `rendering`, `templates`) with an `llms.txt` discovery index.

Skip the prompt with flags (also used in scripts and non-interactive shells):

```bash
npx @coppsary/motionly init my-video --provider opencode   # one agent, no prompt
npx @coppsary/motionly init my-video --all                 # every supported agent
npx @coppsary/motionly init my-video --skip-skills          # no agent skills
```

Provider names are `codex`, `claude`, `gemini`, `opencode`, and `kiro`. Use `--scope project` (default) or `--scope global`.

After setup Motionly starts the project and prints `http://localhost:4173/editor`. Press `Ctrl+C` to stop it, then reopen later with:

```bash
cd my-video
npx @coppsary/motionly dev
```

## Add skills to an existing project

```bash
npx @coppsary/motionly skills add                       # pick scope and agents
npx @coppsary/motionly skills add --all --scope project
npx @coppsary/motionly skills add --provider codex --scope global
```

Each install includes the same `references/` library. Re-running keeps existing files and never overwrites your edits. After installation, start an agent request with `/motionly`, for example: `/motionly inspect my assets and create an editable Motionly animation`.

## Open the editor with no project

```bash
npx @coppsary/motionly
```

This serves the editor at `http://localhost:4173`. Use `--port <n>` to pick a port or `--no-open` to skip launching the browser.

The local editor reads and saves `project.motion` and serves files from `assets/`. Asset imports are
resolved by filename, so the same import works with local media or a browser upload. Motionly asks
before replacing a filename match whose size or dimensions differ significantly.

## Requirements

- Node.js `20.19.0` or newer
- npm
- FFmpeg installed and available on `PATH` for MP4 export
- A modern Chromium-based browser for best MP4 export support

## Install From Source

```bash
git clone https://github.com/COPPSARY/Motionly.git
cd Motionly
npm install
```

## Run

```bash
npm run dev
```

Open the local Vite URL in your browser.

## Build

```bash
npm run build
```

## Serve The Production Build

```bash
npm run serve
```

This runs the same launcher `npx @coppsary/motionly` uses against your local `dist/`.

## Test

```bash
npm run build
npm run test:run
```