> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clayzo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Requirements, what the initializer installs, and how to install by hand.

## Requirements

* Node.js 22.13 or newer.
* npm, pnpm, Yarn or Bun.
* A browser on the machine, for signing in and for `clayzo preview`.
* For playback on your site: a browser with WebGL2, which is every current browser.

Nothing else. The CLI carries everything it needs to render frames and video locally, so you don't install a renderer separately and your website never ships it unless you choose the CanvasKit player.

## The initializer

```bash theme={null}
npx clayzo@latest init
```

Run it in the project root. It installs:

| Installed | As | Purpose |
| - | - | - |
| `@clayzo/animation` | dependency | Types, builders, validation and packaging used by authoring scripts |
| `@clayzo/webgl-player` | dependency | Plays documents on your site |
| `clayzo` | for your whole machine, or a dev dependency | The CLI |

Then it runs `npx skills add clayzo/agent-skills` to install the two Clayzo skills for your agent.

Interactively it asks three questions: whether to also install `@clayzo/canvaskit-player` for full-fidelity playback, whether to install the skills, and whether to install the CLI for your whole machine so every project can use it. Without a terminal, or with `--yes`, it takes the defaults, which add the CLI to the project as a dev dependency.

| Flag | Effect |
| - | - |
| `--renderer webgl` | Install only the WebGL player (default) |
| `--renderer canvaskit` | Install only the CanvasKit player |
| `--renderer both` | Install both players |
| `--renderer none` | Install no player, for projects that only export |
| `--global` | Install the CLI for your whole machine |
| `--local` | Add the CLI to the project as a dev dependency |
| `--no-skills` | Skip the agent skills |
| `--yes` | Accept every default without prompting |
| `--dry-run` | Print the commands instead of running them |

If the machine-wide install fails, for example because npm can't write to its global folder, the initializer adds the CLI to the project instead and says so.

The initializer prints the commands it runs, then a JSON summary on stdout.

## Installing by hand

<CodeGroup>
  ```bash npm theme={null}
  npm install @clayzo/animation @clayzo/webgl-player
  npm install --save-dev clayzo
  npx skills add clayzo/agent-skills
  ```

  ```bash pnpm theme={null}
  pnpm add @clayzo/animation @clayzo/webgl-player
  pnpm add --save-dev clayzo
  npx skills add clayzo/agent-skills
  ```

  ```bash yarn theme={null}
  yarn add @clayzo/animation @clayzo/webgl-player
  yarn add --dev clayzo
  npx skills add clayzo/agent-skills
  ```

  ```bash bun theme={null}
  bun add @clayzo/animation @clayzo/webgl-player
  bun add --dev clayzo
  npx skills add clayzo/agent-skills
  ```
</CodeGroup>

Swap `@clayzo/webgl-player` for `@clayzo/canvaskit-player` if you want the full-fidelity player. See [Choosing a renderer](/playback/choosing-a-renderer).

To install the CLI once for your machine instead of in each project, replace the dev dependency with:

```bash theme={null}
npm install --global clayzo
```

## iOS and macOS

Native playback in Swift apps is a Swift package, not an npm package. Add `https://github.com/Clayzo/clayzo-swift` in Xcode and play the same documents and bundles the CLI produces. See [iOS and macOS](/playback/ios).

## Versions

All Clayzo packages are released together and share one version number, the Swift package included. Install matching versions and upgrade them together.

When the CLI on your machine, your project's Clayzo packages or the agent skills fall behind the current release, every command says so in one line on stderr. One command updates all of them:

```bash theme={null}
npx clayzo update
```

It shows what is behind and asks before changing anything. See [doctor and update](/cli/doctor). When a CLI version falls below the minimum the service supports, protected commands stop with a `CLAYZO_VERSION_UNSUPPORTED` error and the command to run.

## Running the CLI

With the CLI installed for your machine, run it from anywhere:

```bash theme={null}
clayzo --help
```

Every example in these docs uses `npx clayzo`, which works either way: it runs the project's CLI when the project has one, and the one installed for your machine otherwise. With pnpm, `pnpm clayzo` works too, and `npx clayzo@latest` runs the newest release without installing it.

A project that has `clayzo` as a dev dependency keeps its version. The CLI installed for your machine hands `preview`, `render-frame`, `review`, `package` and `export` to the project's CLI, so everyone working on the project, and its CI, renders with the same version.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.