Installation

Get up and running with cmssy in under 5 minutes.

Last updated: March 31, 2026

Prerequisites

Before you begin, make sure you have the following installed on your machine:

  • Node.js 18+ — we recommend using nvm to manage versions
  • pnpm — our recommended package manager (npm and yarn also work)
  • Git — for version control and publishing

Install the CLI

Install the cmssy CLI globally to access all commands from your terminal:

Create a Project

Scaffold a new project with the init command. This creates the directory structure, installs dependencies, and sets up Tailwind CSS v4:

Project Structure

After running init, your project will look like this:

my-blocks/
├── src/
│   └── blocks/
│       └── hero/
│           ├── index.tsx      # Block component
│           ├── schema.ts      # Field definitions
│           └── defaults.ts    # Default content
├── cmssy.config.ts            # Project configuration
├── tailwind.config.ts         # Tailwind CSS config
├── tsconfig.json
└── package.json

Each block lives in its own folder inside src/blocks/. The CLI auto-discovers them based on this convention.

Configure API Access

Connect your local project to your cmssy workspace. You'll need your API token from the workspace settings dashboard:

Start Development

Launch the development server with hot-reload and live preview:

This starts a local server on http://localhost:3000 where you can:

  • Browse all blocks in your project
  • See a live preview with real-time hot reload
  • Edit block content in an interactive editor
  • Test responsive layouts across breakpoints

Publish Your Blocks

When you're ready to use your blocks in the cmssy page builder, publish them:

This validates, bundles, and uploads your blocks to the cmssy platform. They'll immediately appear in the block picker for your workspace.

Updating the CLI

To update to the latest version of the CLI:

Troubleshooting

Common issues

  • "Command not found: cmssy" — make sure the global npm/pnpm bin directory is in your PATH
  • "Authentication failed" — re-run cmssy configure and verify your API token is correct
  • "Port 3000 already in use" — stop any other dev servers or use cmssy dev --port 3001
  • Node.js version error — upgrade to Node.js 18+ using nvm install 18

Next Steps

Now that you're set up, explore the following guides:

  • Quickstart — build and publish your first block end-to-end
  • Blocks — understand block anatomy, schemas and field types
  • Templates — compose blocks into full-page templates
Terminal
400">"text-violet-400">npm install -g cmssy-cli
 
500"># or with 400">"text-violet-400">pnpm
400">"text-violet-400">pnpm add -g cmssy-cli
 
500"># Verify installation
cmssy --version
Using npx

You can also use npx cmssy-cli without installing globally. This is useful for CI/CD pipelines or one-off commands.

Terminal
cmssy init my-blocks
 
500"># Follow the prompts:
500"># ? Project name: my-blocks
500"># ? Template: Default (Hero + Features blocks)
500"># ? Package manager: 400">"text-violet-400">pnpm
 
400">"text-violet-400">cd my-blocks
Terminal
cmssy configure
 
500"># ? Workspace API token: ••••••••••••••••
500"># ✓ Connected to workspace "My Workspace"
500"># ✓ Configuration saved to cmssy.config.ts
Where to find your API token

Go to your workspace Settings → API in the cmssy dashboard. Create a new token with blocks:write permission. Keep this token secret - never commit it to version control.

Terminal
cmssy dev
 
500"># ✓ Found 2 blocks: hero, features
500"># ✓ Dev server running at http:500">//localhost:3000
500"># ✓ Watching for changes...
Terminal
cmssy publish
 
500"># ✓ Validating blocks...
500"># ✓ Building hero (1/2)
500"># ✓ Building features (2/2)
500"># ✓ Published 2 blocks to workspace "My Workspace"
Version bumping

Each publish increments the block version automatically. Previously published versions remain available so existing pages won't break. You can pin a specific version in the page builder.

Terminal
500"># 400">"text-violet-400">npm
400">"text-violet-400">npm update -g cmssy-cli
 
500"># 400">"text-violet-400">pnpm
400">"text-violet-400">pnpm update -g cmssy-cli
 
500"># Check current version
cmssy --version