@surreal-ui/cli 💻🎨

The official Command Line Interface for Surreal UI — an AI-powered cross-platform UI component library.

Directly inspect and install multi-aesthetic components into your project across Svelte 5, React TSX, and WebComponents.

🚀 Quick Start

Run instantly with npx, pnpm dlx, or bunx without prior installation:

# List all available components and styles in the catalog
npx @surreal-ui/cli list

# Add a component with a specific aesthetic into your project
npx @surreal-ui/cli add button --aesthetic glassmorphism

# Specify target framework (defaults to svelte, options: svelte, react, web)
npx @surreal-ui/cli add card --aesthetic neubrutalism --framework react

🌐 Public Registry Endpoints

The Surreal UI component registry is publicly accessible at https://ui.pixerate.com/r and is 100% compliant with the official Shadcn Registry Schema.

| Endpoint | Description | | ------------------------------------------------------------- | -------------------------------------------------------------------------------- | | https://ui.pixerate.com/r/index.json | Catalog index listing all 60+ components, styles, and dependencies | | https://ui.pixerate.com/r/:component.json | Component definition with default aesthetic | | https://ui.pixerate.com/r/:aesthetic/:component.json | Component definition for a specific aesthetic (e.g. glassmorphism/button.json) | | https://ui.pixerate.com/r/styles/:aesthetic/:component.json | Style-scoped alias endpoint |

🛠️ Usage with Official Shadcn CLI

Because the Surreal UI registry strictly adheres to the Shadcn JSON schema, you can also install Surreal UI components directly using the standard shadcn CLI:

# Add a component using shadcn CLI
npx shadcn@latest add https://ui.pixerate.com/r/button.json

# Add an aesthetic variant using shadcn CLI
npx shadcn@latest add https://ui.pixerate.com/r/glassmorphism/button.json

📖 CLI Commands

add <component>

Downloads and writes the component file directly into your project's component directory (e.g. src/lib/components/ui/ or src/components/ui/).

npx @surreal-ui/cli add <component> [options]

Options:

• -a, --aesthetic <style>: Aesthetic variant (glassmorphism, neubrutalism, minimalist, modern, shadcn, etc.).
• -f, --framework <framework>: Framework target (svelte, react, web). Default: svelte.
• -p, --path <path>: Custom destination directory for component files.
• -o, --overwrite: Overwrite existing files if they already exist.
• -r, --registry <url>: Custom registry endpoint URL (default: https://ui.pixerate.com/r).

list

Lists all available UI component types, descriptions, and available aesthetics.

npx @surreal-ui/cli list [options]

Options:

• -r, --registry <url>: Custom registry endpoint URL (default: https://ui.pixerate.com/r).

init

Initializes Surreal UI configuration and sets up the component destination folder and package manager in your project.

npx @surreal-ui/cli init

diff <component>

Compares your local component implementation against the upstream registry version.

npx @surreal-ui/cli diff <component> [options]

⚙️ Environment Variables

• SURREAL_REGISTRY_URL: Override the default registry URL (default: https://ui.pixerate.com/r).