Pittaya UI CLI

A powerful CLI to add Pittaya UI components to your React/Next.js project with intelligent dependency management and AST-based detection.

🚀 Installation

No installation required! Use directly with npx:

npx pittaya@latest init

Current Version: 0.0.9 (View Changelog)

✨ Features

• 🎯 Smart Installation - Automatically detects and skips already installed components
• 🔗 Dependency Management - Intelligently installs component dependencies
• 🛡️ Preserves Customizations - Won't overwrite your modified components
• 📦 Internal Dependencies - Components can declare dependencies on other Pittaya components
• 🤖 AST-Based Detection - 100% precision in detecting component dependencies using TypeScript Compiler API
• 🗑️ Easy Removal - Remove components and clean up empty directories with a single command
• ⚡ Fast & Efficient - Only installs what's needed
• 🔄 Update Management - Check for updates and update components easily
• 📋 Component Discovery - List all available and installed components with detailed information
• 🎨 Import Transformation - Automatically adjusts imports to your project structure
• 🌐 GitHub Registry - Components served via free CDN
• 🔄 Idempotent - Safe to run multiple times
• 🎨 Multiple Styles - Choose from default, new-york, or pittaya design styles
• 📁 Auto-Detection - Automatically detects src/ directory structure
• 🐛 Debug Tools - Built-in diagnostics for troubleshooting

📖 See ROADMAP.md for upcoming features and completed milestones

📖 Usage

Initialize Pittaya UI in your project

npx pittaya@latest init

This command will:

• Create a components.json file with your preferences
• Install required base dependencies
• Configure import aliases
• Apply style-specific CSS variables to your globals.css

Options

• -y, --yes - Use default settings without prompts

npx pittaya@latest init -y

Add components

Add a specific component

npx pittaya@latest add button

Add multiple components

npx pittaya@latest add button badge skeleton

Add all components

npx pittaya@latest add --all

Interactive mode

If you don't specify components, it will enter interactive mode:

npx pittaya@latest add

Options

• -y, --yes - Overwrite existing files without prompting
• -o, --overwrite - Overwrite existing files
• -a, --all - Add all components
• --add-missing-deps - Automatically install missing dependencies

Flag Comparison:

| Flag | Overwrites Files | Auto-Installs Dependencies | | -------------------------- | ---------------- | -------------------------- | | --yes | ✅ Yes | ❌ No | | --add-missing-deps | ❌ No | ✅ Yes | | --yes --add-missing-deps | ✅ Yes | ✅ Yes |

⏭️ Smart Component Installation

The CLI automatically detects if a component is already installed and skips reinstallation to preserve your customizations:

# Install orbit-images (which depends on button and utils)
npx pittaya@latest add orbit-images

First run:

📦 orbit-images requires: button, utils
✓ button installed successfully!
✓ utils installed successfully!
✓ orbit-images installed successfully!

Second run (components already installed):

⏭️  orbit-images already installed, skipping...

Benefits:

• 🛡️ Preserves Customizations - Your modified components won't be overwritten
• ⚡ Faster Installation - Doesn't reinstall dependencies unnecessarily
• 🔄 Idempotent - Running the same command multiple times is safe

Force Reinstallation:

npx pittaya@latest add button --overwrite

📖 Learn more: See SKIP_INSTALLED.md for detailed documentation.

Dependency Management

When adding a component, the CLI automatically checks for required dependencies. If any are missing, you'll see:

npx pittaya@latest add button

Output:

⚠️  button requires the following dependencies:

  • @radix-ui/react-slot

? Do you want to install the dependencies now? › (Y/n)

Skip the prompt with --add-missing-deps:

npx pittaya@latest add button --add-missing-deps

This will automatically install all missing dependencies without asking.

Check for component updates

Check if your installed components have updates available in the registry:

npx pittaya@latest diff

This will show you an interactive list of installed components to check.

Check specific components

npx pittaya@latest diff button orbit-images

Check all installed components

npx pittaya@latest diff --all

