CLI Command Reference

Overview

The Cmssy CLI (@cmssy/cli) is a command-line tool for building, previewing, and publishing custom UI blocks to Cmssy workspaces. Install it globally:

npm install -g @cmssy/cli

cmssy init

Initialize a new Cmssy project with scaffolded structure.

cmssy init [name] [options]

Arguments:

• name — Project directory name (optional, prompts if omitted)

Options:

• -f, --framework <framework> — Framework: react (default), vue, angular, vanilla

• -y, --yes — Skip prompts, use defaults

Example:

cmssy init my-blocks
cmssy init my-blocks --framework react --yes

Creates: Project directory with cmssy.config.js, package.json, tsconfig.json, example hero block, styles, and configuration files.

cmssy link

Connect the current project to a Cmssy workspace. Interactive by default: picks the workspace, accepts the API token, and writes CMSSY_API_URL, CMSSY_API_TOKEN, and CMSSY_WORKSPACE_ID to .env.

cmssy link [options]

Options:

• --token <token> — API token (non-interactive, must start with cs_)

• --workspace <id|slug> — Workspace to link to (non-interactive)

• --api-url <url> — Override API endpoint (default: https://api.cmssy.io/graphql)

Examples:

cmssy link
cmssy link --token cs_xxx --workspace my-workspace-slug
cmssy link --api-url https://api.cmssy.dev/graphql

Tokens come from workspace Settings → API Tokens. List accessible workspaces with cmssy workspaces.

Renamed from the old configure command in 0.12.

cmssy create block

Create a new block within your project.

cmssy create block <name> [options]

Arguments:

• name — Block identifier (kebab-case, e.g., hero-section)

Options:

• -y, --yes — Skip prompts

• -d, --description <text> — Block description

• -c, --category <category> — Category: marketing, typography, media, layout, forms, navigation, other

• -t, --tags <tags> — Comma-separated tags

Example:

cmssy create block pricing-table -c marketing -t "pricing,plans" -y

Creates: blocks/<name>/ with config.ts, package.json, preview.json, and src/ directory.

cmssy create template

Create a new page template.

cmssy create template <name> [options]

Options:

• -y, --yes — Skip prompts

• -d, --description <text> — Template description

Creates: templates/<name>/ with template configuration and page blueprints.

cmssy dev

Start development server with live preview.

cmssy dev [options]

Options:

• -p, --port <port> — Port number (default: 3000)

Features:

• Generates Next.js dev app in .cmssy/dev/

• Hot reload on file changes

• Preview UI for all blocks with preview.json data

• Auto-detects new blocks

• 4GB Node memory allocation

cmssy build

Build all blocks and templates for production.

cmssy build [options]

Options:

• --block <names...> — Build specific blocks only

• --framework <framework> — Override framework from config

Process:

1. Scans blocks/ and templates/ directories

2. Validates config.ts and schema

3. Builds in parallel (concurrency: 8) using esbuild

4. Generates TypeScript types from schema

5. Compiles CSS with Tailwind (v3/v4 auto-detection)

6. Outputs to public/@vendor/package-name/version/

Example:

cmssy build
cmssy build --block hero pricing

cmssy publish-block

Publish a single block to a workspace via the sandbox build pipeline (Vercel Sandbox + Inngest). The CLI tar.gz's the block source tree, uploads it to the backend, which enqueues a build job that bundles the block and writes the artifacts back to Vercel Blob.

cmssy publish-block <name> [options]

Arguments:

• name — Block directory name under blocks/

Options:

• -w, --workspace [id] — Workspace id (defaults to CMSSY_WORKSPACE_ID from .env)
• --entry <path> — Entry path inside block dir (default: src/index.tsx)
• --dry-run — Collect files and print the plan without uploading

Example:

cmssy publish-block hero                   # publish to workspace from .env
cmssy publish-block hero -w 65f...         # override workspace
cmssy publish-block hero --dry-run         # see what would be sent

Limits: 200 files / 10 MB total per block. Build polling: 1.5 s interval, 10 minute cap, gives up after 5 consecutive errors.

The legacy cmssy publish command + the --zip / --patch / --minor / --major / --overwrite-content / --force / --with-source / --all flags were removed in CMS-606. Versioning is handled by the build pipeline.

cmssy publish-template

Publish a single template (page tree + content) to a workspace. Templates are declarative — no sandbox build. The CLI reads template/config.ts + pages.json and uploads via GraphQL; the backend revalidates the public-site cache.

cmssy publish-template <name> [options]

Arguments:

• name — Template directory name under templates/

Options:

• -w, --workspace [id] — Workspace id (defaults to .env)
• --patch / --minor / --major / --no-bump — Version bump (default: --patch)
• --dry-run — Print plan without uploading
• --overwrite-content — Overwrite existing page content on republish (default: preserve)

Example:

cmssy publish-template marketing-site
cmssy publish-template blog -w 65f... --minor

Required blocks listed in the template must already exist in the workspace — publish them via cmssy publish-block first.

cmssy workspaces

List all workspaces you have access to.

cmssy workspaces

Requires: API token configured via cmssy link

Output: Workspace name, slug, ID, and your role (owner/admin/member).

cmssy sync

Pull blocks from Cmssy design library to your local project.

cmssy sync [package] [options]

Arguments:

• package — Specific package to sync (e.g., @cmssy/blocks.hero)

Options:

• --workspace <id> — Sync from specific workspace

Example:

cmssy sync @cmssy/blocks.hero
cmssy sync --workspace abc123

cmssy doctor

All-in-one preflight check for your project setup. Run it before any non-trivial operation (publish, sync); fix failures before proceeding, review warnings as they won't stop you but may flag missing setup.

cmssy doctor

Required (fails the check):

• Node.js >= 18

• cmssy.config.js present in project root

• CMSSY_API_TOKEN set in the environment

Warnings only (run still succeeds):

• npm, next, react availability

• .env file present

• CMSSY_API_URL set (defaults to the public API if missing)

• CMSSY_WORKSPACE_ID set

When enough config is available, doctor also reaches out to the API to verify the token and workspace access.

cmssy test

Run the Vitest suite against your blocks and templates. Test files live at blocks/*/src/**/*.{test,spec}.{ts,tsx} (same for templates).

cmssy test [options]

Options:

• --block <names...> — Test only the listed blocks (space-separated)

• --watch — Watch mode (re-run on file change)

• --coverage — Generate coverage report

Examples:

cmssy test
cmssy test --block hero faq
cmssy test --watch

Writing block tests — use the helpers from @cmssy/cli/test:

import { test, expect } from "vitest";
import { renderBlock, validatePreviewData } from "@cmssy/cli/test";
import Hero from "./Hero";
import previewData from "../preview.json";
// Pull the runtime schema from config.ts (defineBlock({ schema })).
// Don't import from block.d.ts — that's a type declaration, no runtime value.
import heroConfig from "../config";

test("renders the heading from content", async () => {
  const { getByText } = await renderBlock(Hero, {
    content: { heading: "Welcome" },
  });
  expect(getByText("Welcome")).toBeTruthy();
});

test("preview data satisfies the block schema", () => {
  const { valid, errors } = validatePreviewData(heroConfig.schema, previewData);
  expect(valid, errors.join("\n")).toBe(true);
});

@testing-library/react and react are loaded dynamically — install them in your project when you need renderBlock:

npm install -D @testing-library/react

cmssy codegen

Generate TypeScript types from your workspace's public GraphQL schema (powered by @graphql-codegen/cli under the hood).

cmssy codegen [options]

Options:

• -w, --workspace <slug> — Workspace slug (required except for --init)

• -o, --output <path> — Output path (default: src/graphql/types.ts)

• --init — Generate a codegen.ts config file instead of running codegen

First-time setup:

# 1. Create codegen.ts (works on a fresh project, before `cmssy link`)
cmssy codegen --init

# 2. Install codegen deps
npm install -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations

# 3. Run against your workspace
cmssy codegen --workspace my-workspace-slug

Note on --workspace: this flag takes the workspace slug (e.g. my-workspace-slug), not the ObjectId stored in CMSSY_WORKSPACE_ID. Use cmssy workspaces to look up the slug.

cmssy skills install

Install AI coding-assistant skills so Claude Code understands the cmssy CLI, block/template authoring, content editing via MCP, and publishing workflow out of the box.

Two skills ship in 0.14.0:

• block — full CLI + block dev workflow (init, link, create, dev, test, build, publish, sync, defineBlock/defineTemplate authoring)

• mcp-content — managing workspace content via @cmssy/mcp-server MCP tools (i18n rules, layout blocks, forms, publish flow). Requires the MCP server to be configured in Claude Code settings

Commands:

cmssy skills list                 # Show available skills
cmssy skills install              # Interactive prompt (pick a skill)
cmssy skills install block        # CLI + block dev workflow skill
cmssy skills install mcp-content  # Content editing via MCP
cmssy skills install --all        # Install every skill

Options:

• --target <editor> — editor target (default: claude; more coming)

• --all — install every available skill

• --local — install into ./.claude/skills/ (project-scoped) instead of ~/.claude/skills/ (global, default)

• --force — overwrite existing skill without prompting

• -y, --yes — non-interactive mode (fails on conflict instead of prompting)

Requires @cmssy/cli 0.14.0 or newer. After installing, restart Claude Code (or start a new session) and try a prompt like “scaffold a pricing block and publish as patch” or “add a new testimonials block to the homepage, in English and Polish”.

Environment Variables