Skip to main content

​
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

Run it in the project root. It installs: 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. 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

Swap @clayzo/webgl-player for @clayzo/canvaskit-player if you want the full-fidelity player. See Choosing a renderer. To install the CLI once for your machine instead of in each project, replace the dev dependency with:

​
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.

​
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:
It shows what is behind and asks before changing anything. See doctor and update. 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:
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.