Referencja komend CLI — Dokumentacja Cmssy

Przegląd

Cmssy CLI (@cmssy/cli) to narzędzie wiersza poleceń do budowania, podglądu i publikowania niestandardowych bloków UI w przestrzeniach roboczych Cmssy. Zainstaluj globalnie:

npm install -g @cmssy/cli

cmssy init

Inicjalizacja nowego projektu Cmssy z gotową strukturą.

cmssy init [nazwa] [opcje]

Argumenty:

nazwa — Nazwa katalogu projektu (opcjonalna, pyta jeśli pominięta)

Opcje:

-f, --framework <framework> — Framework: react (domyślnie), vue, angular, vanilla
-y, --yes — Pomiń pytania, użyj domyślnych wartości

Przykład:

cmssy init moje-bloki
cmssy init moje-bloki --framework react --yes

Tworzy: Katalog projektu z cmssy.config.js, package.json, tsconfig.json, przykładowym blokiem hero, stylami i plikami konfiguracyjnymi.

cmssy link

Łączy bieżący projekt z workspace'em Cmssy. Domyślnie interaktywnie: wybiera workspace, przyjmuje token API i zapisuje CMSSY_API_URL, CMSSY_API_TOKEN oraz CMSSY_WORKSPACE_ID do pliku .env.

cmssy link [opcje]

Opcje:

