SPM CLI Quick Start Guide¶

Get started with the Cesivi Server command-line tool (spm) in minutes.

Installation¶

Prerequisites¶

.NET 10.0 SDK or later
Git (for cloning the repository)

Step 1: Build and Install¶

# Clone the repository (if not already cloned)
git clone https://github.com/yourusername/Cesivi.git
cd Cesivi

# Build the CLI project
cd Cesivi.Cli
dotnet pack -c Release

# Install as global tool
dotnet tool install -g --add-source ./bin/Release spm

# Verify installation
spm --version

Step 2: First Run¶

# Start the server (defaults to http://localhost:5000)
spm server start

# In another terminal, check status
spm server status

# Check health
spm server health

Step 3: Stop the Server¶

spm server stop

Common Tasks¶

Managing the Server¶

Start with Custom Port¶

spm server start --port 8080

Start with SQL Server Storage¶

spm server start \
  --storage SqlServer \
  --connection "Server=localhost;Database=Cesivi;Trusted_Connection=true;"

Start with Redis for Multi-Server¶

spm server start \
  --redis "localhost:6379" \
  --storage SqlServer \
  --connection "Server=localhost;Database=Cesivi;..."

Creating Custom Extensions¶

Scaffold a WebPart¶

# Create a new chart webpart
spm scaffold webpart --name SalesChart --category Charts

# Navigate to generated project
cd SalesChartWebPart

# Edit SalesChartWebPart.cs to implement your logic
# Then build and pack
dotnet build
dotnet pack -c Release

# Install the webpart
spm extension install bin/Release/SalesChartWebPart.1.0.0.nupkg

# Verify installation
spm extension list

Scaffold a Field Renderer¶

# Create a star rating field renderer
spm scaffold field-renderer --name StarRating

cd StarRatingFieldRenderer

# Edit StarRatingFieldRenderer.cs
# Implement RenderDisplayAsync() and RenderEditAsync()

dotnet build
dotnet pack -c Release
spm extension install bin/Release/StarRatingFieldRenderer.1.0.0.nupkg

Scaffold a Complete Extension Project¶

# Create a full extension project
spm scaffold project --name MyCompany.CesiviExtensions

cd MyCompany.CesiviExtensions

# Project structure:
# - WebParts/ExampleWebPart.cs
# - FieldRenderers/ExampleFieldRenderer.cs
# - Extensions/ExampleExtension.cs
# - wwwroot/ (for CSS/JS assets)

# Build and install
dotnet build
dotnet pack -c Release
spm extension install bin/Release/MyCompany.CesiviExtensions.1.0.0.nupkg

Backup and Restore¶

Create a Backup¶

# Create backup with default settings (ZIP, normal compression)
spm backup --output backup-2026-01-11.zip

# Create backup with best compression
spm backup --output backup.zip --compression best

# Create 7z backup
spm backup --output backup.7z --format 7z

Restore from Backup¶

# Validate backup first
spm restore --input backup.zip --validate-only

# Restore (will prompt for confirmation)
spm restore --input backup.zip

# Restore and overwrite existing data
spm restore --input backup.zip --overwrite --yes

Migrating Between Storage Providers¶

LiteDb to SQL Server¶

# Dry-run migration
spm migrate \
  --from LiteDb \
  --source-connection "Filename=./Data/Cesivi.db" \
  --to SqlServer \
  --target-connection "Server=localhost;Database=Cesivi;Trusted_Connection=true;" \
  --validate-only

# Execute migration
spm migrate \
  --from LiteDb \
  --source-connection "Filename=./Data/Cesivi.db" \
  --to SqlServer \
  --target-connection "Server=localhost;Database=Cesivi;Trusted_Connection=true;"

FileSystem to PostgreSQL¶

spm migrate \
  --from FileSystem \
  --to PostgreSql \
  --target-connection "Host=localhost;Database=sharepoint_mock;Username=postgres;Password=..."

Diagnostics¶

View Logs¶

# Show last 100 lines
spm logs

# Show last 500 lines
spm logs --lines 500

# Show only errors
spm logs --level Error

Clear Cache¶

# Clear all caches
spm cache clear

# Clear only session cache
spm cache clear --type session

Fetch Metrics¶

# Fetch Prometheus metrics
spm metrics

# Fetch from custom endpoint
spm metrics --url http://spm.example.com:8080

Validate Storage¶

# Validate default storage
spm validate

# Validate specific storage provider
spm validate --storage-provider SqlServer --connection "..."

Real-World Scenarios¶

Scenario 1: Local Development¶

# 1. Start server for development
spm server start --port 5000

# 2. Server is now running at http://localhost:5000

