@astralkit/cli 2.0.1 → 2.1.0

package/README.md

@@ -1,6 +1,6 @@
 # @astralkit/cli
 
-Install and manage AstralKit UI components in your project.
+Install and manage AstralKit UI components, boosters, and workflows in your project.
 
 ## Quick Start
 
@@ -11,10 +11,26 @@ npx @astralkit/cli init
 # Add a component
 npx @astralkit/cli add button-sizes
 
+# Add a booster (feature module)
+npx @astralkit/cli add stripe-payments --booster
+
+# Scaffold a workflow (complete app)
+npx @astralkit/cli add saas-starter --workflow
+
 # Search for components
 npx @astralkit/cli search "pricing table"
 ```
 
+## Content Types
+
+AstralKit distributes three types of content:
+
+| Type | Description | Example |
+|------|-------------|---------|
+| **Components** | Single UI elements with framework variants | Button, Card, Data Table |
+| **Boosters** | Drop-in feature modules (core logic + framework adapters) | Stripe Payments, Auth System |
+| **Workflows** | Complete application scaffolds | SaaS Starter, CRM, Admin Dashboard |
+
 ## Commands
 
 ### `astralkit init`
@@ -27,9 +43,11 @@ astralkit init --framework=react
 astralkit init --dir=src/components/ui
 ```
 
-### `astralkit add <component>`
+### `astralkit add <name>`
+
+Add a component, booster, or workflow to your project.
 
-Add a component to your project. Fetches code from AstralKit and writes it to your components directory.
+#### Adding Components
 
 ```bash
 astralkit add avatar-variants
@@ -37,17 +55,51 @@ astralkit add pricing-table --framework=react
 astralkit add data-table --overwrite
 ```
 
-Options:
+#### Adding Boosters
+
+Boosters install framework-agnostic core files (API routes, webhooks, utilities) and framework-specific adapter files (UI components, hooks).
+
+```bash
+astralkit add stripe-payments --booster
+astralkit add auth-system --booster --framework=nextjs
+astralkit add stripe-payments --booster --overwrite
+```
+
+Core files are written to `src/lib/<booster-slug>/` and adapter files to `src/components/<booster-slug>/` by default. Boosters may specify custom install paths.
+
+#### Adding Workflows
+
+Workflows scaffold a complete application. By default, files are created in a new `./<slug>/` directory.
+
+```bash
+astralkit add saas-starter --workflow
+astralkit add crm --workflow --framework=nextjs
+```
+
+Use `--overlay` to merge workflow files into your current project instead of creating a new directory:
+
+```bash
+astralkit add saas-starter --workflow --overlay
+astralkit add saas-starter --workflow --overlay --overwrite
+```
+
+#### Options
+
 - `-f, --framework` — Framework version (html, react, vue, nextjs, angular, svelte, astro)
 - `--dir` — Override output directory
 - `--overwrite` — Overwrite existing files
+- `--booster` — Install a booster (feature module)
+- `--workflow` — Scaffold a workflow (complete app template)
+- `--overlay` — Merge workflow into current project (workflow only)
 
 ### `astralkit list`
 
-List all available components.
+List available content.
 
 ```bash
-astralkit list
+astralkit list                    # List components
+astralkit list --boosters         # List boosters
+astralkit list --workflows        # List workflows
 astralkit list --category=forms
 astralkit list --framework=react
 astralkit list --pro
@@ -56,11 +108,13 @@ astralkit list --free
 
 ### `astralkit search <query>`
 
-Search for components by name or description.
+Search by name or description.
 
 ```bash
 astralkit search "data table"
 astralkit search "pricing" --framework=react
+astralkit search "stripe" --boosters
+astralkit search "crm" --workflows
 ```
 
 ### `astralkit diff <component>`
@@ -82,7 +136,7 @@ astralkit update button-sizes --force
 
 ### `astralkit login`
 
-Authenticate with AstralKit to access premium components. Opens your browser for secure login.
+Authenticate with AstralKit to access premium content. Opens your browser for secure login.
 
 ```bash
 astralkit login
@@ -96,9 +150,9 @@ Remove stored authentication.
 
 Show current authentication status and subscription plan. Verifies your token with the server.
 
