Skip to content

SPM CLI Reference

Complete reference for the Cesivi Server command-line tool (spm).

Table of Contents

Installation

Install as Global Tool

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

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

# Verify installation
spm --version

Update

dotnet tool update -g spm

Uninstall

dotnet tool uninstall -g spm

Server Management

spm server start

Start the SPM server with optional configuration overrides.

Syntax: 

spm server start [options]

Options: - --port, -p <port> - Port to run the server on (default: 5000) - --storage, -s <provider> - Storage provider (InMemory, FileSystem, LiteDb, SqlServer, PostgreSql) - --connection, -c <connection-string> - Storage connection string - --redis, -r <connection-string> - Redis connection string for distributed state

Examples: 

# Start with defaults
spm server start

# Start on port 8080
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 distributed state
spm server start --redis "localhost:6379"

Environment Variables: - ASPNETCORE_URLS - Server URLs (set via --port) - SPM_STORAGE_PROVIDER - Storage provider (set via --storage) - SPM_STORAGE_CONNECTION - Storage connection string (set via --connection) - SPM_REDIS_CONNECTION - Redis connection string (set via --redis)

spm server stop

Stop the running SPM server gracefully.

Syntax: 

spm server stop

Notes: - Sends SIGTERM to server process - Waits up to 30 seconds for graceful shutdown - Cleans up PID file on successful stop

spm server status

Check the status of the SPM server.

Syntax: 

spm server status

Output: - Status: Running or Not Running - PID: Process ID - Uptime: Days, hours, minutes - Memory: Memory usage in MB

Exit Codes: - 0 - Server is running - 1 - Server is not running

spm server health

Check the health of the SPM server via HTTP endpoints.

Syntax: 

spm server health [options]