# 3. Develop your custom extension in a separate terminal
cd ~/my-extensions
spm scaffold webpart --name MyDashboard --category Charts

# 4. Edit MyDashboardWebPart.cs, implement your dashboard

# 5. Build and install
cd MyDashboardWebPart
dotnet build
dotnet pack -c Release
spm extension install bin/Release/MyDashboardWebPart.1.0.0.nupkg

# 6. Navigate to http://localhost:5000 and add your webpart to a page

# 7. When done, stop server
spm server stop

Scenario 2: Testing Before Production¶

# 1. Create backup of current state
spm backup --output backup-before-test.zip

# 2. Test your changes
# (run your tests, make changes, etc.)

# 3. If something goes wrong, restore
spm restore --input backup-before-test.zip --overwrite --yes

# 4. Otherwise, create a new backup
spm backup --output backup-after-test.zip

Scenario 3: Production Deployment¶

# 1. Stop development server (if running)
spm server stop

# 2. Create backup of development data
spm backup --output dev-backup.zip --compression best

# 3. Migrate to production SQL Server
spm migrate \
  --from LiteDb \
  --source-connection "Filename=./Data/Cesivi.db" \
  --to SqlServer \
  --target-connection "Server=prod-sql.example.com;Database=Cesivi;User Id=spm_user;Password=..."

# 4. Validate migrated data
spm validate --storage-provider SqlServer

# 5. Start production server
spm server start \
  --port 80 \
  --storage SqlServer \
  --connection "Server=prod-sql.example.com;Database=Cesivi;User Id=spm_user;Password=..." \
  --redis "prod-redis.example.com:6379"

# 6. Check health
spm server health --endpoint http://prod-spm.example.com

Scenario 4: Multi-Server Load Balanced Setup¶

# On each server:

# 1. Install extensions
spm extension install MyCompany.CesiviExtensions.1.0.0.nupkg

# 2. Start server with Redis and shared SQL storage
spm server start \
  --storage SqlServer \
  --connection "Server=shared-sql;Database=Cesivi;..." \
  --redis "shared-redis:6379"

# 3. Verify health
spm server health

# On load balancer:
# Configure to distribute traffic across servers
# Use /health endpoint for health checks

Troubleshooting¶

Server Won't Start¶

# Check if port is already in use
netstat -ano | findstr :5000  # Windows
lsof -i :5000                 # Linux/macOS

# Check server status
spm server status

# Try a different port
spm server start --port 8080

Extension Won't Install¶

# Verify package exists
ls MyExtension.1.0.0.nupkg

# Check package structure
unzip -l MyExtension.1.0.0.nupkg

# Try absolute path
spm extension install /full/path/to/MyExtension.1.0.0.nupkg

Migration Fails¶

# Validate source storage
spm validate --storage-provider LiteDb

# Check connection strings
# Ensure target database exists

# Try dry-run first
spm migrate --from LiteDb --to SqlServer --validate-only

Can't Connect to Server¶

# Check if server is running
spm server status

# Check health endpoints
spm server health

# Check firewall rules
# Ensure port is open

# Check server logs
spm logs --level Error

Next Steps¶

CLI Reference - Complete command reference
Extensibility Guide - Learn extension development
API Reference - Server API documentation
Deployment Guide - Production deployment options

Tips and Best Practices¶

Development¶

Always create backups before major changes

spm backup --output backup-$(date +%Y%m%d).zip

Use validate-only for dry runs

spm migrate --from A --to B --validate-only
spm restore --input backup.zip --validate-only

Test extensions locally before deploying

spm server start --port 5001  # Separate test server

Production¶

Use SQL Server or PostgreSQL for production
Avoid FileSystem/LiteDb in production
Better performance and reliability
Enable Redis for multi-server setups
Required for session sharing
Improves cache performance

Monitor with metrics endpoint

spm metrics --url http://prod-spm.example.com

Set up automated backups

# Cron job example (daily backup at 2 AM)
0 2 * * * spm backup --output /backups/spm-$(date +\%Y\%m\%d).zip

Extension Development¶

Use scaffolding for consistency
Generates proper project structure
Includes NuGet packaging configuration

Test before packaging

dotnet build
dotnet test  # If you have tests
dotnet pack -c Release

Version your extensions properly
Follow semantic versioning (1.0.0, 1.0.1, 1.1.0, 2.0.0)
Update version in .csproj before packaging
Document your extensions
Include README.md with usage instructions
Document configuration options
Provide examples

Getting Help¶

View command help:

spm --help
spm server --help
spm scaffold webpart --help

Check version:
```
spm version --verbose
```
Report issues:
GitHub: https://github.com/yourusername/Cesivi/issues
Include spm version output
Include error messages from spm logs