-## Premium Components
+## Premium Content
 
-Some components require a Pro subscription. When you try to add a pro component without authentication:
+Some components, boosters, and workflows require a Pro subscription. When you try to add pro content without authentication:
 
 ```bash
 $ astralkit add pro-data-table
@@ -106,7 +160,7 @@ $ astralkit add pro-data-table
 Authentication required. Run `astralkit login` to authenticate.
 ```
 
-After logging in, pro components install normally:
+After logging in, pro content installs normally:
 
 ```bash
 $ astralkit login
@@ -114,8 +168,22 @@ $ astralkit login
   Email: you@example.com
   Plan:  pro
 
-$ astralkit add pro-data-table
-✔ Added Pro Data Table (react)
+$ astralkit add stripe-payments --booster
+✔ Added booster Stripe Payments (nextjs)
+  Core files → src/lib/stripe-payments/
+    lib/stripe.ts
+    api/webhooks/stripe/route.ts
+  Adapter files → src/components/stripe-payments/
+    components/checkout-button.tsx
+    hooks/use-subscription.ts
+
+  Install required dependencies:
+    npm install stripe @stripe/stripe-js
+
+  Add these environment variables to your .env:
+    STRIPE_SECRET_KEY=
+    STRIPE_PUBLISHABLE_KEY=
+    STRIPE_WEBHOOK_SECRET=
 ```
 
 ## Configuration
@@ -147,6 +215,7 @@ export ASTRALKIT_TOKEN="your-api-token"
 
 # Commands automatically use the env var
 astralkit add button-sizes
