CLI Guide

The ui-lab command-line tool provides an intuitive way to initialize projects and install components into your existing applications.

Overview

The CLI is published as the ui-lab npm package and can be used either as a global tool or via npx.

Installation:

npm install -g ui-lab        # Global installation
# or use npx without installing
npx ui-lab init

Requirements:

• Node.js 18 or higher
• npm, yarn, or pnpm

ui-lab init

Initialize a new UI Lab project in your existing application.

Basic Usage:

npx ui-lab init

Usage Modes

Interactive (Default): Guided prompts walk you through framework detection, component directory selection, theme presets, and CSS setup.

npx ui-lab init

Headless: Skip all prompts with defaults or flags:

npx ui-lab init --yes
npx ui-lab init --yes --preset vitesse-dark --framework nextjs

Options

What init Does

• Detects your framework (Next.js or Vite)
• Creates a component directory
• Generates CSS variables for your theme
• Saves configuration for future commands

Example Output

npx ui-lab init --framework nextjs

✓ Detected Next.js 16 (app router)
✓ Creating ./components directory
✓ Generating theme preset (vitesse-light)
✓ Creating ui-lab.config.json
✓ Setup complete!

ui-lab install / ui-lab add

Install specific components into your project. Both install and add work identically.

Basic Usage:

npx ui-lab install button input modal
# or
npx ui-lab add button input modal

Component Installation

The CLI installs only the components you request:

$ npx ui-lab install button input

 ◇  Validating components...
 ◇  Resolving dependencies...
    • button → no dependencies
    • input → requires label
 ◇  Installing components...
    ✓ button → ./components/button.tsx
    ✓ input → ./components/input.tsx
    ✓ label → ./components/label.tsx (auto-required)
 ✓ Installation complete!

Features

• Auto-validates component names and suggests corrections
• Resolves dependencies – installs required child components automatically
• Preview mode – preview changes with --dry-run before committing

Options

Example: With Dependencies & Dry Run

npx ui-lab install form

 ◇  Validating components...
 ◇  Resolving dependencies...
    • form (requires: input, label, button, select)
 ✓ Installing 5 components...

Preview before installing:

npx ui-lab install button input --dry-run

 ◇  Preview mode (no changes)
 ◆  Would install: button.tsx (28 KB), input.tsx (15 KB), label.tsx (8 KB)
 ◆  Estimated impact: +51 KB

Available Components

The CLI recognizes all 27+ components from the UI Lab library:

Layout: button · card · divider · flex · fold · grid · group

Input: checkbox · input · label · radio · select · slider · switch · textarea

Feedback: badge · progress · toast · tooltip

Modal/Overlay: modal · popover · menu · confirmation

Form: form · command-palette

Complex: breadcrumbs · tabs · gallery

Use npx ui-lab list to see all available components (if implemented).

Theme Presets

Choose a preset during init or update later:

npx ui-lab init --preset vitesse-light   # Light theme
npx ui-lab init --preset vitesse-dark    # Dark theme

To customize colors, edit the generated CSS variables file after initialization.

Project Detection

The CLI automatically detects Next.js (app/pages router) and Vite projects. If detection fails, specify your framework explicitly:

npx ui-lab init --framework nextjs
npx ui-lab init --framework vite

Configuration

The CLI saves your setup in ui-lab.config.json. To update it, run init again:

npx ui-lab init --preset vitesse-dark

Troubleshooting

Framework Detection Failed

Problem: CLI doesn't recognize your framework

Solution:

# Specify framework explicitly
npx ui-lab init --framework nextjs    # or --framework vite

Component Installation Failed

Problem: Component fails to install

Causes & Solutions:

• Component name typo → Check spelling (ui-lab install button not ui-lab install btn)
• Dependency missing → Let CLI resolve dependencies automatically
• Directory permissions → Ensure component directory is writable

Theme Preset Not Found

Problem: "Unknown preset" error

Solution:

# Use a known preset
npx ui-lab init --preset vitesse-light

# Check available presets
npx ui-lab list-presets    # if implemented

Network Issues

Problem: "Cannot reach registry" error

Causes & Solutions:

• Check internet connection
• Verify npm registry is accessible
• Try again with exponential backoff
• Check npm configuration: npm config get registry

Best Practices

1. Initialize First

Always run init before installing components:

npx ui-lab init
npx ui-lab install button input

2. Use Presets Initially

Start with a preset theme, customize later:

npx ui-lab init --preset vitesse-dark
# Later: edit theme variables in CSS

3. Install Components as Needed

Add components incrementally as you need them:

npx ui-lab install button input label
npx ui-lab install form modal select

Common Questions

Q: Can I use the CLI without initializing first? A: Run init first—it sets up configuration for future commands.

Q: How do I change the theme after init? A: Edit the generated theme CSS file or run init again with a new preset.

Q: Does the CLI modify my existing files? A: No, it only creates new files. Use --dry-run to preview.

Q: Can I use a custom component directory? A: Yes: npx ui-lab init --componentDir src/ui

Command Reference

# Initialize a project
npx ui-lab init

# Initialize with specific settings
npx ui-lab init --framework nextjs --preset vitesse-dark --yes

# Install components
npx ui-lab install button input

# Install with dry-run
npx ui-lab install button input --dry-run

# Install in headless mode
npx ui-lab install button --yes

# Get help
npx ui-lab --help
npx ui-lab init --help
npx ui-lab install --help

Feedback & Support

Found an issue? Have suggestions for the CLI?

• GitHub Issues: https://github.com/kyza0d/ui-lab.app/issues
• Include CLI version: npx ui-lab --version
• Include framework and Node version
• Describe steps to reproduce