@servlyadmin/cli

Generate strongly-typed component wrappers for Servly components in your codebase.

Features

• 🎯 Full TypeScript Support - Autocomplete, type checking, hover docs
• 🔧 Multi-Framework - React, Vue, Svelte, Angular, Solid
• 🤖 AI-Friendly - Generated context files for Cursor, Windsurf, MCP
• ⚡ Fast - Incremental updates, local caching
• 📦 Zero Runtime Overhead - Types are compile-time only
• 🎨 Interactive Mode - Visual component picker with categories
• 🌳 Dependency Visualization - See component dependency trees
• 💡 Smart Error Messages - Helpful suggestions when things go wrong

Quick Start

# Install
npm install -D @servlyadmin/cli

# Initialize
npx servly init

# Generate typed components
npx servly generate

Usage

// Import generated components
import { PricingCard, ContactForm } from './.servly';

// Full TypeScript support!
<PricingCard
  title="Pro Plan"           // ✓ string
  price={2999}               // ✓ number
  features={['API Access']}  // ✓ string[]
  onSelect={(id) => {}}      // ✓ (id: string) => void
/>

Commands

servly init

Initialize .servly directory in your project.

npx servly init
npx servly init --framework react
npx servly init --output .servly

Options:

• -f, --framework <framework> - Target framework (react, vue, svelte, angular, solid, auto)
• -o, --output <dir> - Output directory (default: .servly)
• -r, --registry <url> - Registry URL
• --no-ai-context - Skip generating AI context files

servly generate

Generate typed component wrappers from registry.

npx servly generate
npx servly generate --force
npx servly generate --components pricing-card,contact-form
npx servly generate --interactive

Options:

• --force - Force regeneration of all components
• -f, --framework <framework> - Target framework
• -c, --components <ids> - Comma-separated component IDs to generate
• -e, --exclude <ids> - Comma-separated component IDs to exclude
• --dry-run - Show what would be generated
• -i, --interactive - Interactive mode with component picker

Interactive Mode

Use --interactive or -i for a visual component selection experience:

npx servly generate --interactive

🎨 Servly Interactive Component Generator
──────────────────────────────────────────────────

Available Components:

  📁 Cards
      1. Pricing Card (5 props) - A pricing card for SaaS pages
      2. Feature Card (3 props) - Display a feature with icon

  📁 Forms
      3. Contact Form (4 props) - Contact form with validation

──────────────────────────────────────────────────

Selection Options:
  • Enter numbers separated by commas: 1,3,5
  • Enter a range: 1-5
  • Enter "all" to select all components
  • Enter "q" to cancel

Select components: 1,3

servly watch

Watch for registry changes and regenerate.

npx servly watch
npx servly watch --interval 60000

Options:

• -i, --interval <ms> - Polling interval in milliseconds (default: 30000)

servly validate

Validate generated files.

npx servly validate

servly info <componentId>

Show detailed information about a component.

npx servly info pricing-card

servly deps <componentId>

Show component dependency tree.

npx servly deps pricing-card
# Output:
# pricing-card (1.2.0)
# ├── feature-list (^1.0.0)
# │   └── icon-check (^2.0.0)
# └── button-primary (^1.2.0)

servly list

List available components.

npx servly list
npx servly list --category cards
npx servly list --search pricing

Options:

• -c, --category <category> - Filter by category
• -s, --search <query> - Search components

Configuration

Create servly.config.json in your project root:

{
  "registry": {
    "url": "https://core-api.servly.app/v1/views/registry",
    "apiKey": "your-api-key"
  },
  "generate": {
    "outputDir": ".servly",
    "framework": "react",
    "typescript": true,
    "includeAIContext": true
  },
  "components": {
    "include": ["pricing-*", "contact-*"],
    "exclude": ["internal-*"]
  }
}

Generated Structure

.servly/
├── index.ts              # Main exports
├── manifest.json         # Component metadata
├── ai-context.md         # AI documentation
├── .cursorrules          # Cursor AI rules
├── mcp-tools.json        # MCP server tools
├── types/
│   ├── index.d.ts        # Type exports
│   └── *.d.ts            # Per-component types
├── components/
│   ├── index.ts          # Component exports
│   └── *.tsx             # Component wrappers
└── hooks/
    ├── useServlyComponent.ts
    └── useServlyRegistry.ts

Environment Variables

• SERVLY_REGISTRY_URL - Override registry URL
• SERVLY_API_KEY - API key for authentication
• SERVLY_FRAMEWORK - Default framework

Error Messages

The CLI provides helpful error messages with suggestions:

# Authentication error
Error: Failed to fetch components from registry

Authentication required. Try one of:
  1. Add API key to servly.config.json:
     { "registry": { "apiKey": "sk_live_xxx" } }
  2. Set environment variable:
     export SERVLY_API_KEY=sk_live_xxx
  3. Get an API key at: https://servly.app/developers/api-keys

# Component not found
No components found to generate

Did you mean one of these?
  • pricing-card - Pricing Card
  • pricing-table - Pricing Table

Run 'servly list' to see available components.

Requirements

• Node.js >= 18.0.0
• One of: React, Vue, Svelte, Angular, or Solid

License

MIT