npm package: @hikmaui/cli
Description: Production-ready CLI for HikmaUI - Interactive component management with auto-install, version tracking, diff, and smart updates
Author: HikmaUI Team
Latest version: 0.4.0

# @hikmaui/cli

Official CLI for HikmaUI - The modern, zero-dependency UI component library.

## Features

✨ **Interactive Component Selection** - Beautiful checkbox UI for browsing and selecting components
🔍 **Smart Search & Filter** - Find components by name, description, category, or tags
📦 **Auto Dependency Management** - Automatically detects and installs required dependencies
🔄 **Intelligent Updates** - Version tracking with diff preview before updates
🗑️ **Component Removal** - Clean up unwanted components with confirmation
✅ **Project Validation** - Comprehensive health checks with actionable fixes
🎨 **Framework Agnostic** - Works with React, Vue, Svelte, and vanilla JavaScript

## Installation

```bash
# Global installation (recommended)
npm install -g @hikmaui/cli

# Or use with npx
npx @hikmaui/cli@latest init
```

## Quick Start

```bash
# 1. Initialize HikmaUI in your project
hikma init

# 2. Add components (interactive mode)
hikma add

# 3. Or add specific components
hikma add button card modal

# 4. Start building! 🚀
```

## Commands

### `hikma init`

Initialize HikmaUI in your project with interactive setup.

```bash
hikma init              # Interactive setup
hikma init --yes        # Use defaults, skip prompts
```

**What it does:**
- Detects your framework (React, Vue, Svelte, Next.js, etc.)
- Creates `hikma.config.js` with your preferences
- Creates `hikma.json` for CLI configuration
- Sets up components directory

---

### `hikma add [components...]`

Add components to your project with smart dependency management.

```bash
# Interactive mode - browse and select with checkbox UI
hikma add

# Add specific components
hikma add button input card

# Add all components
hikma add --all

# Force update even if same version
hikma add button --force

# Skip confirmation for existing components
hikma add button --overwrite

# Skip automatic dependency installation
hikma add button --skip-install
```

**Features:**
- 📦 Auto-installs dependencies (`@hikmaui/core`)
- 🔄 Detects package manager (pnpm/npm/yarn/bun)
- ⚡ Progress indicators for bulk operations
- 🎯 Version tracking in `.hikmaui/components.json`
- ✨ Interactive component selection
- 💡 Smart suggestions for typos

**Options:**
- `--all` - Add all 20 components at once
- `--overwrite` - Overwrite existing components without confirmation
- `--force` - Force update even if version is the same
- `--skip-install` - Skip automatic dependency installation

---

### `hikma list`

List all available components with filtering and search.

```bash
# List all components
hikma list

# Filter by category
hikma list --category foundation
hikma list --category navigation

# Search by name or description
hikma list --search input
hikma list --search "form control"

# Filter by tag
hikma list --tag forms

# Show detailed information
hikma list --verbose
```

**Categories:**
- `foundation` - Button, Input, Card, Badge, Checkbox, Radio, Switch, Select (8 components)
- `layout` - Container (1 component)
- `overlay` - Modal, Tooltip (2 components)
- `feedback` - Alert, Toast, Progress, Skeleton (4 components)
- `navigation` - Tabs, Accordion, Breadcrumb, Pagination, DropdownMenu (6 components)
- `data-display` - Avatar (1 component)

**Options:**
- `--category <category>` - Filter by category
- `--search <query>` - Fuzzy search by name or description
- `--tag <tag>` - Filter by tag
- `-v, --verbose` - Show detailed component information

---

### `hikma diff <component>`

Show differences between installed and registry versions.

```bash
hikma diff button
```

**Features:**
- 🔍 Line-by-line diff with color coding
- ✅ Green for additions (+)
- ❌ Red for deletions (-)
- 📊 Summary with file count and line changes
- 💡 Suggests update command if differences found

**Example output:**
```
🔍 Checking diff for "button"...

Installed version: 0.7.0
Registry version:  0.8.0

📄 Button.tsx

+ const newFeature = true;
- const oldFeature = false;

Summary:
  1 file(s) changed, 1 insertion(s), 1 deletion(s)

To update: hikma add button --overwrite
```

---

### `hikma remove <component>`

Remove a component from your project.

```bash
# Interactive removal (with confirmation)
hikma remove button

# Force removal (skip confirmation)
hikma remove button --force
```

**Features:**
- 🗑️ Shows files to be deleted before removal
- ✅ Confirmation prompt (unless `--force`)
- 📝 Updates version tracking file
- 🧹 Removes empty directories

**Options:**
- `--force` - Skip confirmation prompt

---

### `hikma doctor`

Validate your project setup and configuration.

```bash
hikma doctor
```

