CLI Reference

CLI Workflows for Component Libraries

The common workflow is: initialize configuration, build compiled Fragments data, inspect it locally, and run governance and metadata checks in CI. If you are setting up Fragments for the first time, start with Install & Theming and return here for the command-level reference.

The CLI compiles the catalog for the static HTML viewer, documentation pages, and automated checks. Fragments Cloud indexes that catalog, and its 4 hosted MCP tools read the index; token metadata supports theming and generation flows.

Setup

Install as a dev dependency. You can also run commands without installing via npx @usefragments/cli. After a local install, the short fragments bin is available in package scripts and via npx.

npm install -D @usefragments/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 npx @usefragments/cli build compiles all fragment files into a single fragments.json file. This is consumed by MCP tooling (so AI assistants can query your components), the static HTML viewer from npx @usefragments/cli view (for browsing locally), and CI pipelines (for compliance checks). Hosted MCP setup is documented separately on the MCP page.

Configuration

Running npx @usefragments/cli init installs local Fragments guardrails, available agent integrations, and CI. Claude Code, Cursor, GitHub Copilot, and Codex are configured by default. If Codex hooks were explicitly disabled with [features].hooks = false, init prints an actionable skip and continues; re-enable hooks before installing the Codex integration. After installation, review and trust the project hook with /hooks. As part of setup, it writes a fragments.config.ts file in your project root with the detected app scope, component files, canonical sources, and token sources:

import type { FragmentsConfig } from '@usefragments/core';

const config: FragmentsConfig = {
  app: {
    path: '.',
    include: [
      '**/*.{tsx,jsx}',
      '**/*.{scss,css}',
    ],
  },

  include: [
    '**/*.fragment.ts',
    '**/*.fragment.tsx',
    '**/*.contract.json',
  ],
  exclude: ['**/node_modules/**'],

  components: ['src/components/**/*.{tsx,jsx}'],

  govern: {
    presets: ['universal@2'],
    // Added when init detects a canonical local directory.
    // It stays open-ended so components added later are governed too.
    canonicalSources: [
      {
        kind: 'directory',
        path: 'src/components',
      },
    ],
  },

  tokens: {
    sources: [
      { path: 'src/styles/**/*.scss', format: 'scss' },
    ],
  },
};

export default config;

Quick Start

Setup is one command. init detects your framework and existing UI library, writes the contract (fragments.config.ts with govern.canonicalSources when a component library is detected), installs the available agent integrations (skip all of them with --no-hook), and finishes by running doctor to prove the chain is armed:

npx @usefragments/cli init

The commands below assume the CLI is installed locally (the fragments bin is then available in package scripts and via npx):

fragments build       # Compile .contract.json files into fragments.json
fragments view        # Generate a static HTML viewer to browse components
fragments doctor      # Prove the enforcement hook chain is armed
fragments check --changed --ci # Gate design-system drift in CI
fragments verify --ci # Verify compiled metadata completeness in CI

Doctor

The agent contract hook is fail-open by design: any error in the hook chain results in a silent allow, never a blocked agent. That is the right trade for your team's workflow, but it means a broken chain looks identical to a healthy one. npx @usefragments/cli doctor is the honest answer to "is it actually working?" — it proves the chain end to end instead of assuming it.

npx @usefragments/cli doctor

Doctor runs a battery of configuration checks covering the whole chain. For Claude it checks the hook entries, pinned command and binary, dist freshness, contract and policy resolution, then executes clean and violating synthetic probes (the latter must surface findings). For an installed Codex integration, Doctor checks its config, global prerequisite, pinned binary and freshness, and a SessionStart contract-injection probe; it does not run a Codex violating-write probe. A required check for an installed integration that cannot run is reported as a failure, not assumed healthy. Optional Codex checks are skipped when Fragments has not installed a Codex integration.

init runs doctor automatically at the end of normal setup, so a fresh install terminates with proof for the integrations it installed. Exit code is non-zero when any required check fails.

Commands