# Install the genmotion CLI

> Install the genmotion CLI with npm and Node 22. Scaffold a video project with npx @genmotion/cli init, preview it live, and render MP4 on macOS, Linux or CI.

Source: https://genmotion.dev/docs/install-cli

The `genmotion` CLI is the app-free way to make videos: scaffold, preview, check and render from a terminal, plus an MCP server for coding agents. It's open source under Apache-2.0 and needs no account.

## Requirements

- **Node 22 or newer.** Check with `node --version`.
- **macOS or Linux.** CI runners work too.
- Nothing else. A headless Chromium and ffmpeg download on the first render.

## Create a project

### 1. Scaffold it

```sh
npx @genmotion/cli@latest init my-video
```

`npm create genmotion@latest my-video` does the same thing.

### 2. Install dependencies

```sh
cd my-video
npm install
```

The project pins its own copy of `@genmotion/cli`, so `npm run` scripts and `npx @genmotion/cli` use the same version.

Want `genmotion` without `npx`, everywhere? Install it globally:

```sh
npm install -g @genmotion/cli
```

That is the same command GenMotion Studio installs. If the Studio is on this Mac, `genmotion .` opens the current folder in it.

::: note
The package is `@genmotion/cli` and the command it installs is `genmotion`. Inside a project, `npm run dev` and the other scripts call `genmotion` directly; elsewhere, `npx @genmotion/cli <command>` runs it without installing anything.

### Run it

```sh
npm run dev       # live studio at http://localhost:4200
npm run check     # compile and headless-render every scene
npm run render    # exports/my-video.mp4
```
:::

## `init` options

| Flag | What it does |
| --- | --- |
| `--size <size>` | `landscape` (1920×1080, default), `portrait` (1080×1920), `square`, `4k`, or `WIDTHxHEIGHT` |
| `--fps <n>` | Frame rate. Default 30 |
| `--template <id\|path>` | Start from a catalog template or a local project folder |
| `--engine <three\|react>` | Scene runtime. Default `three` |
| `--name <name>` | Display name. Default: the folder name |
| `--yes`, `-y` | Never ask a question |
| `--json` | Print one JSON object, for scripts and agents |

```sh
npx @genmotion/cli init reel --size portrait --fps 60
npx @genmotion/cli init launch --template crypto-launch-video
```

## Check your machine

```sh
npx @genmotion/cli doctor
```

It checks Node, ffmpeg, Chromium and WebGL, and prints the fix for anything missing.

> **Note:** The CLI renders Three.js and React projects. HyperFrames projects open in [GenMotion Studio](https://genmotion.dev/docs/install-studio).

## Render in CI

Rendering is deterministic: the default software WebGL produces the same pixels on every machine. A project needs no extra setup to render in a CI job. This is the workflow the [starter repo](https://github.com/haxzie/genmotion/tree/main/examples/three-starter) ships with:

```yaml title=".github/workflows/render.yml"
name: Render
on: [push]
jobs:
  render:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install
      - run: npx @genmotion/cli check
      - run: npx @genmotion/cli render
      - uses: actions/upload-artifact@v4
        with:
          name: video
          path: exports/
```