Morpha UI CLI

🚀 Quick Start

Installation & Usage

No installation required! Use with your preferred package manager:

# npm
npx morpha-ui@latest add button

# pnpm
pnpm dlx morpha-ui@latest add button

# yarn
yarn dlx morpha-ui@latest add button

# bun
bunx --bun morpha-ui@latest add button

Prerequisites

• A Next.js project with shadcn/ui configured
• Node.js 16+
• A valid components.json file in your project root

📦 Components

🆓 Free Components

Access these components without authentication:

• button - Enhanced button variants
• card - Advanced card layouts
• input - Improved input fields
• badge - Status and category badges
• And more...

💎 Pro Components

Premium components requiring authentication:

• data-table - Advanced data tables with sorting, filtering
• chart - Interactive charts and visualizations
• dashboard - Complete dashboard layouts
• advanced-form - Multi-step forms with validation
• calendar - Feature-rich calendar components
• And many more...

🔧 Commands

Add Components

morpha-ui add <component-name>

Add a component to your project. The CLI automatically detects if it's a free or pro component and handles authentication accordingly.

Examples:

morpha-ui add button           # Add free component
morpha-ui add data-table       # Add pro component (requires auth)
morpha-ui add card --overwrite # Overwrite existing component

Authentication

morpha-ui auth

Configure your email and secret key for accessing pro components.

You'll be prompted to enter:

• Email: Your registered email address
• Secret Key: Get yours at https://morphaui.com/profile

View Configuration

morpha-ui config

Display your current authentication status and configuration.

Clear Configuration

morpha-ui config clear

Remove stored authentication credentials.

List Components

morpha-ui list

Display all available free and pro components.

Get Help

morpha-ui --help
morpha-ui -h

🔐 Pro Access

Getting Started with Pro

1. Sign up at morphaui.com
2. Subscribe to a Pro plan
3. Get your secret key from your profile
4. Configure the CLI:

   morpha-ui auth

Authentication Process

When you try to add a pro component, the CLI will:

1. ✅ Validate your credentials with our servers
2. 🔍 Verify your pro subscription status
3. 📦 Download the component if authorized
4. ⚡ Install it into your project

Security

• Credentials are stored locally in ~/.morpha-ui-config.json
• Secret keys are masked when displayed
• All communication is encrypted (HTTPS)

🛠️ Advanced Usage

Shadcn/ui Compatibility

The CLI is fully compatible with shadcn/ui. You can use any shadcn/ui command:

morpha-ui init                 # Initialize shadcn/ui
morpha-ui add shadcn-button    # Add original shadcn components
morpha-ui diff                 # Check for updates

Configuration File

The CLI stores configuration in ~/.morpha-ui-config.json:

{
  "email": "[email protected]",
  "secretKey": "your-secret-key"
}

Component Overrides

morpha-ui add button --overwrite    # Force overwrite existing files
morpha-ui add card --diff           # Show differences before installing

🔍 Troubleshooting

Common Issues

"Authentication required" Error

❌ Authentication required for Pro component
💡 Configure your credentials: morpha-ui auth
🔗 Get your secret key: https://morphaui.com/profile

Solution: Run morpha-ui auth and enter your credentials.

"Access forbidden" Error

❌ Access forbidden
💡 Invalid secret key or email address
🔧 Reconfigure: morpha-ui auth

Solution:

• Verify your secret key at morphaui.com/profile
• Check your email address is correct
• Ensure your subscription is active

"Component not found" Error

❌ Component "xyz" not found
📋 See available components: morpha-ui list

Solution: Run morpha-ui list to see available components.

Network Issues

❌ Network error - unable to connect to server
🌐 Check your internet connection
🔄 Try again in a few moments

Solution:

• Check your internet connection
• Verify firewall settings
• Try again after a few minutes

Rate Limiting

If you encounter rate limiting issues:

• Wait a few minutes before retrying
• Avoid automated scripts that make rapid requests
• Contact support if you need higher limits

Getting Help

• 📚 Documentation: morphaui.com/docs
• 💬 Support: morphaui.com/support
• 🐛 Bug Reports: GitHub Issues

🎯 Examples

Basic Component Addition

# Add a free component
morpha-ui add button

# Add a pro component (with auto-validation)
morpha-ui auth
morpha-ui add data-table

Project Setup Workflow

# 1. Initialize shadcn/ui (if not done)
morpha-ui init

# 2. Configure pro access
morpha-ui auth

# 3. Add components
morpha-ui add button card input
morpha-ui add data-table chart dashboard

# 4. Check what's available
morpha-ui list

Team Workflow

# Each team member configures their own credentials
morpha-ui auth

# Components can be added consistently across the team
morpha-ui add design-system-button
morpha-ui add advanced-form

🔄 Migration

From shadcn/ui CLI

Morpha UI CLI is a drop-in replacement:

# Before
npx shadcn-ui@latest add button

# After
npx morpha-ui@latest add button

All existing shadcn/ui commands work identically.

📋 Requirements

System Requirements

• Node.js: Version 16 or higher
• Package Manager: npm, pnpm, yarn, or bun
• Operating System: Windows, macOS, or Linux

Project Requirements

• Framework: Next.js (App Router or Pages Router)
• UI Library: shadcn/ui configured
• Configuration: Valid components.json file
• Dependencies: React, TypeScript (recommended)

🚦 Status & Monitoring

The CLI includes built-in status checking:

• ✅ Authentication status in morpha-ui config
• 🔍 Component validation before download
• 📊 Real-time error handling with helpful suggestions
• ⚡ Performance monitoring for optimal experience

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/c4sto/morpha-ui.git
cd cli
npm install
npm run dev

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• Website: morphaui.com
• Documentation: morphaui.com/docs
• Pricing: morphaui.com/pricing
• GitHub: github.com/morphaui/cli