+astralkit add stripe-payments --booster
 astralkit whoami
 ```
 
@@ -189,7 +258,7 @@ If you see timeout or connection errors, check your internet connection. The CLI
 ## Requirements
 
 - Node.js 18+
-- An AstralKit account for premium components
+- An AstralKit account for premium content
 
 ## Links
 

package/bin/index.js

@@ -18,7 +18,7 @@ const program = new Command();
 
 program
   .name('astralkit')
-  .description('AstralKit CLI — Install and manage UI components')
+  .description('AstralKit CLI — Install and manage UI components, boosters, and workflows')
   .version(pkg.version);
 
 // ─── init ────────────────────────────────────────────
@@ -31,11 +31,14 @@ program
 
 // ─── add ─────────────────────────────────────────────
 program
-  .command('add <component>')
-  .description('Add a component to your project')
+  .command('add <name>')
+  .description('Add a component, booster, or workflow to your project')
   .option('-f, --framework <framework>', 'Framework version (html, react, vue, nextjs)')
   .option('--dir <directory>', 'Override output directory')
   .option('--overwrite', 'Overwrite existing files', false)
+  .option('--booster', 'Install a booster (feature module)')
+  .option('--workflow', 'Scaffold a workflow (complete app template)')
+  .option('--overlay', 'Merge workflow into current project (workflow only)')
   .action(addCommand);
 
 // ─── login ───────────────────────────────────────────
@@ -57,18 +60,22 @@ program
 // ─── list ────────────────────────────────────────────
 program
   .command('list')
-  .description('List available components')
+  .description('List available components, boosters, or workflows')
   .option('-c, --category <category>', 'Filter by category')
   .option('--framework <framework>', 'Filter by supported framework')
-  .option('--pro', 'Show only pro components', false)
-  .option('--free', 'Show only free components', false)
+  .option('--pro', 'Show only pro items', false)
+  .option('--free', 'Show only free items', false)
+  .option('--boosters', 'List boosters instead of components')
+  .option('--workflows', 'List workflows instead of components')
   .action(listCommand);
 
 // ─── search ──────────────────────────────────────────
 program
   .command('search <query>')
-  .description('Search for components')
+  .description('Search for components, boosters, or workflows')
   .option('--framework <framework>', 'Filter by supported framework')
+  .option('--boosters', 'Search boosters only')
+  .option('--workflows', 'Search workflows only')
   .action(searchCommand);
 
 // ─── diff ────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astralkit/cli",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "AstralKit CLI — Install and manage UI components in your project",
   "license": "MIT",
   "bin": {

package/src/commands/add.js

@@ -2,22 +2,35 @@ const fs = require('fs');
 const path = require('path');
 const chalk = require('chalk');
 const ora = require('ora');
-const { getComponent } = require('../lib/api');
+const { getComponent, getBooster, getWorkflow } = require('../lib/api');
 const { getProjectConfig, detectFramework } = require('../lib/config');
 const { validateSlug, validateFramework, isSafePath } = require('../lib/validators');
 
-async function addCommand(componentSlug, options) {
-  // Validate inputs
+/**
+ * Route to the correct add handler based on flags.
+ */
+async function addCommand(nameOrSlug, options) {
+  if (options.booster) {
+    return addBooster(nameOrSlug, options);
+  }
+  if (options.workflow) {
+    return addWorkflow(nameOrSlug, options);
+  }
+  return addComponent(nameOrSlug, options);
+}
+
+/**
+ * Add a single UI component (existing behavior).
+ */
+async function addComponent(componentSlug, options) {
   if (!validateSlug(componentSlug)) process.exit(1);
-  if (!validateFramework(options.framework)) process.exit(1);
+  if (options.framework && !validateFramework(options.framework)) process.exit(1);
 
-  // Resolve framework
   const config = getProjectConfig();
   const framework = options.framework || config?.framework || detectFramework();
   const componentsDir = options.dir || config?.componentsDir || 'src/components/ui';
   const targetDir = path.resolve(process.cwd(), componentsDir, componentSlug);
 
-  // Check for existing files
   if (fs.existsSync(targetDir) && !options.overwrite) {
     console.log(chalk.yellow(`Component already exists at ${componentsDir}/${componentSlug}/`));
     console.log(chalk.gray('Use --overwrite to replace existing files.'));
@@ -37,10 +50,8 @@ async function addCommand(componentSlug, options) {
       return;
     }
 
-    // Create component directory
     fs.mkdirSync(targetDir, { recursive: true });
 
-    // Write each file (with path traversal protection)
     for (const file of data.files) {
       if (!isSafePath(targetDir, file.path)) {
         console.log(chalk.red(`  Skipping suspicious file path: ${file.path}`));
@@ -56,20 +67,17 @@ async function addCommand(componentSlug, options) {
 
     spinner.succeed(`Added ${chalk.cyan(data.name || componentSlug)} (${framework})`);
 
-    // Show files written
     console.log(chalk.gray(`  ${componentsDir}/${componentSlug}/`));
     for (const file of data.files) {
       console.log(chalk.gray(`    ${file.path}`));
     }
 
-    // Show dependencies to install
     if (data.dependencies?.length) {
       console.log();
       console.log(chalk.yellow('Install required dependencies:'));
       console.log(chalk.cyan(`  npm install ${data.dependencies.join(' ')}`));
     }
 
-    // Pro badge
     if (data.is_pro) {
       console.log();
       console.log(chalk.magenta('Pro component — thank you for your subscription!'));
@@ -77,28 +85,289 @@ async function addCommand(componentSlug, options) {
 
   } catch (err) {
     spinner.fail('Failed to add component.');
+    handleAddError(err, componentSlug, framework);
+  }
+}
+
+/**
+ * Add a booster (multi-file feature module with core + adapter).
+ */
+async function addBooster(slug, options) {
+  if (!validateSlug(slug)) process.exit(1);
+  if (options.framework && !validateFramework(options.framework)) process.exit(1);
+
+  const config = getProjectConfig();
+  const framework = options.framework || config?.framework || detectFramework();
+
+  const spinner = ora(`Fetching booster ${slug} (${framework})...`).start();
+
+  try {
+    const data = await getBooster(slug, framework);
+
+    const coreFiles = data.core_files || [];
+    const adapterFiles = data.adapter_files || [];
+
+    if (coreFiles.length === 0 && adapterFiles.length === 0) {
+      spinner.fail(`No files available for booster "${slug}" (${framework}).`);
+      if (data.frameworks?.length) {
+        console.log(chalk.gray(`Available frameworks: ${data.frameworks.join(', ')}`));
+      }
+      return;
+    }
+
+    // Resolve install paths
+    const corePath = options.dir || data.install_paths?.core || `src/lib/${slug}`;
+    const adapterPath = data.install_paths?.adapter || `src/components/${slug}`;
+    const coreDir = path.resolve(process.cwd(), corePath);
+    const adapterDir = path.resolve(process.cwd(), adapterPath);
+
+    // Check for existing files
+    if (!options.overwrite) {
+      const conflicts = [];
+      for (const file of coreFiles) {
+        const fp = path.resolve(coreDir, file.path);
+        if (fs.existsSync(fp)) conflicts.push(`${corePath}/${file.path}`);
+      }
+      for (const file of adapterFiles) {
+        const fp = path.resolve(adapterDir, file.path);
+        if (fs.existsSync(fp)) conflicts.push(`${adapterPath}/${file.path}`);
+      }
+      if (conflicts.length > 0) {
+        spinner.fail('Some files already exist.');
+        console.log(chalk.yellow('Conflicting files:'));
+        for (const c of conflicts) {
+          console.log(chalk.gray(`  ${c}`));
+        }
+        console.log(chalk.gray('Use --overwrite to replace existing files.'));
+        return;
+      }
+    }
+
+    // Write core files
+    let coreCount = 0;
+    for (const file of coreFiles) {
+      if (!isSafePath(coreDir, file.path)) {
+        console.log(chalk.red(`  Skipping suspicious file path: ${file.path}`));
+        continue;
+      }
+      const filePath = path.resolve(coreDir, file.path);
+      const fileDir = path.dirname(filePath);
+      if (!fs.existsSync(fileDir)) {
+        fs.mkdirSync(fileDir, { recursive: true });
+      }
+      fs.writeFileSync(filePath, file.content);
+      coreCount++;
+    }
+
+    // Write adapter files
+    let adapterCount = 0;
+    for (const file of adapterFiles) {
+      if (!isSafePath(adapterDir, file.path)) {
+        console.log(chalk.red(`  Skipping suspicious file path: ${file.path}`));
+        continue;
+      }
+      const filePath = path.resolve(adapterDir, file.path);
+      const fileDir = path.dirname(filePath);
+      if (!fs.existsSync(fileDir)) {
+        fs.mkdirSync(fileDir, { recursive: true });
+      }
+      fs.writeFileSync(filePath, file.content);
+      adapterCount++;
+    }
+
+    spinner.succeed(`Added booster ${chalk.cyan(data.name || slug)} (${framework})`);
+
+    // Show files written
+    if (coreCount > 0) {
+      console.log(chalk.gray(`  Core files → ${corePath}/`));
+      for (const file of coreFiles) {
+        console.log(chalk.gray(`    ${file.path}`));
+      }
+    }
+    if (adapterCount > 0) {
+      console.log(chalk.gray(`  Adapter files → ${adapterPath}/`));
+      for (const file of adapterFiles) {
+        console.log(chalk.gray(`    ${file.path}`));
+      }
+    }
+
+    // Dependencies
+    if (data.dependencies?.npm?.length) {
+      console.log();
+      console.log(chalk.yellow('Install required dependencies:'));
+      console.log(chalk.cyan(`  npm install ${data.dependencies.npm.join(' ')}`));
+    }
+
+    // Environment variables
+    if (data.dependencies?.env?.length) {
+      console.log();
+      console.log(chalk.yellow('Add these environment variables to your .env:'));
+      for (const envVar of data.dependencies.env) {
+        console.log(chalk.gray(`  ${envVar}=`));
+      }
+    }
+
+    // Post-install instructions
+    if (data.post_install) {
+      console.log();
+      console.log(chalk.white.bold('Setup instructions:'));
+      console.log(chalk.gray(data.post_install));
+    }
 
-    if (err.code === 'AUTH_REQUIRED') {
-      console.log(chalk.yellow(err.message));
-    } else if (err.code === 'PRO_REQUIRED') {
-      console.log(chalk.yellow(err.message));
+    if (data.is_pro) {
+      console.log();
+      console.log(chalk.magenta('Pro booster — thank you for your subscription!'));
+    }
+
+  } catch (err) {
+    spinner.fail('Failed to add booster.');
+    handleAddError(err, slug, framework);
+  }
+}
+
+/**
+ * Add a workflow (complete application scaffold).
+ */
+async function addWorkflow(slug, options) {
+  if (!validateSlug(slug)) process.exit(1);
+  if (options.framework && !validateFramework(options.framework)) process.exit(1);
+
+  const config = getProjectConfig();
+  const framework = options.framework || config?.framework || detectFramework();
+
+  const spinner = ora(`Fetching workflow ${slug} (${framework})...`).start();
+
+  try {
+    const data = await getWorkflow(slug, framework);
+
+    if (!data.files || data.files.length === 0) {
+      spinner.fail(`No files available for workflow "${slug}" (${framework}).`);
+      if (data.frameworks?.length) {
+        console.log(chalk.gray(`Available frameworks: ${data.frameworks.join(', ')}`));
+      }
+      return;
+    }
+
+    // Determine target directory
+    let targetDir;
+    if (options.overlay) {
+      // Overlay mode: write into current project
+      targetDir = path.resolve(process.cwd());
     } else {
-      // Try to parse API error for framework suggestions
-      try {
-        const body = JSON.parse(err.message.replace(/^API error \d+: /, ''));
-        if (body.supported_frameworks) {
-          console.log(chalk.yellow(`No ${framework} code available for "${componentSlug}".`));
-          console.log(chalk.gray(`Available frameworks: ${body.supported_frameworks.join(', ')}`));
-          console.log(chalk.gray(`Try: astralkit add ${componentSlug} --framework=${body.supported_frameworks[0]}`));
-          process.exit(1);
+      // Default: create a new subdirectory
+      const dirName = options.dir || slug;
+      targetDir = path.resolve(process.cwd(), dirName);
+    }
+
+    // Check for conflicts in overlay mode
+    if (options.overlay && !options.overwrite) {
+      const conflicts = [];
+      for (const file of data.files) {
+        const fp = path.resolve(targetDir, file.path);
+        if (fs.existsSync(fp)) conflicts.push(file.path);
+      }
+      if (conflicts.length > 0) {
+        spinner.fail(`${conflicts.length} file(s) would be overwritten.`);
+        console.log(chalk.yellow('Conflicting files:'));
+        for (const c of conflicts.slice(0, 20)) {
+          console.log(chalk.gray(`  ${c}`));
+        }
+        if (conflicts.length > 20) {
+          console.log(chalk.gray(`  ... and ${conflicts.length - 20} more`));
         }
-      } catch {
-        // Not a JSON parse error, show raw message
+        console.log(chalk.gray('Use --overwrite to replace existing files.'));
+        return;
+      }
+    }
+
+    // Check if target directory exists (non-overlay)
+    if (!options.overlay && fs.existsSync(targetDir) && !options.overwrite) {
+      spinner.fail(`Directory "${slug}/" already exists.`);
+      console.log(chalk.gray('Use --overwrite to replace, or --dir to specify a different name.'));
+      return;
+    }
+
+    // Write files
+    let fileCount = 0;
+    for (const file of data.files) {
+      if (!isSafePath(targetDir, file.path)) {
+        console.log(chalk.red(`  Skipping suspicious file path: ${file.path}`));
+        continue;
+      }
+      const filePath = path.resolve(targetDir, file.path);
+      const fileDir = path.dirname(filePath);
+      if (!fs.existsSync(fileDir)) {
+        fs.mkdirSync(fileDir, { recursive: true });
+      }
+      fs.writeFileSync(filePath, file.content);
+      fileCount++;
+    }
+
+    const targetLabel = options.overlay ? './' : `${slug}/`;
+    spinner.succeed(`Scaffolded workflow ${chalk.cyan(data.name || slug)} (${framework}) → ${targetLabel}`);
+
+    console.log(chalk.gray(`  ${fileCount} files written to ${targetLabel}`));
+
+    // Dependencies
+    if (data.dependencies?.npm?.length) {
+      console.log();
+      console.log(chalk.yellow('Install dependencies:'));
+      if (options.overlay) {
+        console.log(chalk.cyan(`  npm install ${data.dependencies.npm.join(' ')}`));
+      } else {
+        console.log(chalk.cyan(`  cd ${slug} && npm install`));
+      }
+    }
+
+    // Environment variables
+    if (data.dependencies?.env?.length) {
+      console.log();
+      console.log(chalk.yellow('Add these environment variables to your .env:'));
+      for (const envVar of data.dependencies.env) {
+        console.log(chalk.gray(`  ${envVar}=`));
+      }
+    }
+
+    // Post-install instructions
+    if (data.post_install) {
+      console.log();
+      console.log(chalk.white.bold('Setup instructions:'));
+      console.log(chalk.gray(data.post_install));
+    }
+
+    if (data.is_pro) {
+      console.log();
+      console.log(chalk.magenta('Pro workflow — thank you for your subscription!'));
+    }
+
+  } catch (err) {
+    spinner.fail('Failed to add workflow.');
+    handleAddError(err, slug, framework);
+  }
+}
+
+/**
+ * Shared error handler for add commands.
+ */
+function handleAddError(err, slug, framework) {
+  if (err.code === 'AUTH_REQUIRED') {
+    console.log(chalk.yellow(err.message));
+  } else if (err.code === 'PRO_REQUIRED') {
+    console.log(chalk.yellow(err.message));
+  } else {
+    try {
+      const body = JSON.parse(err.message.replace(/^API error \d+: /, ''));
+      if (body.supported_frameworks) {
+        console.log(chalk.yellow(`No ${framework} version available for "${slug}".`));
+        console.log(chalk.gray(`Available frameworks: ${body.supported_frameworks.join(', ')}`));
+        process.exit(1);
       }
-      console.error(chalk.red(err.message));
+    } catch {
+      // Not a JSON parse error
     }
-    process.exit(1);
+    console.error(chalk.red(err.message));
   }
+  process.exit(1);
 }
 
 module.exports = { addCommand };

package/src/commands/list.js

@@ -1,14 +1,29 @@
 const chalk = require('chalk');
 const ora = require('ora');
-const { listComponents } = require('../lib/api');
+const { listComponents, listBoosters, listWorkflows } = require('../lib/api');
 const { validateFramework } = require('../lib/validators');
 
+/**
+ * Route to the correct list handler based on flags.
+ */
 async function listCommand(options) {
-  // Validate --framework if provided
   if (options.framework && !validateFramework(options.framework)) {
     process.exit(1);
   }
 
+  if (options.boosters) {
+    return listBoostersCommand(options);
+  }
+  if (options.workflows) {
+    return listWorkflowsCommand(options);
+  }
+  return listComponentsCommand(options);
+}
+
+/**
+ * List UI components (existing behavior).
+ */
+async function listComponentsCommand(options) {
   const spinner = ora('Fetching components...').start();
 
   try {
@@ -26,7 +41,6 @@ async function listCommand(options) {
       return;
     }
 
-    // Group by category
     const grouped = {};
     for (const comp of data.components) {
       const cat = comp.category || 'Uncategorized';
@@ -61,4 +75,112 @@ async function listCommand(options) {
   }
 }
 
+/**
+ * List available boosters.
+ */
+async function listBoostersCommand(options) {
+  const spinner = ora('Fetching boosters...').start();
+
+  try {
+    const data = await listBoosters({
+      framework: options.framework,
+      pro: options.pro,
+      free: options.free,
+    });
+
+    spinner.stop();
+
+    if (!data.boosters || data.boosters.length === 0) {
+      console.log(chalk.yellow('No boosters found.'));
+      return;
+    }
+
+    const grouped = {};
+    for (const booster of data.boosters) {
+      const cat = booster.category || 'Uncategorized';
+      if (!grouped[cat]) grouped[cat] = [];
+      grouped[cat].push(booster);
+    }
+
+    console.log(chalk.blue.bold(`AstralKit Boosters (${data.boosters.length} total)`));
+    console.log();
+
+    for (const [category, boosters] of Object.entries(grouped)) {
+      console.log(chalk.white.bold(`  ${category}`));
+      for (const b of boosters) {
+        const proTag = b.is_pro ? chalk.magenta(' PRO') : '';
+        const frameworks = b.frameworks?.length
+          ? chalk.gray(` [${b.frameworks.join(', ')}]`)
+          : '';
+        console.log(`    ${chalk.cyan(b.slug)}${proTag}${frameworks}`);
+        if (b.description) {
+          console.log(`      ${chalk.gray(b.description)}`);
+        }
+      }
+      console.log();
+    }
+
+    console.log(chalk.gray('Run'), chalk.cyan('astralkit add --booster <name>'), chalk.gray('to install.'));
+
+  } catch (err) {
+    spinner.fail('Failed to list boosters.');
+    console.error(chalk.red(err.message));
+    process.exit(1);
+  }
+}
+
+/**
+ * List available workflows.
+ */
+async function listWorkflowsCommand(options) {
+  const spinner = ora('Fetching workflows...').start();
+
+  try {
+    const data = await listWorkflows({
+      framework: options.framework,
+      pro: options.pro,
+      free: options.free,
+    });
+
+    spinner.stop();
+
+    if (!data.workflows || data.workflows.length === 0) {
+      console.log(chalk.yellow('No workflows found.'));
+      return;
+    }
+
+    const grouped = {};
+    for (const workflow of data.workflows) {
+      const cat = workflow.category || 'Uncategorized';
+      if (!grouped[cat]) grouped[cat] = [];
+      grouped[cat].push(workflow);
+    }
+
+    console.log(chalk.blue.bold(`AstralKit Workflows (${data.workflows.length} total)`));
+    console.log();
+
+    for (const [category, workflows] of Object.entries(grouped)) {
+      console.log(chalk.white.bold(`  ${category}`));
+      for (const w of workflows) {
+        const proTag = w.is_pro ? chalk.magenta(' PRO') : '';
+        const frameworks = w.frameworks?.length
+          ? chalk.gray(` [${w.frameworks.join(', ')}]`)
+          : '';
+        console.log(`    ${chalk.cyan(w.slug)}${proTag}${frameworks}`);
+        if (w.description) {
+          console.log(`      ${chalk.gray(w.description)}`);
+        }
+      }
+      console.log();
+    }
+
+    console.log(chalk.gray('Run'), chalk.cyan('astralkit add --workflow <name>'), chalk.gray('to scaffold.'));
+
+  } catch (err) {
+    spinner.fail('Failed to list workflows.');
+    console.error(chalk.red(err.message));
+    process.exit(1);
+  }
+}
+
 module.exports = { listCommand };

package/src/commands/search.js

@@ -1,14 +1,29 @@
 const chalk = require('chalk');
 const ora = require('ora');
-const { listComponents } = require('../lib/api');
+const { listComponents, listBoosters, listWorkflows } = require('../lib/api');
 const { validateFramework } = require('../lib/validators');
 
+/**
+ * Route to the correct search handler based on flags.
+ */
 async function searchCommand(query, options) {
-  // Validate --framework if provided
   if (options.framework && !validateFramework(options.framework)) {
     process.exit(1);
   }
 
+  if (options.boosters) {
+    return searchBoostersCommand(query, options);
+  }
+  if (options.workflows) {
+    return searchWorkflowsCommand(query, options);
+  }
+  return searchComponentsCommand(query, options);
+}
+
+/**
+ * Search UI components (existing behavior).
+ */
+async function searchComponentsCommand(query, options) {
   const spinner = ora(`Searching for "${query}"...`).start();
 
   try {
@@ -50,4 +65,92 @@ async function searchCommand(query, options) {
   }
 }
 
+/**
+ * Search boosters.
+ */
+async function searchBoostersCommand(query, options) {
+  const spinner = ora(`Searching boosters for "${query}"...`).start();
+
+  try {
+    const data = await listBoosters({
+      search: query,
+      framework: options.framework,
+    });
+
+    spinner.stop();
+
+    if (!data.boosters || data.boosters.length === 0) {
+      console.log(chalk.yellow(`No boosters found for "${query}".`));
+      return;
+    }
+
+    console.log(chalk.blue.bold(`Found ${data.boosters.length} booster(s):`));
+    console.log();
+
+    for (const b of data.boosters) {
+      const proTag = b.is_pro ? chalk.magenta(' PRO') : '';
+      const cat = b.category ? chalk.gray(` (${b.category})`) : '';
+      console.log(`  ${chalk.cyan(b.slug)}${proTag}${cat}`);
+      if (b.description) {
+        console.log(`    ${chalk.gray(b.description.length > 80 ? b.description.slice(0, 80) + '...' : b.description)}`);
+      }
+      if (b.frameworks?.length) {
+        console.log(`    ${chalk.gray(`Frameworks: ${b.frameworks.join(', ')}`)}`);
+      }
+      console.log();
+    }
+
+    console.log(chalk.gray('Run'), chalk.cyan('astralkit add --booster <name>'), chalk.gray('to install.'));
+
+  } catch (err) {
+    spinner.fail('Search failed.');
+    console.error(chalk.red(err.message));
+    process.exit(1);
+  }
+}
+
+/**
+ * Search workflows.
+ */
+async function searchWorkflowsCommand(query, options) {
+  const spinner = ora(`Searching workflows for "${query}"...`).start();
+
+  try {
+    const data = await listWorkflows({
+      search: query,
+      framework: options.framework,
+    });
+
+    spinner.stop();
+
+    if (!data.workflows || data.workflows.length === 0) {
+      console.log(chalk.yellow(`No workflows found for "${query}".`));
+      return;
+    }
+
+    console.log(chalk.blue.bold(`Found ${data.workflows.length} workflow(s):`));
+    console.log();
+
+    for (const w of data.workflows) {
+      const proTag = w.is_pro ? chalk.magenta(' PRO') : '';
+      const cat = w.category ? chalk.gray(` (${w.category})`) : '';
+      console.log(`  ${chalk.cyan(w.slug)}${proTag}${cat}`);
+      if (w.description) {
+        console.log(`    ${chalk.gray(w.description.length > 80 ? w.description.slice(0, 80) + '...' : w.description)}`);
+      }
+      if (w.frameworks?.length) {
+        console.log(`    ${chalk.gray(`Frameworks: ${w.frameworks.join(', ')}`)}`);
+      }
+      console.log();
+    }
+
+    console.log(chalk.gray('Run'), chalk.cyan('astralkit add --workflow <name>'), chalk.gray('to scaffold.'));
+
+  } catch (err) {
+    spinner.fail('Search failed.');
+    console.error(chalk.red(err.message));
+    process.exit(1);
+  }
+}
+
 module.exports = { searchCommand };

package/src/lib/api.js

@@ -136,4 +136,56 @@ async function verifyAuth() {
   return response.json();
 }
 
-module.exports = { apiRequest, listComponents, getComponent, verifyAuth, API_BASE, CLI_VERSION };
+/**
+ * List boosters with optional filters.
+ */
+async function listBoosters({ framework, search, pro, free } = {}) {
+  const params = new URLSearchParams();
+  if (framework) params.set('framework', framework);
+  if (pro) params.set('pro', 'true');
+  if (free) params.set('free', 'true');
+  if (search) params.set('search', search);
+
+  const response = await apiRequest(`/api/cli/boosters?${params}`);
+  return response.json();
+}
+
+/**
+ * Get a single booster's details + files for installation.
+ */
+async function getBooster(slug, framework = 'nextjs') {
+  const response = await apiRequest(
+    `/api/cli/boosters/${encodeURIComponent(slug)}?framework=${encodeURIComponent(framework)}`
+  );
+  return response.json();
+}
+
+/**
+ * List workflows with optional filters.
+ */
+async function listWorkflows({ framework, search, pro, free } = {}) {
+  const params = new URLSearchParams();
+  if (framework) params.set('framework', framework);
+  if (pro) params.set('pro', 'true');
+  if (free) params.set('free', 'true');
+  if (search) params.set('search', search);
+
+  const response = await apiRequest(`/api/cli/workflows?${params}`);
+  return response.json();
+}
+
+/**
+ * Get a single workflow's details + files for scaffolding.
+ */
+async function getWorkflow(slug, framework = 'nextjs') {
+  const response = await apiRequest(
+    `/api/cli/workflows/${encodeURIComponent(slug)}?framework=${encodeURIComponent(framework)}`
+  );
+  return response.json();
+}
+
+module.exports = {
+  apiRequest, listComponents, getComponent, verifyAuth,
+  listBoosters, getBooster, listWorkflows, getWorkflow,
+  API_BASE, CLI_VERSION,
+};