@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

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

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

Quick Start

# 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.

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.

# 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.

# 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.

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.

# 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.

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:

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

hikma.config.js

Created by hikma init, stores framework configuration:

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

.hikmaui/components.json

Auto-generated, tracks installed components:

{
  "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

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

Update existing component

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

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

# Check project setup
hikma doctor

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

Dependencies not installing

# Manual installation
pnpm add @hikmaui/core

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

Component not found

# 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 for guidelines.

Development

# 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