brainy/CLI_AUGMENTATION_GUIDE.md

🧠 Brainy CLI - Augmentation Management Guide

Complete CLI Commands for Augmentations

Core Commands

# Initialize Brainy
brainy init

# Basic operations
brainy add "data"           # Add data
brainy search "query"       # Search
brainy chat                 # Interactive chat

Augmentation Management

# List all augmentations
brainy augment              # Shows installed & available
brainy augment list         # Same as above
brainy augment available    # Shows what can be installed

# Add augmentations
brainy augment add          # Interactive mode
brainy augment add neural-import    # Built-in
brainy augment add brainy-sentiment  # Community (from npm)
brainy augment add ai-memory --premium  # Premium (needs license)

# Remove augmentations
brainy augment remove sentiment-analyzer
brainy augment disable neural-import  # Disable but keep installed

# Configure augmentations
brainy augment config neural-import
brainy augment config notion-sync --set apiKey=xxx

Installing Different Types

1. Built-in Augmentations (Free, Always Available)

# These are included - just enable them
brainy augment enable neural-import
brainy augment enable auto-save
brainy augment enable basic-cache

2. Community Augmentations (Free, From npm)

# Step 1: Install from npm
npm install -g brainy-sentiment

# Step 2: Register with Brainy
brainy augment add brainy-sentiment

# Or in one command (coming soon)
brainy augment install brainy-sentiment  # Auto-installs from npm

3. Premium Augmentations (Paid, From @soulcraft/brain-cloud)

# Step 1: Set license key
export BRAINY_LICENSE_KEY=lic_xxxxxxxxxxxxx

# Step 2: Install premium package
npm install -g @soulcraft/brain-cloud

# Step 3: Add specific augmentations
brainy augment add ai-memory --premium
brainy augment add agent-coordinator --premium
brainy augment add notion-sync --premium

# Or add all premium at once
brainy augment add-premium --all

4. Brain Cloud Service (Managed, Everything Included)

# Connect to Brain Cloud (includes all augmentations)
brainy cloud --connect YOUR_CUSTOMER_ID

# Check status
brainy cloud --status

# Force sync
brainy cloud --sync

# Open dashboard
brainy cloud --dashboard

Working with Different Instances

Local Instance

# Add augmentation to local Brainy
cd my-project
brainy init
brainy augment add neural-import

Remote Hosted Instance

# Connect to remote Brainy server
brainy config set server.url https://my-brainy-server.com
brainy config set server.apiKey xxx

# Add augmentation to remote
brainy augment add sentiment-analyzer --remote

Brain Cloud Instance

# Everything is managed
brainy cloud --connect CUSTOMER_ID
# All augmentations automatically available

Interactive Mode Examples

Adding an Augmentation (No Arguments)

$ brainy augment add
? What type of augmentation? › 
  Built-in (Free)
  Community (npm)
  Premium (Licensed)
  
? Select augmentation › 
  ✓ neural-import (AI understanding)
  ○ sentiment-analyzer (Emotion detection)
  ○ translator (Multi-language)
  
? Configure now? (Y/n) › 

Configuring an Augmentation

$ brainy augment config notion-sync
? Notion API Token › secret_xxxxx
? Sync Mode › 
  ○ Read only
  ● Bidirectional
  ○ Write only
  
? Sync Interval (minutes) › 5
✅ Configuration saved!

CLI Implementation in brainy.js

// brainy augment command structure
program
  .command('augment [action] [name]')
  .description('Manage brain augmentations')
  .option('--type <type>', 'Augmentation type (sense|conduit|memory|etc)')
  .option('--premium', 'Premium augmentation')
  .option('--remote', 'Install on remote server')
  .action(async (action, name, options) => {
    if (!action) {
      // List all augmentations
      await listAugmentations()
    } else {
      switch(action) {
        case 'add':
        case 'install':
          await installAugmentation(name, options)
          break
        case 'remove':
          await removeAugmentation(name)
          break
        case 'config':
          await configureAugmentation(name, options)
          break
        case 'list':
          await listAugmentations()
          break
        case 'enable':
          await enableAugmentation(name)
          break
        case 'disable':
          await disableAugmentation(name)
          break
      }
    }
  })

Environment Variables

# For premium augmentations
export BRAINY_LICENSE_KEY=lic_xxxxxxxxxxxxx

# For Brain Cloud
export BRAIN_CLOUD_KEY=bc_xxxxxxxxxxxxx
export BRAIN_CLOUD_CUSTOMER_ID=cust_xxxxx

# For remote server
export BRAINY_SERVER_URL=https://my-server.com
export BRAINY_SERVER_KEY=xxx

Package.json Scripts

Add these to your project's package.json:

{
  "scripts": {
    "brain:init": "brainy init",
    "brain:augment": "brainy augment",
    "brain:add-sentiment": "brainy augment add brainy-sentiment",
    "brain:add-premium": "brainy augment add ai-memory --premium",
    "brain:cloud": "brainy cloud --connect"
  }
}

Error Messages & Solutions

# Missing license key
❌ Premium augmentation requires license key
💡 Set BRAINY_LICENSE_KEY or visit soulcraft.com

# Augmentation not found
❌ Augmentation 'xyz' not found
💡 Try: npm install brainy-xyz first

# Remote connection failed
❌ Cannot connect to remote server
💡 Check BRAINY_SERVER_URL and network connection

# Incompatible version
❌ Augmentation requires Brainy v0.62+
💡 Update: npm update @soulcraft/brainy

Summary

The CLI provides a unified interface for managing all augmentation types:

• Built-in: Always available, just enable
• Community: Install from npm, then add
• Premium: Need license, install from @soulcraft/brain-cloud
• Brain Cloud: Everything managed, just connect

The key is making it simple for beginners (interactive mode) while powerful for experts (direct commands).