syntaxis/docs/cli-quick-reference.md

⚡ CLI Quick Reference: Database Commands

TL;DR - No Special Database CLI Commands

We did NOT create CLI flags like --database sqlite or --surrealdb

Instead: Use configuration files to switch databases

---

Quickest Setup

# 1️⃣ CHOOSE YOUR DATABASE BY COPYING CONFIG

# For SQLite (default):
cp configs/database-default.toml configs/database.toml

# OR for SurrealDB:
cp configs/database-surrealdb.toml configs/database.toml

# 2️⃣ RUN CLI COMMANDS NORMALLY (no special flags!)

workspace create                    # Create project
workspace status                    # Show status
workspace checklist show            # Show checklist
workspace config show               # Show configuration

That's it! No other steps needed.

---

Available CLI Commands

Project Operations

workspace init [PATH] --type TYPE        # Initialize project
workspace create                         # Create from config
workspace migrate PATH                   # Migrate project
workspace status                         # Show status

Checklist Management

workspace checklist show [PHASE]         # Show checklist
workspace checklist complete ITEM_ID     # Mark complete
workspace checklist add DESCRIPTION      # Add item
workspace checklist types                # Show task types

Security

workspace security profile TYPE          # Set security profile
workspace security assess [--detailed]   # Assess security
workspace audit [--audit-vulns]          # Run audit

Phase Management

workspace phase current                  # Show current phase
workspace phase transition PHASE         # Move to phase

Database Operations ⭐

workspace migrate-db PATH                # Migrate DB to global
workspace migrate-db --scan ROOT         # Scan for databases
workspace migrate-db --status            # Show migration status

Configuration

workspace config show                    # Show configuration
workspace config validate                # Validate configuration

Tools

workspace tool list                      # List tools
workspace tool enable TOOL               # Enable tool
workspace tool disable TOOL              # Disable tool
workspace tool status                    # Show tool status

Import/Export

workspace export [--format FORMAT]       # Export data
workspace import FILE [--format FORMAT]  # Import data

Other

workspace search QUERY [filters]         # Search projects
workspace sbom generate                  # Generate SBOM
workspace plugin install PATH            # Install plugin
workspace batch FILE                     # Batch operations

---

Global Flags

Available with any command:

workspace --verbose COMMAND              # Verbose output
workspace -v COMMAND                     # Shorthand

workspace --project NAME COMMAND         # Specify project
workspace -p NAME COMMAND                # Shorthand

workspace --remote COMMAND               # Use remote API

workspace --api-url URL COMMAND          # API server URL

---

Database Configuration Files

SQLite Config (Recommended Default)

# File: configs/database-default.toml

[database]
engine = "sqlite"

[sqlite]
path = "~/.local/share/core/workspace.db"
max_connections = 5

SurrealDB Config (Alternative)

# File: configs/database-surrealdb.toml

[database]
engine = "surrealdb"

[surrealdb]
# Choose one mode:
url = "mem://"                           # In-memory (fast, no server)
# url = "file:///tmp/surrealdb.db"     # File-based (persistent)
# url = "ws://localhost:8000"          # Server mode (remote)

namespace = "syntaxis"
database = "projects"
max_connections = 10

---

How To Switch Databases

SQLite → SurrealDB

# 1. Copy SurrealDB config
cp configs/database-surrealdb.toml configs/database.toml

# 2. If using server mode, start server:
surreal start --bind 127.0.0.1:8000 memory

# 3. Run CLI (uses SurrealDB automatically)
workspace create

SurrealDB → SQLite

# 1. Copy SQLite config
cp configs/database-default.toml configs/database.toml

# 2. Run CLI (uses SQLite automatically)
workspace create

---

Database Migration Command

Most relevant for databases:

# Migrate from local to global database
workspace migrate-db PATH

# Example:
workspace migrate-db ~/.local/share/core/old.db

# What it does:
# 1. Opens local database (at PATH)
# 2. Loads all projects from local database
# 3. Saves all projects to global database
# 4. Creates backup of local database
# 5. Reports success

