CLI

Quick start

Setup is one command: init detects your framework and existing UI library, writes the contract, installs the available agent integrations, and finishes by running doctor — the full walkthrough is in The loop in five minutes. After a local install (npm install -D @usefragments/cli), the short fragments bin is available in package scripts and via npx:

# one-time setup: contract, agent integrations, CI
npx @usefragments/cli init

npx @usefragments/cli build                # Compile .contract.json files into fragments.json
npx @usefragments/cli view                 # Generate a static HTML viewer to browse components
npx @usefragments/cli doctor               # Prove the enforcement hook chain is armed
npx @usefragments/cli check --changed --ci # Gate design-system drift in CI

Configuration

init writes a fragments.config.ts file in your project root with the detected app scope, component files, canonical sources, and token sources. The agent hooks and CI workflow it also installs are documented in Agents and Connect the gate.

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/**'],

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 rules 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

Next steps

• The loopinit, discover, and the first correction in five minutes.
• MCPHosted endpoint, per-editor configuration, and the design-system tools.
• Error codesEvery FUI diagnostic code with its own explain page.