CLI Commands

init#

Initialize Sugarcoat in your project.

sugarcoat init [options]

Options#

What it does#

1. Detects your project framework (Next.js, Vite, etc.)
2. Prompts for theme preferences (brand color, accent color, gray scale)
3. Creates sugarcoat.config.ts with your settings
4. Creates .sugarcoat/ directory with Panda config
5. Creates or updates postcss.config.js
6. Updates .gitignore to exclude generated files

Examples#

# Interactive setup
sugarcoat init
 
# Use defaults, skip prompts
sugarcoat init -y
 
# Overwrite existing config
sugarcoat init --force

add#

Add components from the registry to your project.

sugarcoat add [components...] [options]

Arguments#

Options#

What it does#

1. Fetches component data from the registry
2. Resolves and installs registry dependencies
3. Creates component files in your project
4. Updates components.json to track installed components
5. Lists any npm dependencies you need to install

Examples#

# Add a single component
sugarcoat add button
 
# Add multiple components
sugarcoat add button card dialog
 
# Add all components
sugarcoat add --all
 
# Skip confirmation
sugarcoat add button -y
 
# Custom component path
sugarcoat add button --path src/ui

remove#

Remove components from your project.

sugarcoat remove [components...] [options]

Alias: sugarcoat rm

Arguments#

Options#

What it does#

1. Checks for dependent components
2. Removes component files from your project
3. Updates components.json

Examples#

# Interactive removal
sugarcoat remove
 
# Remove specific components
sugarcoat remove button card
 
# Skip confirmation
sugarcoat rm button -y
 
# Force remove (ignore dependencies)
sugarcoat rm button --force

update#

Update installed components to their latest registry versions.

sugarcoat update [components...] [options]

Arguments#

Options#

What it does#

1. Compares local files with registry versions
2. Shows files that would be updated or created
3. Overwrites local files with latest registry versions

Examples#

# Interactive update (shows components with changes)
sugarcoat update
 
# Update specific components
sugarcoat update button card
 
# Update all components
sugarcoat update --all
 
# Preview changes without applying
sugarcoat update --dry-run

list#

List all available components in the registry.

sugarcoat list [options]

Alias: sugarcoat ls

Options#

Examples#

# List all components
sugarcoat list
 
# List installed components only
sugarcoat ls --installed
 
# Filter by category
sugarcoat ls --category forms

search#

Search for components in the registry.

sugarcoat search [query] [options]

Arguments#

Options#

Examples#

# Search for modal-related components
sugarcoat search modal
 
# Search with more results
sugarcoat search button --limit 20

info#

Display detailed information about a component.

sugarcoat info <component> [options]

Arguments#

Options#

What it shows#

• Component name and description
• Installation status
• Categories and tags
• NPM dependencies
• Registry dependencies
• File list

Examples#

# Show component info
sugarcoat info button
 
# Output as JSON
sugarcoat info button --json

diff#

Show differences between local and registry versions of components.

sugarcoat diff [components...] [options]

Arguments#

Options#

What it shows#

• Components that are up to date
• Components with modified files
• Missing files
• Line count of changes (in verbose mode)

Examples#

# Check all installed components
sugarcoat diff
 
# Check specific components
sugarcoat diff button card
 
# Show detailed changes
sugarcoat diff --verbose

codegen#

Generate CSS artifacts from your sugarcoat.config.ts.

sugarcoat codegen [options]

Alias: sugarcoat gen

Options#

What it generates#

• css/ - CSS utility functions (css, cx, cva)
• tokens/ - Design tokens
• patterns/ - Layout patterns (stack, flex, grid, etc.)
• recipes/ - Component recipes
• jsx/ - JSX factory components
• styles.css - Extracted CSS styles

Examples#

# One-time generation
sugarcoat codegen
 
# Watch mode
sugarcoat codegen --watch

dev#

Run codegen in watch mode (alias for codegen --watch).

sugarcoat dev

This is the recommended way to run Sugarcoat during development. It watches for file changes and regenerates CSS automatically.

Example#

# Terminal 1
sugarcoat dev
 
# Terminal 2
npm run dev

doctor#

Run diagnostics to check your Sugarcoat setup.

sugarcoat doctor [options]

Options#

What it checks#

• Project - package.json exists
• Framework - Detected framework and settings
• Sugarcoat config - sugarcoat.config.ts exists
• Sugarcoat directory - .sugarcoat/ exists
• Panda config - .sugarcoat/panda.config.ts exists
• Generated artifacts - Files in .sugarcoat/generated/
• CSS output - styles.css exists and size
• Dependencies - Required packages installed
• PostCSS config - Properly configured
• TypeScript paths - @/.sugarcoat alias configured
• Components config - components.json status

Examples#

# Run diagnostics
sugarcoat doctor
 
# Detailed output
sugarcoat doctor --verbose

mcp#

Start or configure the MCP (Model Context Protocol) server for AI assistants.

sugarcoat mcp [options]

Options#

What it does#

Without options, starts the MCP server (used by AI assistants).

With --install, creates the appropriate MCP configuration file:

• claude: Creates .mcp.json in project root
• cursor: Creates .cursor/mcp.json
• vscode: Creates .vscode/mcp.json

Examples#

# Configure for Claude Code
sugarcoat mcp --install claude
 
# Configure for Cursor
sugarcoat mcp --install cursor
 
# Configure for VS Code
sugarcoat mcp --install vscode
 
# Start MCP server directly (used by AI assistants)
sugarcoat mcp