CLI Reference

The catalogue CLI provides commands for developing, building, and testing your component catalogue.

Installation

npm install @clearforest/catalogue-cli

Commands

catalogue init

Initialize a new component catalogue in the current directory.

catalogue init [options]

Option	Description
-n, --name <name>	Project name
-f, --force	Overwrite existing files
--with-claude	Install Claude Code skills

Examples:

# Initialize with defaults
catalogue init

# With custom name
catalogue init --name "My Design System"

# Force overwrite existing config
catalogue init --force

Creates:

├── catalogue.config.ts
├── tsconfig.json
├── .gitignore
├── registry/
│   └── components/
│       └── sample-button/
│           ├── component.json
│           ├── docs.md
│           └── scenarios/
│               └── default.json
├── src/
│   └── components/
│       ├── index.ts
│       └── sample-button.ts
└── screenshots/

With --with-claude, also creates:

├── .claude/
│   └── skills/
│       ├── new-component.md
│       ├── new-scenario.md
│       └── document-component.md

Claude Code Skills

When initialized with --with-claude, these skills are available:

Skill	Description
/new-component <id>	Create a new component with registry files and source
/new-scenario <id> <name>	Add a scenario to an existing component
/document-component <id>	Generate documentation from source code
/migrate-library [path]	Migrate an existing component library
/setup-tokens [path]	Configure design tokens and themes

---

catalogue dev

Start the development server with hot reload.

catalogue dev [options]

Option	Description
-c, --config <file>	Path to config file
-p, --port <port>	Port to listen on (default: 5173)

Examples:

# Start with defaults
catalogue dev

# Custom port
catalogue dev --port 3000

# Custom config
catalogue dev --config ./custom.config.ts

---

catalogue build

Build the static catalogue site.

catalogue build [options]

Option	Description
-c, --config <file>	Path to config file
-o, --out-dir <dir>	Output directory

Examples:

# Build with defaults
catalogue build

# Custom output directory
catalogue build --out-dir ./public/docs

Output:

Creates a static site in the output directory that can be deployed to any static host.

---

catalogue preview

Preview the built catalogue locally.

catalogue preview [options]

Option	Description
-c, --config <file>	Path to config file
-p, --port <port>	Port to listen on (default: 5173)

Examples:

# Build then preview
catalogue build
catalogue preview

---

catalogue validate

Validate the component registry.

catalogue validate [options]

Option	Description
-c, --config <file>	Path to config file

Checks:

• JSON schema validation for all files
• Cross-reference validation:
  • primaryScenarioId exists
  • parentId references valid component
  • subcomponents reference valid components
  • Every component has at least one scenario
  • No duplicate IDs across registry

Examples:

# Validate registry
catalogue validate

Output:

Validating registry...

Found 5 component(s), 12 scenario(s), 2 example(s)

✓ Registry is valid

Or with errors:

Validating registry...

Schema validation errors:
  components/button/component.json: status: Invalid enum value

Cross-reference validation errors:
  components/card/component.json: playground.primaryScenarioId:
    Primary scenario "card-missing" not found

✗ Validation failed

---

catalogue test

Run Playwright visual regression tests.

catalogue test [options]

Option	Description
-c, --config <file>	Path to config file
-u, --update	Update snapshots
--headed	Run tests in headed mode

Process:

1. Validates the registry
2. Builds the static site
3. Generates Playwright test file
4. Runs tests across scenarios, themes, and breakpoints

Examples:

# Run tests
catalogue test

# Update snapshots
catalogue test --update

# Debug in browser
catalogue test --headed

Prerequisites:

# Install Playwright browsers
npx playwright install

---

catalogue new

Create a new component with scaffolding.

catalogue new <component-id> [options]

Option	Description
-c, --config <file>	Path to config file
-t, --title <title>	Component title
-s, --status <status>	Status: stable, beta, deprecated
-k, --kind <kind>	Kind: standalone, subcomponent, feature

Examples:

# Basic component
catalogue new user-avatar

# With all options
catalogue new data-table \
  --title "Data Table" \
  --status stable \
  --kind standalone

# Subcomponent
catalogue new table-row --kind subcomponent

Creates:

registry/components/<id>/
├── component.json
├── docs.md
└── scenarios/
    └── default.json

src/components/
└── <id>.ts

---

Global Options

All commands support:

Option	Description
-h, --help	Show help for command
-v, --version	Show version number

catalogue --help
catalogue dev --help

Exit Codes

Code	Meaning
0	Success
1	Error (validation failed, build error, etc.)

Configuration Discovery

Commands look for configuration in this order:

1. --config option path
2. catalogue.config.ts
3. catalogue.config.js
4. catalogue.config.mjs

npm Scripts

Add to package.json:

{
  "scripts": {
    "catalogue": "catalogue dev",
    "catalogue:build": "catalogue build",
    "catalogue:test": "catalogue test",
    "catalogue:validate": "catalogue validate"
  }
}

Then run:

npm run catalogue
npm run catalogue:build

CI/CD Integration

GitHub Actions

name: Component Catalogue

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '23'
      - run: npm ci
      - run: npx catalogue validate

  visual-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '23'
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx catalogue test
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: playwright-report
          path: playwright-report/

Next Steps

• Visual Testing Guide
• Configuration Reference