@moontra/moonui-cli/README.md

CLI tool for MoonUI component library

# MoonUI CLI v2.0.0

[![npm version](https://img.shields.io/npm/v/@moontra/moonui-cli.svg)](https://www.npmjs.com/package/@moontra/moonui-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Official CLI tool for MoonUI component library. Easily add components to your React project with automatic dependency management, Pro license handling, and advanced project setup.

## Installation

You can install MoonUI CLI globally:

```bash
npm install -g @moontra/moonui-cli
```

Or use it directly with npx:

```bash
npx @moontra/moonui-cli@latest <command>
```

## Usage

```bash
moonui <command> [options]
```

### Available Commands

#### Initialize MoonUI

Set up MoonUI in your project. This will:
- Install @moontra/moonui@latest automatically
- Create configuration file (moonui.config.js)
- Set up component directories
- Create utility functions
- Install required dependencies (Tailwind CSS, etc.)
- Set up TypeScript configurations

```bash
moonui init [options]
```

Options:
- `-f, --force`: Overwrite existing configuration
- `-t, --typescript`: Use TypeScript (default)
- `-j, --javascript`: Use JavaScript
- `--pro`: Set up Pro license during initialization

#### Authentication Management

Manage authentication for Pro features with support for team tokens, CI tokens, and personal authentication.

```bash
moonui auth [action] [token]
```

Actions:
- `status`: Show current authentication status
- `set-team`: Set team token for shared use
- `set-ci`: Set CI token for automated builds
- `clear`: Clear stored authentication

Examples:
```bash
# Check authentication status
moonui auth

# Set team token (interactive)
moonui auth set-team

# Set team token directly
moonui auth set-team team_xxxxxxxxxxxxx

# Set CI token for automated builds
moonui auth set-ci ci_xxxxxxxxxxxxx

# Clear authentication
moonui auth clear
```

**Team Authentication:**
```bash
# For teams using MoonUI Pro
moonui auth set-team team_your_token_here

# This creates:
# - .moonui-env file with the token
# - .env.local for Next.js projects
# Team members can source .moonui-env or add to their shell profile
```

**CI/CD Authentication:**
```bash
# Set CI token
moonui auth set-ci ci_your_token_here

# Then add to your CI environment:
# GitHub Actions: Add as secret MOONUI_CI_TOKEN
# Vercel/Netlify: Add as environment variable
```

#### Add Components

Add MoonUI components to your project.

```bash
moonui add [components...] [options]
```

Options:
- `-a, --all`: Add all components
- `-p, --path <path>`: Custom output path for components
- `-f, --force`: Overwrite existing components

Examples:
```bash
# Add free components (from @moontra/moonui)
moonui add button card avatar

# Add pro components (requires @moontra/moonui-pro@latest)
moonui add data-table
# Will prompt: npm install @moontra/moonui-pro@latest

# Add all components
moonui add --all

# Interactive mode
moonui add
```

**How it works**:
- By default, CLI fetches the latest component code from our registry
- Components are added to your project directory for full customization
- Pro components create wrapper patterns for the NPM package

**Import pattern for all components**:
```tsx
// Free components (from your project)
import { Button } from "@/components/ui/button"
import { Card } from "@/components/ui/card"

// Pro components (from your project)
import { DataTable } from "@/components/pro/data-table"
```

**Registry Options**:
```bash
# Default: Use registry (recommended)
moonui add button

# Use local templates (free components only)
moonui add button --no-registry
```

#### List Components

List available MoonUI components:

```bash
moonui list [options]
```

Options:
- `-c, --category <category>`: Filter components by category
- `-d, --detail`: Show detailed information about components

#### Manage Themes

Manage MoonUI themes:

```bash
moonui theme [options]
```

Options:
- `-c, --create <name>`: Create a new theme
- `-e, --export <path>`: Export current theme to a file
- `-i, --import <path>`: Import theme from a file
- `-l, --list`: List available themes

#### License Management (New in v2.0.0)

Manage your MoonUI Pro license:

```bash
moonui license [options]
```

Options:
- `-s, --set <key>`: Set your Pro license key
- `-v, --verify`: Verify current license
- `-r, --remove`: Remove license key
- `-i, --info`: Show license information

#### Install Packages (New in v2.0.0)

Install MoonUI packages with proper dependency management:

```bash
moonui install [packages...] [options]
```

Options:
- `--pro`: Install Pro package with license verification
- `--latest`: Install latest versions
- `--dev`: Install as dev dependencies

Examples:
```bash
# Install base package
moonui install

# Install Pro package (requires license)
moonui install --pro

# Install specific versions
moonui install @moontra/moonui@2.0.0
```

## NPM Packages (v2.0.0)

MoonUI provides two NPM packages:

### @moontra/moonui (Free) - v2.0.0
- **50+ production-ready components** including interactive and performance components
- **New Components**: Magnetic Button, Spotlight Card, Gesture Drawer, Hover Card 3D, Swipeable Card
- **Performance Components**: Virtual List, Memory Efficient Data, Lazy Loading
- **Full source code access** via CLI
- **MIT License**
- **Zero runtime license checks**

### @moontra/moonui-pro (Pro) - v2.0.0
- **Advanced enterprise components**: DataTable, Charts, Calendar Pro, Rich Text Editor Pro
- **New in v2.0.0**: Event Dialog System, Slash Commands, Advanced Chart Types
- **Performance optimizations**: Virtual scrolling, memory efficiency
- **All dependencies included** (no extra packages needed)
- **Requires active license** (build-time verification only)
- **Commercial License**
- **Priority support and updates**

### @moontra/moonui-cli (CLI) - v2.0.0
- **Enhanced project setup** with automatic dependency management
- **Pro license management** with verification
- **Advanced component installation** with registry support
- **Theme management** system
- **Package installation** helpers

## Configuration

MoonUI uses a `moonui.config.js` file:

```javascript
module.exports = {
  paths: {
    components: './src/components/ui',
    utils: './src/lib',
  },
  // ... more options
}
```

## Environment Variables

The MoonUI CLI supports environment variables for local development:

```bash
# For local development (when developing MoonUI itself)
export MOONUI_API_BASE="http://localhost:3000"
export MOONUI_AUTH_URL="http://localhost:3000/cli-auth"
export MOONUI_REGISTRY_URL="http://localhost:3000/api/registry"

# For production (default values - no need to set)
# MOONUI_API_BASE="https://moonui.dev"
# MOONUI_AUTH_URL="https://moonui.dev/cli-auth"
# MOONUI_REGISTRY_URL="https://moonui.dev/api/registry"
```

**Where to set these variables:**

1. **Temporary (current terminal session only):**
   ```bash
   export MOONUI_API_BASE="http://localhost:3000"
   moonui login
   ```

2. **Permanent (for all terminal sessions):**
   
   **macOS/Linux:** Add to `~/.bashrc`, `~/.zshrc`, or `~/.profile`:
   ```bash
   echo 'export MOONUI_API_BASE="http://localhost:3000"' >> ~/.zshrc
   source ~/.zshrc
   ```
   
   **Windows:** Set via System Properties > Environment Variables or PowerShell:
   ```powershell
   [System.Environment]::SetEnvironmentVariable('MOONUI_API_BASE', 'http://localhost:3000', 'User')
   ```

3. **Project-specific:** Create a `.env` file in your project root (requires dotenv):
   ```env
   MOONUI_API_BASE=http://localhost:3000
   MOONUI_AUTH_URL=http://localhost:3000/cli-auth
   MOONUI_REGISTRY_URL=http://localhost:3000/api/registry
   ```

**Note:** These environment variables are only needed when developing MoonUI itself. Regular users should not set these variables.

## Support

- Documentation: [moonui.dev/docs](https://moonui.dev/docs)
- GitHub Issues: [Report bugs](https://github.com/moontra/moonui-cli/issues)
- Discord: [Join our community](https://discord.gg/moonui)

## License

MIT