Simple UI CLI

The command-line interface for Simple UI - add beautiful components to any React project.

Installation

Global Installation (Recommended)

npm install -g @simple-ui/cli
# or
pnpm add -g @simple-ui/cli
# or
yarn global add @simple-ui/cli

Local Installation

npm install @simple-ui/cli
# or
pnpm add @simple-ui/cli
# or
yarn add @simple-ui/cli

Quick Start

1. Initialize your project

simple-ui init

This command will:

• Create a components.json configuration file
• Set up the required directory structure (src/components/ui, src/lib)
• Create a utils.ts file with the cn helper function
• List the dependencies you need to install

2. Add components

# Add a single component
simple-ui add button

# Add multiple components at once
simple-ui add button card badge input

# See what's available
simple-ui list

3. Install dependencies

Install the required dependencies shown after running init:

npm install clsx tailwind-merge class-variance-authority @radix-ui/react-slot

Commands

init

Initialize Simple UI in your project.

simple-ui init [options]

Options:

• --cwd <path> - The working directory. Defaults to current directory
• -y, --yes - Skip confirmation prompts

Example:

# Initialize in current directory
simple-ui init

# Initialize with confirmation skip
simple-ui init --yes

# Initialize in specific directory
simple-ui init --cwd ./my-project

add

Add one or more components to your project.

simple-ui add [components...] [options]

Options:

• --cwd <path> - The working directory. Defaults to current directory
• -y, --yes - Skip confirmation prompts
• -o, --overwrite - Overwrite existing files without asking
• -p, --path <path> - Custom path for components (default: src/components/ui)

Examples:

# Add a single component
simple-ui add button

# Add multiple components
simple-ui add button card badge

# Overwrite existing files
simple-ui add button --overwrite

# Add to custom path
simple-ui add button --path ./components/ui

# Skip confirmations
simple-ui add button card --yes

list

List all available components with their categories and dependencies.

simple-ui list

Output example:

📦 Available Components:

Form:
  • button (deps: @radix-ui/react-slot, class-variance-authority)
  • input

Navigation:
  • animatedtabs (deps: framer-motion)

Layout:
  • card

Display:
  • badge (deps: class-variance-authority)

Usage: simple-ui add <component-name>
Example: simple-ui add button card

Available Components

| Component | Description | Category | Dependencies | | -------------- | ---------------------------------------------------------- | ---------- | ---------------------------------------------- | | button | A versatile button component with multiple variants | Form | @radix-ui/react-slot, class-variance-authority | | input | A styled input field component | Form | - | | card | A flexible card container with header, content, and footer | Layout | - | | badge | Small status indicators and labels | Display | class-variance-authority | | animatedtabs | Animated tab navigation component | Navigation | framer-motion |

Configuration

The CLI uses a components.json file to configure your project:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": false,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "src/index.css",
    "baseColor": "slate",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide"
}

Prerequisites

• Node.js 16.x or higher
• A React project with Tailwind CSS configured
• TypeScript (recommended)

Required Dependencies

Most components require these base dependencies:

npm install clsx tailwind-merge

Individual components may require additional dependencies:

• Button, Badge: class-variance-authority
• Button: @radix-ui/react-slot
• AnimatedTabs: framer-motion

Tailwind CSS Setup

Ensure your tailwind.config.js includes the components directory:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./src/**/*.{js,ts,jsx,tsx,mdx}",
    // Add other paths as needed
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};

Project Structure

After running simple-ui init, your project structure will look like:

your-project/
├── src/
│   ├── components/
│   │   └── ui/           # Components added here
│   │       ├── button.tsx
│   │       ├── card.tsx
│   │       └── ...
│   └── lib/
│       └── utils.ts      # Utility functions
├── components.json       # Configuration file
└── package.json

Usage in Your Components

After adding components, import and use them in your React components:

import { Button } from "@/components/ui/button";
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";

export function MyComponent() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Hello World</CardTitle>
      </CardHeader>
      <CardContent>
        <Button variant="default">Click me</Button>
      </CardContent>
    </Card>
  );
}

Troubleshooting

CLI not found after global installation

If you get "command not found" after global installation:

1. Check if the global bin directory is in your PATH
2. Try reinstalling: npm uninstall -g @simple-ui/cli && npm install -g @simple-ui/cli
3. Use npx: npx @simple-ui/cli list

Import paths not working

Make sure you have path aliases configured in your tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

For Vite projects, also add to vite.config.ts:

import path from "path";
import { defineConfig } from "vite";

export default defineConfig({
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
});

Components not styled correctly

Ensure you have:

1. Tailwind CSS properly configured
2. Required dependencies installed
3. CSS variables defined in your globals.css

Contributing

Contributions are welcome! Please see our main Contributing Guide.

License

Licensed under the MIT license.