**Checks:**
1. ✅ HikmaUI Configuration (`hikma.json`)
2. ✅ Config File (`hikma.config.js`)
3. ✅ Components Directory
4. ✅ `@hikmaui/core` Dependency
5. ✅ React Version (if using React)
6. ✅ TypeScript Configuration
7. ✅ Package Manager (pnpm/npm/yarn/bun)
8. ✅ Node.js Version

**Example output:**
```
🔍 HikmaUI Doctor - Project Health Check

✓ HikmaUI Configuration
  Configuration found (react)

✓ @hikmaui/core Dependency
  @hikmaui/core installed (^0.3.0)

✓ React Version
  React 19.0.0 installed

✓ Node.js Version
  Node.js 20.10.0 installed

Summary:
  8 passed | 0 warnings | 0 failed

✓ Project is healthy! All checks passed.
```

---

## Configuration

### `hikma.json`

Created by `hikma init`, stores CLI configuration:

```json
{
  "framework": "react",
  "styling": "hybrid",
  "features": ["darkMode", "animations", "forms"],
  "componentsDir": "./src/components"
}
```

### `hikma.config.js`

Created by `hikma init`, stores framework configuration:

```javascript
export default {
  content: [
    './src/**/*.{html,js,jsx,ts,tsx}',
  ],
  darkMode: 'class',
  theme: {
    extend: {
      // Your custom theme
    },
  },
};
```

### `.hikmaui/components.json`

Auto-generated, tracks installed components:

```json
{
  "components": {
    "button": {
      "version": "0.8.0",
      "installedAt": "2025-11-03T10:30:00Z",
      "files": [
        "src/components/ui/button/Button.ts",
        "src/components/ui/button/Button.tsx",
        "src/components/ui/button/index.ts"
      ]
    }
  },
  "updatedAt": "2025-11-03T10:30:00Z"
}
```

---

## Workflow Examples

### Add components interactively

```bash
hikma add
# → Opens checkbox UI
# → Select: Button, Input, Card
# → Press Enter
# → Auto-installs @hikmaui/core
# → ✓ Components ready to use!
```

### Update existing component

```bash
hikma add button
# → ⚠ Component "button" already exists
# →   Installed: v0.7.0
# →   Registry:  v0.8.0
# → Update "button" from v0.7.0 to v0.8.0? (y/n)
```

### Search and add

```bash
hikma list --search form
# → Shows: Input, Select, Checkbox, Radio

hikma add input select checkbox radio
# → [1/4] Installing input...
# → [2/4] Installing select...
# → [3/4] Installing checkbox...
# → [4/4] Installing radio...
# → ✓ Added 4 component(s)
```

---

## Comparison: HikmaUI vs shadcn/ui

| Feature | HikmaUI CLI | shadcn/ui CLI |
|---------|-------------|---------------|
| **Interactive Mode** | ✅ Checkbox UI | ✅ Checkbox UI |
| **Auto Dependencies** | ✅ All managers | ✅ npm/pnpm/yarn |
| **Version Tracking** | ✅ `.hikmaui/` | ❌ No tracking |
| **Diff Command** | ✅ Line-by-line | ✅ Basic diff |
| **Search/Filter** | ✅ Name, desc, tag | ⚠️ Basic search |
| **Health Checks** | ✅ 8 checks | ⚠️ Basic validation |
| **Component Removal** | ✅ With tracking | ❌ Manual only |
| **Progress Indicators** | ✅ [3/20] style | ❌ No progress |
| **Typo Suggestions** | ✅ Levenshtein | ❌ No suggestions |
| **Zero Dependencies** | ✅ Core only | ❌ Multiple deps |

**HikmaUI Advantages:**
- Better version tracking and update management
- More comprehensive health checks
- Component removal with cleanup
- Smarter error messages with suggestions
- Zero external dependencies for components

---

## Troubleshooting

### Components not installing

```bash
# Check project setup
hikma doctor

# Force reinstall
hikma add button --overwrite --force
```

### Dependencies not installing

```bash
# Manual installation
pnpm add @hikmaui/core

# Or skip auto-install
hikma add button --skip-install
```

### Component not found

```bash
# List all components
hikma list

# Search for component
hikma list --search <name>

# CLI suggests similar names for typos
hikma add buton
# → ✗ Component "buton" not found in registry.
# → Did you mean:
# →   - button
```

---

## Contributing

We welcome contributions! See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.

### Development

```bash
# Clone repository
git clone https://github.com/hikmaui/hikmaui.git
cd hikmaui

# Install dependencies
pnpm install

# Build CLI
cd packages/cli
pnpm build

# Test locally
npm link
hikma --version
```

---

## License

MIT © HikmaUI Team

---

## Links

- **Website**: https://hikmaui.dev
- **Documentation**: https://hikmaui.dev/docs
- **GitHub**: https://github.com/hikmaui/hikmaui
- **npm**: https://www.npmjs.com/package/@hikmaui/cli
- **Discord**: https://discord.gg/hikmaui

---

**Made with ❤️ by the HikmaUI team**