This command works with BOTH SQLite and SurrealDB!

---

Configuration Discovery

CLI automatically finds config in this order:

1. configs/database.toml                    ← PRIMARY (created by copying)
2. .project/database.toml
3. .vapora/database.toml
4. .coder/database.toml

Uses first one found ✅

---

Real-World Examples

Example 1: Local Development with SurrealDB In-Memory

# Step 1: Use SurrealDB config
cp configs/database-surrealdb.toml configs/database.toml

# Step 2: Ensure config has url = "mem://"

# Step 3: Run CLI (no server needed!)
workspace create              # Create project
workspace checklist show      # View checklist
workspace status              # Show status
workspace security assess     # Security assessment

Example 2: Production with SurrealDB Server

# Step 1: Use SurrealDB config
cp configs/database-surrealdb.toml configs/database.toml

# Step 2: Update config:
# url = "ws://surrealdb.example.com:8000"
# username = "app-user"
# password = "secure-password"

# Step 3: Run CLI against remote server
workspace create              # Connects to remote SurrealDB
workspace status              # Fetches from remote

Example 3: Team Using SQLite

# Step 1: Use SQLite config (already default)
cp configs/database-default.toml configs/database.toml

# Step 2: Share database file via Git LFS or cloud storage

# Step 3: All team members run same commands
workspace create              # Uses local SQLite
workspace checklist show      # Instant (no network)

---

What Commands Support Databases?

Command	Works with SQLite?	Works with SurrealDB?
workspace create	✅ Yes	✅ Yes
workspace status	✅ Yes	✅ Yes
workspace checklist	✅ Yes	✅ Yes
workspace security	✅ Yes	✅ Yes
workspace migrate-db	✅ Yes	✅ Yes
workspace export	✅ Yes	✅ Yes
workspace search	✅ Yes	✅ Yes
All other commands	✅ Yes	✅ Yes

Every CLI command works with both databases!

---

Troubleshooting

"Database not found"

# Make sure config exists:
ls -la configs/database.toml

# If missing, copy it:
cp configs/database-default.toml configs/database.toml

"SurrealDB server connection failed"

# Make sure server is running:
surreal start --bind 127.0.0.1:8000 memory

# Check config URL:
workspace config show

"Wrong database being used"

# Check which config is active:
workspace config show

# Copy the right config:
cp configs/database-{default|surrealdb}.toml configs/database.toml

---

Summary

Question	Answer
Any --database flag?	❌ No - use config files
How to switch databases?	Copy different config file
CLI code changes needed?	❌ No - all commands work both ways
Server needed for SQLite?	❌ No - local file
Server needed for SurrealDB in-memory?	❌ No - embedded
Server needed for SurrealDB server mode?	✅ Yes - one command
Which database is default?	SQLite (in database-default.toml)

---

Files To Know

configs/database-default.toml          ← SQLite config template
configs/database-surrealdb.toml        ← SurrealDB config template
configs/database.toml                  ← Active config (created by copying)

syntaxis-core/src/persistence/
    ├─ mod.rs                          ← Database trait
    ├─ sqlite_impl.rs                  ← SQLite implementation
    └─ surrealdb_impl.rs               ← SurrealDB implementation (800+ lines)

syntaxis-cli/src/handlers/
    ├─ migrate_db.rs                   ← Database migration
    ├─ config.rs                       ← Configuration management
    ├─ create.rs                       ← Project creation
    ├─ checklist.rs                    ← Checklist operations
    ├─ security.rs                     ← Security operations
    └─ ... (all use Database trait)

---

Key Insight

The architecture is beautiful:

One set of CLI commands
         ↓
Database trait (abstraction)
         ↓
    ┌──────────┬──────────┐
    ↓          ↓
 SQLite    SurrealDB

Same CLI code, different backends!
Database is selected via config, not code!

This is why no special CLI flags were needed - the design handles it elegantly through configuration.

---

That's it! You're ready to use either SQLite or SurrealDB with the CLI! 🚀