brainy/docs/brainy-cli-1.0.md

# Brainy CLI 1.0 - Unified Command Interface 🧠

> **One CLI, All the Power - Simplified from 40+ commands to 9**

The Brainy 1.0 CLI provides a clean, unified interface to manage your intelligent database. Every command follows the same unified philosophy as the API.

## 🎯 What's New in CLI 1.0

### **Before (0.x): Command Chaos**
```bash
brainy add-smart "data"
brainy add-vector --literal "text" 
brainy search-similar "query"
brainy neural-import data.csv
# ... 40+ different commands
```

### **After (1.0): Unified Simplicity** 
```bash
brainy add "data"              # Smart by default
brainy search "query"          # Unified search
brainy import data.csv         # Neural import built-in
# Just 9 core commands total
```

## ⚡ Quick Start

### Installation
```bash
npm install @soulcraft/brainy@rc
```

### Initialize Your Brain
```bash
brainy init

# Interactive setup prompts:
# ✓ Storage type (memory, filesystem, S3)
# ✓ Encryption (recommended for sensitive data)
# ✓ Performance tier (small, medium, large, enterprise)
```

## 🧠 The 7 Core Data Commands

### 1. `brainy add` - Smart Data Addition
```bash
# Smart mode (auto-detects and processes)
brainy add "Elon Musk founded SpaceX in 2002"

# With metadata
brainy add "Customer feedback" --metadata '{"rating": 5, "source": "survey"}'

# Encrypted storage  
brainy add "Sensitive data" --encrypt

# Literal mode (bypass AI processing)
brainy add "Raw text data" --literal
```

### 2. `brainy search` - Unified Search
```bash
# Semantic search
brainy search "companies founded by Elon" 

# With filters
brainy search "customer feedback" --filter '{"rating": {"$gte": 4}}'

# Limit results
brainy search "AI projects" --limit 5

# Include metadata in output
brainy search "projects" --include-metadata
```

### 3. `brainy import` - Bulk Data Import
```bash
# CSV with automatic structure detection
brainy import data.csv

# JSON files 
brainy import documents.json --batch-size 100

# With neural processing (detects entities and relationships)
brainy import data.csv --neural

# Preview mode (analyze without importing)
brainy import data.csv --preview-only
```

### 4. `brainy update` - Smart Updates
```bash
# Update by ID
brainy update abc123 "Updated content"

# Update with new metadata
brainy update abc123 --metadata '{"status": "processed"}'

# Batch updates
brainy update --query "old content" --replace "new content"
```

### 5. `brainy delete` - Smart Deletion
```bash
# Soft delete (default - preserves indexes)
brainy delete abc123

# Hard delete (permanent removal)
brainy delete abc123 --hard

# Delete by query
brainy delete --query "outdated content" --confirm
```

### 6. `brainy add-noun` - Create Typed Entities
```bash
# Create person entity
brainy add-noun "Sarah Thompson" --type Person

# With rich metadata
brainy add-noun "Project Apollo" --type Project --metadata '{
  "status": "active",
  "budget": "$500K",
  "team_size": 12
}'
```

### 7. `brainy add-verb` - Create Relationships
```bash
# Create relationship between entities
brainy add-verb person_sarah_123 project_apollo_456 --type WorksWith

# With relationship metadata
brainy add-verb person_sarah_123 project_apollo_456 --type WorksWith --metadata '{
  "role": "Lead Designer",
  "allocation": "75%",
  "start_date": "2024-01-15"
}'
```

## 🎮 Interactive Commands

### `brainy chat` - Talk to Your Data
```bash
# Start interactive chat session
brainy chat

# Single question mode
brainy chat "What projects is Sarah working on?"

# With specific AI provider
brainy chat --provider anthropic "Analyze customer sentiment trends"

# Export conversation
brainy chat --export-session conversation.md
```

### `brainy status` - System Overview
```bash
# Complete system status
brainy status

# Per-service breakdown
brainy status --detailed

# Performance metrics
brainy status --metrics

# Storage utilization
brainy status --storage
```

## ⚙️ Configuration & Management