--token <token> — Token API (tryb nieinteraktywny, musi zaczynać się od cs_)
--workspace <id|slug> — Workspace do połączenia (tryb nieinteraktywny)
--api-url <url> — Nadpisuje endpoint API (domyślnie: https://api.cmssy.io/graphql)

Przykłady:

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

Tokeny generujesz w ustawieniach workspace'u: Settings → API Tokens. Listę dostępnych workspace'ów zwraca cmssy workspaces.

Zastąpił starą komendę configure w 0.12.

cmssy create block

Tworzenie nowego bloku w projekcie.

cmssy create block <nazwa> [opcje]

Argumenty:

nazwa — Identyfikator bloku (kebab-case, np. hero-section)

Opcje:

-y, --yes — Pomiń pytania
-d, --description <tekst> — Opis bloku
-c, --category <kategoria> — Kategoria: marketing, typography, media, layout, forms, navigation, other
-t, --tags <tagi> — Tagi oddzielone przecinkami

Przykład:

cmssy create block tabela-cenowa -c marketing -t "cennik,plany" -y

Tworzy: blocks/<nazwa>/ z config.ts, package.json, preview.json i katalogiem src/.

cmssy create template

Tworzenie nowego szablonu strony.

cmssy create template <nazwa> [opcje]

Opcje:

-y, --yes — Pomiń pytania
-d, --description <tekst> — Opis szablonu

Tworzy: templates/<nazwa>/ z konfiguracją szablonu i projektami stron.

cmssy dev

Uruchomienie serwera deweloperskiego z podglądem na żywo.

cmssy dev [opcje]

Opcje:

-p, --port <port> — Numer portu (domyślnie: 3000)

Funkcje:

Generuje aplikację deweloperską Next.js w .cmssy/dev/
Hot reload przy zmianach plików
Podgląd UI dla wszystkich bloków z danymi preview.json
Automatyczne wykrywanie nowych bloków
Alokacja pamięci Node 4GB

cmssy build

Budowanie wszystkich bloków i szablonów do produkcji.

cmssy build [opcje]

Opcje:

--block <nazwy...> — Buduj tylko określone bloki
--framework <framework> — Nadpisz framework z konfiguracji

Proces:

Skanuje katalogi blocks/ i templates/
Waliduje config.ts i schemat
Buduje równolegle (współbieżność: 8) używając esbuild
Generuje typy TypeScript ze schematu
Kompiluje CSS z Tailwind (automatyczne wykrywanie v3/v4)
Wynik do public/@vendor/package-name/version/

Przykład:

cmssy build
cmssy build --block hero pricing

cmssy publish-block

Publikuje pojedynczy blok do workspace przez pipeline sandbox build (Vercel Sandbox + Inngest). CLI archiwizuje drzewo źródeł do tar.gz, wysyła do backendu, który kolejkuje zadanie build budujące blok i zapisujące artefakty z powrotem do Vercel Blob.

cmssy publish-block <nazwa> [opcje]

Argumenty:

nazwa — Nazwa katalogu bloku w blocks/

Opcje:

-w, --workspace [id] — ID workspace (domyślnie CMSSY_WORKSPACE_ID z .env)
--entry <ścieżka> — Ścieżka entry w katalogu bloku (domyślnie: src/index.tsx)
--dry-run — Zbiera pliki i wypisuje plan bez wysyłania

Przykład:

cmssy publish-block hero                   # publikuj do workspace z .env
cmssy publish-block hero -w 65f...         # nadpisz workspace
cmssy publish-block hero --dry-run         # zobacz co zostanie wysłane

Limity: 200 plików / 10 MB łącznie na blok. Odpytywanie buildu: co 1.5s, max 10 minut, kończy po 5 kolejnych błędach.

Stara komenda cmssy publish wraz z flagami --zip / --patch / --minor / --major / --overwrite-content / --force / --with-source / --all została usunięta w CMS-606. Wersjonowanie obsługuje pipeline build.

cmssy publish-template

Publikuje pojedynczy szablon (drzewo stron + zawartość) do workspace. Szablony są deklaratywne — bez sandbox build. CLI czyta template/config.ts + pages.json i wysyła przez GraphQL; backend rewaliduje cache strony publicznej.

cmssy publish-template <nazwa> [opcje]

Argumenty:

nazwa — Nazwa katalogu szablonu w templates/

Opcje:

-w, --workspace [id] — ID workspace (domyślnie z .env)
--patch / --minor / --major / --no-bump — Podbicie wersji (domyślnie: --patch)
--dry-run — Wypisuje plan bez wysyłania
--overwrite-content — Nadpisz istniejącą zawartość strony przy republikacji (domyślnie: zachowaj)

Przykład:

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

Bloki wymagane przez szablon muszą już istnieć w workspace — opublikuj je najpierw przez cmssy publish-block.

cmssy workspaces

Wyświetlanie wszystkich przestrzeni roboczych, do których masz dostęp.

cmssy workspaces

Wymaga: Token API skonfigurowany przez cmssy link

Wyświetla: Nazwa przestrzeni roboczej, slug, ID i Twoja rola (owner/admin/member).

cmssy sync

Pobieranie bloków z biblioteki designu Cmssy do lokalnego projektu.

cmssy sync [pakiet] [opcje]

Argumenty:

pakiet — Konkretny pakiet do synchronizacji (np. @cmssy/blocks.hero)

Opcje:

--workspace <id> — Synchronizuj z konkretnej przestrzeni roboczej

Przykład:

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

cmssy doctor

Kompleksowy preflight check konfiguracji projektu. Uruchom przed każdą nietrywialną operacją (publish, sync); napraw błędy przed kontynuowaniem, przejrzyj ostrzeżenia - nie blokują uruchomienia, ale mogą wskazywać brakujące elementy setupu.

cmssy doctor

Wymagane (check kończy się błędem):

Node.js >= 18
cmssy.config.js w katalogu głównym projektu
CMSSY_API_TOKEN ustawiony w środowisku

Tylko ostrzeżenia (check przechodzi):

Dostępność npm, next, react
Plik .env obecny
CMSSY_API_URL ustawiony (jeśli brak, używa publicznego API)
CMSSY_WORKSPACE_ID ustawiony

Gdy konfiguracja na to pozwala, doctor łączy się z API żeby zweryfikować token i dostęp do workspace'u.

cmssy test

Uruchamia Vitest na Twoich blokach i szablonach. Pliki testów żyją w blocks/*/src/**/*.{test,spec}.{ts,tsx} (analogicznie dla szablonów).

cmssy test [opcje]

Opcje:

--block <nazwy...> — Testuj tylko wskazane bloki (rozdzielone spacjami)
--watch — Tryb watch (re-run przy każdej zmianie)
--coverage — Generuj raport pokrycia

Przykłady:

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

Pisanie testów bloków — użyj helperów z @cmssy/cli/test:

import { test, expect } from "vitest";
import { renderBlock, validatePreviewData } from "@cmssy/cli/test";
import Hero from "./Hero";
import previewData from "../preview.json";
// Runtime schema pochodzi z config.ts (defineBlock({ schema })).
// Nie importuj z block.d.ts - to tylko deklaracje typów, bez runtime value.
import heroConfig from "../config";

test("renderuje heading z content", async () => {
  const { getByText } = await renderBlock(Hero, {
    content: { heading: "Witaj" },
  });
  expect(getByText("Witaj")).toBeTruthy();
});

test("preview data pasuje do schematu bloku", () => {
  const { valid, errors } = validatePreviewData(heroConfig.schema, previewData);
  expect(valid, errors.join("\n")).toBe(true);
});

@testing-library/react i react są ładowane dynamicznie — zainstaluj je w projekcie gdy będziesz używać renderBlock:

npm install -D @testing-library/react

cmssy codegen

Generuje typy TypeScript ze schematu publicznego GraphQL Twojego workspace'u (pod spodem @graphql-codegen/cli).

cmssy codegen [opcje]

Opcje:

-w, --workspace <slug> — Slug workspace'u (wymagany poza --init)
-o, --output <path> — Ścieżka wyjściowa (domyślnie: src/graphql/types.ts)
--init — Generuje plik codegen.ts zamiast uruchamiania codegenu

Pierwszy setup:

# 1. Stwórz codegen.ts (działa w świeżym projekcie, przed `cmssy link`)
cmssy codegen --init

# 2. Zainstaluj zależności codegenu
npm install -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations

# 3. Uruchom dla swojego workspace'u
cmssy codegen --workspace my-workspace-slug

Uwaga o --workspace: ta flaga przyjmuje slug workspace'u (np. my-workspace-slug), nie ObjectId z CMSSY_WORKSPACE_ID. Sluga sprawdzisz komendą cmssy workspaces.

cmssy skills install

Instaluje skille dla asystenta AI (Claude Code) - dzięki temu edytor zna komendy Cmssy CLI, strukturę bloków i szablonów, edycję content przez MCP oraz workflow publikacji.

W 0.14.0 dostarczane są dwa skille:

block – pełny workflow CLI + tworzenie bloków (init, link, create, dev, test, build, publish, sync, defineBlock/defineTemplate)
mcp-content – zarządzanie contentem workspace przez narzędzia @cmssy/mcp-server (reguły i18n, layout blocks, formularze, flow publikacji). Wymaga skonfigurowanego MCP servera w Claude Code

Komendy:

cmssy skills list                 # Pokaż dostępne skille
cmssy skills install              # Interaktywny prompt (wybierz skill)
cmssy skills install block        # Skill CLI + block dev
cmssy skills install mcp-content  # Edycja content przez MCP
cmssy skills install --all        # Zainstaluj wszystkie skille

Opcje:

--target <editor> – docelowy edytor (domyślnie: claude; więcej wkrótce)
--all – zainstaluj wszystkie dostępne skille
--local – instaluj do ./.claude/skills/ (w obrębie projektu) zamiast ~/.claude/skills/ (globalnie, domyślnie)
--force – nadpisz istniejący skill bez pytania
-y, --yes – tryb nieinteraktywny (kończy błędem w razie konfliktu zamiast pytania)

Wymaga @cmssy/cli w wersji 0.14.0 lub nowszej. Po instalacji zrestartuj Claude Code (lub otwórz nową sesję) i zapytaj o coś w stylu „zescafolduj blok pricing i opublikuj jako patch” lub „dodaj nowy blok testimonials do strony głównej po angielsku i po polsku”.

Zmienne środowiskowe

Zmienna	Wymagana	Opis
`CMSSY_API_URL`	Tak	Endpoint GraphQL API (domyślnie: `https://api.cmssy.io/graphql`)
`CMSSY_API_TOKEN`	Tak	Token uwierzytelniania API (format: `cs_xxxxx`)
`CMSSY_WORKSPACE_ID`	Nie	Domyślne ID przestrzeni roboczej dla skrótu `--workspace`