CLI Reference

CLI Workflows for Component Libraries

The common workflow is: initialize configuration, build compiled Fragments data, run local dev previews, and verify quality checks in CI. If you are setting up Fragments for the first time, start with Getting Started and return here for the command-level reference.

The compiled output is shared with MCP tools, documentation pages, and automated checks, so the CLI becomes the backbone of your AI-ready component workflow. It powers 12 MCP tools and token metadata used across theming and generation flows.

Setup

Install as a dev dependency. You can also run commands without installing via npx fragments.

npm install -D @fragments-sdk/cli

How It Works

Every component in your design system can have a .contract.json file alongside it. These files define metadata that AI agents and tools can query: component descriptions, prop documentation, usage guidelines, accessibility rules, and code examples.

{
  "$schema": "https://usefragments.com/schemas/contract.v1.json",
  "name": "Button",
  "description": "Interactive element for user actions",
  "category": "forms",
  "status": "stable",
  "sourcePath": "src/components/Button/index.tsx",
  "exportName": "Button",
  "propsSummary": ["variant: primary|secondary|ghost", "size: sm|md|lg"],
  "usage": {
    "when": ["Triggering actions", "Form submission"],
    "whenNot": ["Navigation (use Link)", "Toggling state (use Switch)"]
  },
  "provenance": { "source": "extracted", "verified": true }
}

Running fragments build compiles all fragment files into a single fragments.json file. This is consumed by the MCP server (so AI assistants can query your components), the dev viewer (for browsing locally), and CI pipelines (for compliance checks).

Configuration

Running fragments init creates a fragments.config.ts file in your project root. This tells the CLI where to find your fragment files and where to write the compiled output:

import { defineConfig } from '@fragments-sdk/cli';

export default defineConfig({
  // Glob patterns for finding .contract.json files
  include: ['src/components/**/*.contract.json'],

  // Output path for compiled fragments.json
  outFile: 'fragments.json',

  // Glob patterns for component source files (for coverage validation)
  components: ['src/components/**/index.tsx'],

  // Design token discovery
  tokens: {
    include: ['src/styles/**/*.scss'],
  },
});

Quick Start

The typical workflow after installation:

fragments init        # Create fragments.config.ts and scaffold files
fragments build       # Compile .contract.json files into fragments.json
fragments dev         # Start local viewer to browse components
fragments verify --ci # Run compliance checks in CI

Commands