Options: - --endpoint, -e <url> - Server endpoint URL (default: http://localhost:5000)

Examples: 

# Check localhost:5000
spm server health

# Check custom endpoint
spm server health --endpoint http://spm.example.com:8080

Checks: - /health - Overall health status - /ready - Readiness probe (ready to accept requests) - /live - Liveness probe (server is alive)

Exit Codes: - 0 - All health checks passed - 1 - One or more health checks failed

Data Management

spm migrate

Migrate data between storage providers.

Syntax: 

spm migrate --from <provider> --to <provider> [options]

Required Options: - --from, -f <provider> - Source storage provider - --to, -t <provider> - Target storage provider

Optional Options: - --source-connection, -sc <connection-string> - Source connection string - --target-connection, -tc <connection-string> - Target connection string - --validate-only, -v - Validate migration without executing

Providers: - InMemory - FileSystem - LiteDb - SqlServer - PostgreSql

Examples: 

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

# Dry-run migration
spm migrate --from FileSystem --to LiteDb --validate-only

Notes: - Migration leverages existing CesiviStorageConverter tool - Shows progress bar during migration - Validates data integrity after migration - Support for all provider combinations

spm backup

Create a backup of SPM storage.

Syntax: 

spm backup --output <file> [options]

Required Options: - --output, -o <file> - Output backup file path (e.g., backup.zip)

Optional Options: - --format, -f <format> - Backup format: zip, 7z (default: zip) - --compression, -c <level> - Compression level: fast, normal, best (default: normal)

Examples: 

# Create backup with default settings
spm backup --output backup-2026-01-11.zip

# Create 7z backup with best compression
spm backup --output backup.7z --format 7z --compression best

Output: - Progress bar showing sites, lists, items, files backed up - Final backup file size - Includes all sites, lists, items, files, users, permissions

spm restore

Restore SPM storage from a backup.

Syntax: 

spm restore --input <file> [options]

Required Options: - --input, -i <file> - Input backup file path

Optional Options: - --overwrite - Overwrite existing data (default: merge) - --validate-only, -v - Validate backup without restoring - --yes, -y - Skip confirmation prompt

Examples: 

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

# Restore with confirmation
spm restore --input backup.zip

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

Notes: - Default mode is merge (adds to existing data) - Use --overwrite to replace existing data - Always prompts for confirmation unless --yes is specified

spm validate

Validate SPM storage integrity.

Syntax: 

spm validate [options]

Optional Options: - --storage-provider, -s <provider> - Storage provider to validate - --connection, -c <connection-string> - Storage connection string

Examples: 

# Validate default storage
spm validate

# Validate SQL Server storage
spm validate --storage-provider SqlServer --connection "Server=localhost;Database=Cesivi;..."

Checks: - Orphaned items (items without parent lists) - Broken references (invalid lookup/user references) - Missing files (file entries without actual files)

Output: - Detailed validation report - Error count, warning count - Suggestions for fixing issues

Extension Management

spm extension install

Install an SPM extension from a NuGet package.

Syntax: 

spm extension install <package> [options]

Arguments: - <package> - NuGet package file path (.nupkg) or package ID

Optional Options: - --version, -v <version> - Package version (when using package ID)

Examples: 

# Install from local .nupkg file
spm extension install MyCompany.CesiviExtensions.1.0.0.nupkg

# Install from NuGet.org (not yet implemented)
spm extension install MyCompany.CesiviExtensions --version 1.0.0

Process: 1. Extracts package to Extensions/ folder 2. Registers extension in appsettings.json 3. Verifies SPM version compatibility

spm extension list

List installed SPM extensions.

Syntax: 

spm extension list [options]

Optional Options: - --verbose, -v - Show detailed information

Examples: 

# List extensions
spm extension list

# List with details
spm extension list --verbose

Output: - Extension name - Version (verbose mode) - Author (verbose mode) - Install location (verbose mode) - WebParts/Renderers/Extensions count (verbose mode)

spm extension uninstall

Uninstall an SPM extension.

Syntax: 

spm extension uninstall <name> [options]

Arguments: - <name> - Extension name to uninstall

Optional Options: - --yes, -y - Skip confirmation prompt

Examples: 

# Uninstall with confirmation
spm extension uninstall MyCompany.CesiviExtensions

# Uninstall without confirmation
spm extension uninstall MyCompany.CesiviExtensions --yes

Process: 1. Removes extension from Extensions/ folder 2. Removes registration from appsettings.json 3. Prompts for confirmation unless --yes

Scaffolding

spm scaffold webpart

Generate boilerplate code for a new WebPart.

Syntax: 

spm scaffold webpart --name <name> [options]

Required Options: - --name, -n <name> - WebPart name (e.g., MyChart)

Optional Options: - --category, -c <category> - WebPart category (default: Custom) - Categories: Lists, Content, Media, Forms, Search, Social, Charts, Custom - --output-dir, -o <path> - Output directory (default: current directory)

Examples: 

# Scaffold a chart webpart
spm scaffold webpart --name SalesChart --category Charts

# Scaffold to specific directory
spm scaffold webpart --name MyWebPart --output-dir ./MyExtensions/

Generated Files: - {Name}WebPart.cs - WebPart implementation - {Name}WebPart.csproj - Project file for NuGet packaging - README.md - Installation and usage instructions

Next Steps: 1. cd {Name}WebPart 2. Implement RenderAsync() method 3. dotnet build 4. dotnet pack -c Release 5. spm extension install bin/Release/{Name}WebPart.1.0.0.nupkg

spm scaffold field-renderer

Generate boilerplate code for a new field renderer.

Syntax: 

spm scaffold field-renderer --name <name> [options]

Required Options: - --name, -n <name> - Field renderer name (e.g., StarRating)

Optional Options: - --output-dir, -o <path> - Output directory (default: current directory)

Examples: 

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

Generated Files: - {Name}FieldRenderer.cs - Field renderer implementation - {Name}FieldRenderer.csproj - Project file for NuGet packaging

Next Steps: 1. Implement RenderDisplayAsync() and RenderEditAsync() 2. Implement ParseValueAsync() for form submission 3. Build and package

spm scaffold extension

Generate boilerplate code for a new extension.

Syntax: 

spm scaffold extension --name <name> [options]

Required Options: - --name, -n <name> - Extension name (e.g., CustomFooter)

Optional Options: - --extension-point, -e <point> - Extension point (default: Scripts) - Points: Head, Styles, BeforeContent, AfterContent, Scripts - --output-dir, -o <path> - Output directory (default: current directory)

Examples: 

# Scaffold a footer extension
spm scaffold extension --name CustomFooter --extension-point AfterContent

Generated Files: - {Name}Extension.cs - Extension implementation - {Name}Extension.csproj - Project file for NuGet packaging

spm scaffold project

Generate a complete extension project structure.

Syntax: 

spm scaffold project --name <name> [options]

Required Options: - --name, -n <name> - Project name (e.g., MyCompany.CesiviExtensions)

Optional Options: - --output-dir, -o <path> - Output directory (default: current directory)

Examples: 

# Scaffold a complete extension project
spm scaffold project --name MyCompany.CesiviExtensions

Generated Structure: 

MyCompany.CesiviExtensions/
├── WebParts/
│   └── ExampleWebPart.cs
├── FieldRenderers/
│   └── ExampleFieldRenderer.cs
├── Extensions/
│   └── ExampleExtension.cs
├── wwwroot/
├── MyCompany.CesiviExtensions.csproj
└── README.md

Diagnostics

spm logs

View SPM server logs.

Syntax: 

spm logs [options]

Optional Options: - --lines, -n <count> - Number of lines to show (default: 100) - --follow, -f - Follow log output (live tail) - --level, -l <level> - Filter by log level (Info, Debug, Warning, Error)

Examples: 

# Show last 100 lines
spm logs

# Show last 500 lines
spm logs --lines 500

# Follow logs (not yet implemented)
spm logs --follow

# Show only errors
spm logs --level Error

spm cache clear

Clear SPM cache.

Syntax: 

spm cache clear [options]

Optional Options: - --type, -t <type> - Cache type: session, cache, all (default: all)

Examples: 

# Clear all caches
spm cache clear

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

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

spm metrics

Fetch and display Prometheus metrics.

Syntax: 

spm metrics [options]

Optional Options: - --endpoint, -e <path> - Metrics endpoint path (default: /metrics) - --url, -u <url> - Server URL (default: http://localhost:5000)

Examples: 

# Fetch metrics from localhost
spm metrics

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

Output: - Raw Prometheus metrics in text format - Includes: request count, duration, cache hit ratio, etc.

spm version

Show SPM version information.

Syntax: 

spm version [options]

Optional Options: - --verbose, -v - Show detailed version information

Examples: 

# Show version
spm version

# Show detailed version info
spm version --verbose

Output: - CLI version - .NET runtime version - Assembly versions (verbose) - Environment info (verbose)

Environment Variables

The following environment variables can be used to configure SPM:

Server Configuration

  • ASPNETCORE_URLS - Server URLs (e.g., http://localhost:5000)
  • ASPNETCORE_ENVIRONMENT - Environment name (Development, Staging, Production)

Storage Configuration

  • SPM_STORAGE_PROVIDER - Storage provider (InMemory, FileSystem, LiteDb, SqlServer, PostgreSql)
  • SPM_STORAGE_CONNECTION - Storage connection string

Distributed State Configuration

  • SPM_REDIS_CONNECTION - Redis connection string for distributed state
  • SPM_DISTRIBUTED_STATE_PROVIDER - Distributed state provider (InMemory, Redis)

Authentication Configuration

  • SPM_AUTH_ENABLED - Enable/disable authentication (true/false)
  • SPM_AUTH_PROVIDER - Authentication provider (NTLM, Basic, Bearer, Forms)

Logging Configuration

  • SPM_LOG_LEVEL - Minimum log level (Trace, Debug, Information, Warning, Error, Critical)
  • SPM_LOG_FILE - Log file path

Proxy Configuration

  • CESIVI_PROXY_PORT - Proxy server port (default: 8080)

Exit Codes

The spm CLI uses standard exit codes:

  • 0 - Success
  • 1 - General error
  • 2 - Command not found
  • 130 - Process terminated by user (Ctrl+C)

Examples

Complete Development Workflow

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

# 2. Check server status
spm server status

# 3. Scaffold a new webpart
spm scaffold webpart --name MyChart --category Charts

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

# 5. List installed extensions
spm extension list

# 6. Create backup before testing
spm backup --output backup-before-test.zip

# 7. Test the webpart (navigate to http://localhost:5000)

# 8. If needed, restore from backup
spm restore --input backup-before-test.zip

# 9. Stop server
spm server stop

Production Migration Workflow

# 1. Validate current storage
spm validate --storage-provider LiteDb

# 2. Create backup
spm backup --output backup-pre-migration.zip --compression best

# 3. Dry-run migration
spm migrate \
  --from LiteDb \
  --to SqlServer \
  --target-connection "Server=prod-sql;Database=Cesivi;..." \
  --validate-only

# 4. Execute migration
spm migrate \
  --from LiteDb \
  --to SqlServer \
  --target-connection "Server=prod-sql;Database=Cesivi;..."

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

# 6. Update server configuration
# Edit appsettings.json or use environment variables

# 7. Restart server
spm server stop
spm server start --storage SqlServer

See Also