Output:

📝 Components with updates available (2):

   • button
     └─ button.tsx (modified)
   • orbit-images
     └─ orbit-images.tsx (modified)

Run npx pittaya update <component> to update.

✅ Components up to date (1):

   • utils

Update components

Update your installed components to the latest version from the registry:

npx pittaya@latest update

This will show you an interactive list of installed components to update.

Update specific components

npx pittaya@latest update button

Update all installed components

npx pittaya@latest update --all

Options

• -y, --yes - Skip confirmation prompts
• -f, --force - Force update even if no changes detected
• -a, --all - Update all installed components

Examples:

# Update all components without prompts
npx pittaya@latest update --all --yes

# Force update button (even if up to date)
npx pittaya@latest update button --force

Output:

✅ Updated 2 component(s):

   • button
   • orbit-images

⏭️  Skipped 1 component(s):

   • utils (already up to date)

List components

View all available and installed components:

npx pittaya@latest list

This will show all components from the registry, organized by category, with installation status.

Options

• --installed - Show only installed components
• --available - Show only available components
• --json - Output in JSON format

Remove components

Remove installed components from your project:

npx pittaya@latest remove button

Interactive mode

If you don't specify components, it will show a list of installed components to select for removal:

npx pittaya@latest remove

Options

• -y, --yes - Skip confirmation prompt

Debug component issues

Diagnose why a component is not being detected as installed:

npx pittaya@latest debug --component installation-section

This will show:

• Project structure (src/ vs root)
• Resolved alias paths
• Expected file locations
• Actual file existence
• Similar files found (helps identify naming issues)

Common issues it helps solve:

• File name mismatches (e.g., InstallationSection.tsx vs installation-section.tsx)
• Wrong directory structure
• Incorrect components.json configuration

View credits

Show the creators and contributors of Pittaya UI:

npx pittaya@latest credits

🎨 Available Components

Actions

• announcement-badge - Displays an announcement badge with customizable styles
• button - Displays a button or a component that looks like a button
• copy-button - A button that copies content to clipboard

Forms

• checkbox - A checkbox form control
• input - Text input field
• label - Form label component
• multi-select - Multi-selection dropdown component
• radio-group - Radio button group
• textarea - Multiline text input

UI Components

• badge - Displays a badge with customizable styles
• card - Card container component
• carousel - Image carousel component
• command - Command palette component
• orbit-images - Displays images in an orbiting motion
• popover - Popover overlay component
• tabs - Tab navigation component

Documentation

• installation-section - Displays installation instructions with code snippets

Library

• utils - Utility functions for className management

💡 Note: Components are available in three styles: default, new-york, and pittaya. Each style has its own visual design and can include different implementations.

💡 Practical Examples

Customization Workflow

# 1. Install a component
npx pittaya add button

# 2. Customize it in your project
# Edit: src/components/ui/button.tsx
# Add your own styles, logic, etc.

# 3. Install other components that depend on button
npx pittaya add modal card dialog orbit-images

# ✅ Result: Your customized button is preserved!
# Only modal, card, dialog, and orbit-images are installed

Managing Dependencies

# Install a component with multiple dependencies
npx pittaya add orbit-images

# Output:
# 📦 orbit-images requires: button, utils
# ✓ button installed successfully!
# ✓ utils installed successfully!
# ✓ orbit-images installed successfully!

# Run again - nothing is reinstalled
npx pittaya add orbit-images

# Output:
# ⏭️  orbit-images already installed, skipping...

Force Reinstallation

# Want to reset a component to its original state?
npx pittaya add button --overwrite

# This will:
# ✅ Overwrite the existing button.tsx
# ✅ Keep your other customized components intact

🔧 Configuration

The components.json file stores your preferences:

{
  "$schema": "https://raw.githubusercontent.com/pittaya-ui/ui/main/registry/schema.json",
  "style": "pittaya",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "src/app/globals.css",
    "baseColor": "neutral",
    "cssVariables"