npm package: @ragdalion/cli
Description: CLI to add Ragdalion UI components to your project
Author: Ragdalion
Latest version: 0.0.2

# @ragdalion/cli

A CLI tool to add beautifully designed React UI components to your project. Similar to [shadcn/ui](https://ui.shadcn.com), components are copied directly into your codebase — you own the code, no runtime dependency on the library.

## Features

- **80+ components** — Buttons, forms, charts, file uploads, auth pages, error pages, and more
- **Zero runtime dependency** — Components are copied into your project as source files
- **Automatic dependency resolution** — Inter-component dependencies are resolved and installed automatically
- **npm package installation** — Required third-party packages (Radix UI, Recharts, etc.) are installed for you
- **Fully customizable** — Every component lives in your codebase, ready to be modified

## Installation

```bash
npm install -g @ragdalion/cli
```

Or use with `npx` without installing globally:

```bash
npx @ragdalion/cli init
npx @ragdalion/cli add button
```

## Quick Start

### 1. Initialize your project

```bash
ragdalion init
```

This prompts you to set your `@/` alias root directory, then generates a `ragdalion.json` config file:

```json
{
  "baseDir": "src"
}
```

### 2. Add components

```bash
ragdalion add button
```

This copies the `button` component (and its dependency `cn`) into your project and installs required npm packages (`class-variance-authority`, `@radix-ui/react-slot`, `lucide-react`, `clsx`, `tailwind-merge`).

### 3. Add multiple components at once

```bash
ragdalion add button badge alert card
```

### 4. Add all components

```bash
ragdalion add --all
```

### 5. Interactive selector

Running `ragdalion add` without arguments opens an interactive multi-select prompt:

```bash
ragdalion add
```

## Commands

### `ragdalion init`

Initializes Ragdalion UI in your project.

| Prompt | Default | Description |
|---|---|---|
| Path alias root | `src` | The directory your `@/` alias resolves to (e.g. `src`) |

Creates a `ragdalion.json` file in the project root.

### `ragdalion add [components...]`

Adds one or more components to your project.

| Option | Description |
|---|---|
| `-a, --all` | Add all available components |
| `-h, --help` | Show help |

**What happens when you run `add`:**

1. Reads `ragdalion.json` for the base output directory
2. Resolves all inter-component dependencies recursively
3. Copies template files into your project
4. Detects your package manager (npm/yarn/pnpm/bun) and installs required packages automatically

## Components

### Utilities

| Name | Description |
|---|---|
| `cn` | `clsx` + `tailwind-merge` utility function |
| `format` | Byte/file size formatting utility |

### Types & Hooks

| Name | Description |
|---|---|
| `file-type` | Upload file type definitions |
| `use-add-files` | Hook for handling file uploads with progress tracking |

### Basic UI

| Name | Description | Key Dependencies |
|---|---|---|
| `button` | Multi-variant button with loading state and icons | `class-variance-authority`, `@radix-ui/react-slot` |
| `button-social` | Social login buttons (Google, Facebook, X) | `react-icons` |
| `badge` | Color badges with dot, icon, and removable variants | `lucide-react` |
| `accordion` | Collapsible accordion sections | `@radix-ui/react-accordion` |
| `alert` | Alert banners (info, success, warning, error) | `lucide-react` |
| `breadcrumb` | Breadcrumb navigation | `lucide-react` |
| `card` | Card container with header, content, footer | — |
| `card-stat-grid` | Stat grid cards with tooltips | `lucide-react` |
| `checkbox` | Checkbox input | `radix-ui` |
| `calendar` | Calendar / date picker | `react-day-picker` |
| `date-picker` | Single date picker with popover | `lucide-react` |
| `date-range-picker` | Date range picker with popover | `date-fns`, `react-day-picker` |
| `delete-button` | Small delete action button | — |
| `dialog` | Dialog / modal primitives | `@radix-ui/react-dialog` |
| `file-icon` | File type icon based on MIME type | — |
| `modal` | Pre-built modals (confirm, delete, success) | `lucide-react` |
| `pagination` | Pagination with page numbers | `lucide-react` |
| `pagination-default` | Pagination with rows-per-page select | `lucide-react` |
| `popover` | Popover component | `@radix-ui/react-popover` |
| `progress` | Progress bar | `radix-ui` |
| `scroll-area` | Custom scroll area | `@radix-ui/react-scroll-area` |
| `select` | Select dropdown | `@radix-ui/react-select` |
| `sort` | Sort indicator icon | `lucide-react` |
| `table` | Table primitives with sorting | — |
| `tabs` | Tabs component | — |
| `tooltip` | Tooltip component | `@radix-ui/react-tooltip` |
| `tooltip-wrapper` | Simple tooltip wrapper | `@radix-ui/react-tooltip` |

### Forms

| Name | Description |
|---|---|
| `input` | Text input with label and icon support |
| `label` | Form label |
| `select-custom` | Custom styled select with label |

### Authentication Pages

| Name | Description |
|---|---|
| `auth-login` | Login page with social auth |
| `auth-register` | Register page with password validation |
| `auth-forgot-password` | Forgot password / reset flow |
| `auth-email-verification` | Email verification page |

### Error Pages

| Name | Description |
|---|---|
| `error-forbidden` | 403 Forbidden page |
| `error-not-found` | 404 Not Found page |
| `error-server` | 500 Internal Server Error page |

### File Upload

| Name | Description |
|---|---|
| `avatar-upload` | Avatar image upload with preview |
| `document-upload` | Document file upload with progress bar |
| `drag-drop-upload` | Drag & drop file upload zone |
| `file-upload` | Single file upload with preview |
| `image-gallery-upload` | Image gallery upload grid |
| `inline-upload` | Inline file upload with file list |
| `multiple-file-upload` | Multiple file upload with previews |
| `video-upload` | Video file upload with progress |

### Modals

| Name | Description |
|---|---|
| `modal-preview` | File preview modal |

### Charts

All chart components are built with [Recharts](https://recharts.org) and wrapped inside a `chart-card` container.

| Name | Description |
|---|---|
| `chart-card` | Chart wrapper card with badge |
| `main-chart` | Main area chart dashboard widget |
| `horizontal-bar` | Horizontal bar chart |
| `vertical-bar` | Vertical bar chart |
| `snake-bar` | Snake/area bar chart |

**Bar Charts**

| Name | Description |
|---|---|
| `bar-simple` | Simple bar chart |
| `bar-grouped` | Grouped bar chart |
| `bar-stacked` | Stacked bar chart |
| `bar-horizontal` | Horizontal bar chart variant |
| `bar-category` | Category bar chart |
| `bar-spark-line` | Spark line bar chart |

**Line Charts**

| Name | Description |
|---|---|
| `line-simple` | Simple line chart |
| `line-multi` | Multi-line chart |
| `line-area` | Area line chart |
| `line-stacked-area` | Stacked area chart |
| `line-stock` | Stock price line chart |
| `line-toggle` | Toggle-able multi line chart |

**Pie Charts**

| Name | Description |
|---|---|
| `pie-simple` | Simple pie chart |
| `pie-donut` | Donut chart |
| `pie-donut-stats` | Donut chart with stats |
| `pie-half-donut` | Half donut chart |
| `pie-labeled` | Labeled pie chart |
| `pie-multi-donut` | Multi-ring donut chart |

**Radar Charts**

| Name | Description |
|---|---|
| `radar-simple` | Simple radar chart |
| `radar-filled` | Filled radar chart |
| `radar-comparison` | Radar comparison chart |
| `radar-interactive` | Interactive radar with toggles |
| `radar-multi-team` | Multi-team radar chart |
| `radar-spider` | Spider radar chart |

**Scatter Charts**

| Name | Description |
|---|---|
| `scatter-simple` | Simple scatter plot |
| `scatter-bubble` | Bubble chart |
| `scatter-cluster` | Cluster scatter plot |
| `scatter-correlation` | Correlation scatter plot |
| `scatter-jitter` | Jitter scatter plot |
| `scatter-risk-return` | Risk return scatter with zones |

## Dependency Resolution

When you add a component, all of its internal dependencies are resolved automatically. For example:

```bash
ragdalion add date-picker
```

This will install:
- `date-picker` — the component itself
- `button` — used inside the date picker
- `popover` — the popover container
- `calendar` — the calendar dropdown
- `label` — the form label
- `cn` — the utility function (shared dependency)

Along with npm packages: `lucide-react`, `class-variance-authority`, `@radix-ui/react-slot`, `@radix-ui/react-popover`, `react-day-picker`, `clsx`, `tailwind-merge`.

## Configuration

### ragdalion.json

The config file generated by `ragdalion init`:

```json
{
  "baseDir": "src"
}
```

| Key | Description | Default |
|---|---|---|
| `baseDir` | The directory that maps to your `@/` path alias. All components are installed relative to this. | `src` |

> **Note:** Your project's `tsconfig.json` (or `vite.config.ts`) should have `@/` aliased to the same directory. For example:
> ```json
> {
>   "compilerOptions": {
>     "paths": { "@/*": ["src/*"] }
>   }
> }
> ```

### Project Requirements

- **React 18+** — All components use React
- **Tailwind CSS** — Components are styled with Tailwind utility classes
- **Path alias `@/`** — Your project must have `@/` alias configured pointing to the same `baseDir` (typically `src`)
- **Node.js 18+** — Required runtime for the CLI

## All Available Components — Install Guide

Below is the complete list of every component available in `@ragdalion/cli`. Copy any command to add a component to your project. Dependencies are resolved automatically.

### Utilities

```bash
npx @ragdalion/cli add cn                  # clsx + tailwind-merge utility
npx @ragdalion/cli add format              # Byte formatting utility
```

### Types & Hooks

```bash
npx @ragdalion/cli add file-type           # Upload file type definitions
npx @ragdalion/cli add use-add-files       # Hook for handling file uploads with progress
```

### Basic UI

```bash
npx @ragdalion/cli add button              # Multi-variant button with loading state and icons
npx @ragdalion/cli add button-social       # Social login buttons (Google, Facebook, X)
npx @ragdalion/cli add badge               # Color badges with dot, icon, and removable variants
npx @ragdalion/cli add accordion           # Collapsible accordion sections
npx @ragdalion/cli add alert               # Alert banners (info, success, warning, error)
npx @ragdalion/cli add breadcrumb          # Breadcrumb navigation
npx @ragdalion/cli add card                # Card container with header, content, footer
npx @ragdalion/cli add card-stat-grid      # Stat grid cards with tooltips
npx @ragdalion/cli add checkbox            # Checkbox input
npx @ragdalion/cli add calendar            # Calendar / date picker component
npx @ragdalion/cli add date-picker         # Single date picker with popover
npx @ragdalion/cli add date-range-picker   # Date range picker with popover
npx @ragdalion/cli add delete-button       # Small delete action button
npx @ragdalion/cli add dialog              # Dialog / modal primitives
npx @ragdalion/cli add file-icon           # File type icon based on MIME type
npx @ragdalion/cli add modal               # Pre-built modals 
npx @ragdalion/cli add modal-confirm       # modal confrim
npx @ragdalion/cli add modal-delete        # modal delete
npx @ragdalion/cli add modal-failed        # modal failed
npx @ragdalion/cli add modal-form          # modal form
npx @ragdalion/cli add modal-preview       # modal preview
npx @ragdalion/cli add modal-success       # modal success
npx @ragdalion/cli add pagination          # Pagination with page numbers
npx @ragdalion/cli add pagination-default  # Pagination with rows-per-page select
npx @ragdalion/cli add loader-data         # Loader data
npx @ragdalion/cli add popover             # Popover component
npx @ragdalion/cli add progress            # Progress bar
npx @ragdalion/cli add scroll-area         # Custom scroll area
npx @ragdalion/cli add select              # Select dropdown
npx @ragdalion/cli add switch              # Select dropdown
npx @ragdalion/cli add sort                # Sort indicator icon
npx @ragdalion/cli add table               # Table primitives with sorting
npx @ragdalion/cli add table-wrapper               # Table primitives with sorting
npx @ragdalion/cli add table-filter               # Table primitives with sorting
npx @ragdalion/cli add tabs                # Tabs component
npx @ragdalion/cli add tooltip             # Tooltip component
npx @ragdalion/cli add tooltip-wrapper     # Simple tooltip wrapper
```

### Forms

```bash
npx @ragdalion/cli add input 
npx @ragdalion/cli add input-password
npx @ragdalion/cli add search
npx @ragdalion/cli add label               # Form label
npx @ragdalion/cli add select-custom       # Custom styled select with label
```

### Authentication Pages

```bash
npx @ragdalion/cli add auth-login              # Login page with social auth
npx @ragdalion/cli add auth-register           # Register page with password validation
npx @ragdalion/cli add auth-forgot-password    # Forgot password / reset flow
npx @ragdalion/cli add auth-email-verification # Email verification page
```

### Error Pages

```bash
npx @ragdalion/cli add error-forbidden     # 403 Forbidden page
npx @ragdalion/cli add error-not-found     # 404 Not Found page
npx @ragdalion/cli add error-server        # 500 Internal Server Error page
```

### File Upload

```bash
npx @ragdalion/cli add avatar-upload           # Avatar image upload with preview
npx @ragdalion/cli add document-upload         # Document file upload with progress bar
npx @ragdalion/cli add drag-drop-upload        # Drag & drop file upload zone
npx @ragdalion/cli add file-upload             # Single file upload with preview
npx @ragdalion/cli add image-gallery-upload    # Image gallery upload grid
npx @ragdalion/cli add inline-upload           # Inline file upload with file list
npx @ragdalion/cli add multiple-file-upload    # Multiple file upload with previews
npx @ragdalion/cli add video-upload            # Video file upload with progress
```

### Modals

```bash
npx @ragdalion/cli add modal-preview       # File preview modal
```

### Charts — General

```bash
npx @ragdalion/cli add chart-card          # Chart wrapper card with badge
npx @ragdalion/cli add main-chart          # Main area chart dashboard widget
npx @ragdalion/cli add horizontal-bar      # Horizontal bar chart
npx @ragdalion/cli add vertical-bar        # Vertical bar chart
npx @ragdalion/cli add snake-bar           # Snake/area bar chart
```

### Charts — Bar

```bash
npx @ragdalion/cli add bar-simple          # Simple bar chart
npx @ragdalion/cli add bar-grouped         # Grouped bar chart
npx @ragdalion/cli add bar-stacked         # Stacked bar chart
npx @ragdalion/cli add bar-horizontal      # Horizontal bar chart variant
npx @ragdalion/cli add bar-category        # Category bar chart
npx @ragdalion/cli add bar-spark-line      # Spark line bar chart
```

### Charts — Line

```bash
npx @ragdalion/cli add line-simple         # Simple line chart
npx @ragdalion/cli add line-multi          # Multi-line chart
npx @ragdalion/cli add line-area           # Area line chart
npx @ragdalion/cli add line-stacked-area   # Stacked area chart
npx @ragdalion/cli add line-stock          # Stock price line chart
npx @ragdalion/cli add line-toggle         # Toggle-able multi line chart
```

### Charts — Pie

```bash
npx @ragdalion/cli add pie-simple          # Simple pie chart
npx @ragdalion/cli add pie-donut           # Donut chart
npx @ragdalion/cli add pie-donut-stats     # Donut chart with stats
npx @ragdalion/cli add pie-half-donut      # Half donut chart
npx @ragdalion/cli add pie-labeled         # Labeled pie chart
npx @ragdalion/cli add pie-multi-donut     # Multi-ring donut chart
```

### Charts — Radar

```bash
npx @ragdalion/cli add radar-simple        # Simple radar chart
npx @ragdalion/cli add radar-filled        # Filled radar chart
npx @ragdalion/cli add radar-comparison    # Radar comparison chart
npx @ragdalion/cli add radar-interactive   # Interactive radar with toggles
npx @ragdalion/cli add radar-multi-team    # Multi-team radar chart
npx @ragdalion/cli add radar-spider        # Spider radar chart
```

### Charts — Scatter

```bash
npx @ragdalion/cli add scatter-simple      # Simple scatter plot
npx @ragdalion/cli add scatter-bubble      # Bubble chart
npx @ragdalion/cli add scatter-cluster     # Cluster scatter plot
npx @ragdalion/cli add scatter-correlation # Correlation scatter plot
npx @ragdalion/cli add scatter-jitter      # Jitter scatter plot
npx @ragdalion/cli add scatter-risk-return # Risk return scatter with zones
```

### Install All Components at Once

```bash
npx @ragdalion/cli add --all
```

> **Total: 83 components** — All dependencies are resolved automatically when you install any component.

## How It Works

1. Templates are bundled inside the npm package under `templates/`
2. Each component is defined in an internal registry with its file paths, npm dependencies, and inter-component dependencies
3. Running `ragdalion add <component>` copies the source files into your project's `baseDir`
4. Required npm packages are auto-installed using your detected package manager (npm/yarn/pnpm/bun)
5. You get full ownership of the code — edit, extend, or restyle freely

## Development

```bash
# Install dependencies
bun install

# Build
bun run build

# Build in watch mode
bun run dev

# Type check
bun run typecheck
```

## License

MIT