### `brainy config` - Configuration Management
```bash
# View current configuration
brainy config show

# Set configuration values
brainy config set storage.type filesystem
brainy config set ai.provider openai

# Encrypted configuration
brainy config set api_key "secret-key" --encrypt

# Reset to defaults
brainy config reset
```

## 🔍 Advanced Examples

### Entity and Relationship Management
```bash
# Create a complete knowledge graph
brainy add-noun "SoulCraft Labs" --type Organization
brainy add-noun "Brainy Database" --type Product  
brainy add-noun "Sarah Johnson" --type Person

# Connect them with relationships
brainy add-verb org_soulcraft_123 product_brainy_456 --type Creates
brainy add-verb person_sarah_789 org_soulcraft_123 --type WorksFor --metadata '{
  "position": "CTO",
  "start_date": "2023-06-01"
}'

# Query the graph
brainy search "SoulCraft team members" --include-relationships
```

### Bulk Operations
```bash
# Import and process a large dataset
brainy import customer-data.csv --neural --batch-size 500 --progress

# Update all records matching criteria
brainy update --query '{"status": "pending"}' --set '{"status": "processed"}' --confirm

# Export data with relationships
brainy export --format json --include-relationships --output backup.json
```

### Production Deployment
```bash
# Initialize for production with encryption
brainy init --storage s3 --encrypt --performance enterprise

# Configure S3 storage
brainy config set storage.s3.bucket my-production-brain
brainy config set storage.s3.region us-east-1

# Health check for monitoring
brainy status --health-check --json
```

## 🔧 Environment Variables

Configure Brainy using environment variables:

```bash
# Storage Configuration
export BRAINY_STORAGE_TYPE=s3
export BRAINY_S3_BUCKET=my-brainy-data
export BRAINY_S3_REGION=us-east-1

# AI Provider Configuration  
export BRAINY_AI_PROVIDER=openai
export BRAINY_OPENAI_API_KEY=your-api-key

# Performance Tuning
export BRAINY_PERFORMANCE_TIER=large
export BRAINY_CACHE_SIZE=1000000

# Security
export BRAINY_ENCRYPTION_KEY=your-32-char-encryption-key
```

## 📊 Output Formats

All commands support multiple output formats:

```bash
# JSON output
brainy search "projects" --format json

# Table output (default)
brainy status --format table

# CSV export
brainy search "customers" --format csv --output customers.csv

# Markdown reports
brainy status --format markdown --output report.md
```

## 🚀 Performance Tips

1. **Use batch operations** for large datasets:
   ```bash
   brainy import large-file.csv --batch-size 1000
   ```

2. **Enable caching** for repeated queries:
   ```bash
   brainy config set cache.enabled true
   brainy config set cache.size 100000
   ```

3. **Use filters** to reduce result sets:
   ```bash
   brainy search "content" --filter '{"date": {"$gte": "2024-01-01"}}'
   ```

4. **Monitor performance** with detailed status:
   ```bash
   brainy status --metrics --detailed
   ```

## 🆘 Help & Troubleshooting

```bash
# Get help for any command
brainy --help
brainy add --help
brainy search --help

# Verbose output for debugging
brainy search "query" --verbose

# Check system requirements
brainy status --system-info

# Validate configuration
brainy config validate
```

## 🔄 Migration from 0.x CLI

| Old Command (0.x) | New Command (1.0) | Notes |
|-------------------|-------------------|--------|
| `cortex init` | `brainy init` | Same functionality |
| `cortex add-smart "data"` | `brainy add "data"` | Smart by default |
| `cortex search-similar "q"` | `brainy search "q"` | Unified search |
| `cortex neural import file.csv` | `brainy import file.csv` | Neural processing built-in |
| `cortex chat "question"` | `brainy chat "question"` | Same interface |
| `cortex status --detailed` | `brainy status --detailed` | Enhanced metrics |

## 💡 Pro Tips

1. **Start with init**: Always run `brainy init` in new projects
2. **Use chat mode**: `brainy chat` is the fastest way to explore your data
3. **Enable encryption**: Use `--encrypt` for sensitive data
4. **Monitor status**: Regular `brainy status` checks keep you informed  
5. **Batch operations**: Use `--batch-size` for large imports

---

*For the complete API documentation, see [Brainy 1.0 Quick Start](getting-started/quick-start-1.0.md)*