CLI Extension Management Guide¶

This guide explains how to install, manage, and uninstall SPM extensions using the command-line interface.

Table of Contents¶

Overview
Installing Extensions
Listing Installed Extensions
Uninstalling Extensions
Browsing Available Extensions
Searching Extensions
Extension Package Structure

Overview¶

The SPM CLI provides comprehensive extension management capabilities:

Install extensions from local .nupkg files
List all installed extensions with metadata
Uninstall extensions cleanly
Browse available extensions in the registry
Search for extensions by keywords

All extension management commands are under the spm extension namespace.

Installing Extensions¶

From Local Package File¶

Install an extension from a local .nupkg file:

spm extension install path/to/MyExtension.1.0.0.nupkg

What happens during installation:

Extraction - The .nupkg file is extracted to the Extensions/ directory
Metadata - Package metadata is read from the .nuspec file
File Organization - Files are organized according to NuGet conventions:
lib/net10.0/*.dll → Copied to extension directory
content/**/* → Static files (CSS, JS, images)
contentFiles/**/* → Content files
Registration - Extension metadata is saved to extension.json

Example Output:

Installing extension: MyCustomExtension.1.0.0.nupkg
  Source: Local file
  Extracting to: C:\Cesivi\Extensions
✓ Extension 'MyCustomExtension' v1.0.0 installed successfully
  Package ID: MyCustomExtension
  Version: 1.0.0
  Location: C:\Cesivi\Extensions\MyCustomExtension

From NuGet.org (Future Enhancement)¶

Direct installation from NuGet.org is planned for future releases:

# Planned feature (not yet implemented)
spm extension install MyCustomExtension --version 1.0.0

Current Workaround:

Download the .nupkg file from NuGet.org manually
Install using the local file path

Listing Installed Extensions¶

Basic List¶

List all installed extensions:

spm extension list

Example Output:

Installed SPM Extensions:
─────────────────────────────────
• MyCustomExtension v1.0.0
• CesiviExtensions.Example v1.0.0
• CustomTheme v2.1.0

Total: 3 extension(s)

Verbose Mode¶

Get detailed information about installed extensions:

spm extension list --verbose

Example Output:

Installed SPM Extensions:
─────────────────────────────────
• MyCustomExtension v1.0.0
  Location: C:\Cesivi\Extensions\MyCustomExtension
  Description: Custom field renderers and WebParts

• CesiviExtensions.Example v1.0.0
  Location: C:\Cesivi\Extensions\CesiviExtensions.Example
  Description: Example extension with field renderers, WebParts, and custom footer

Total: 2 extension(s)

Uninstalling Extensions¶

Remove an installed extension:

spm extension uninstall MyCustomExtension

Interactive Confirmation:

Uninstall extension 'MyCustomExtension'? (y/N): y
Uninstalling extension: MyCustomExtension
✓ Extension 'MyCustomExtension' uninstalled successfully

Skip Confirmation:

spm extension uninstall MyCustomExtension --yes

What happens during uninstallation:

Metadata Removal - Extension metadata is removed from configuration
File Deletion - Extension directory and all files are deleted
Cleanup - Any static file registrations are cleaned up

Browsing Available Extensions¶

Browse all available extensions in the registry:

spm extension browse

Example Output:

All Extensions:
═════════════════════════════════════════════════════════════
• Advanced Charts v1.2.0 [INSTALLED]
  ID: advanced-charts
  [WebPart] by SPM Community
  Create interactive charts using Chart.js and D3.js
  Downloads: 1250

• Custom Authentication v2.0.1
  ID: custom-auth
  [Extension] by Security Team
  SAML and OAuth 2.0 authentication providers
  Downloads: 890

Total: 13 extension(s)

Use 'spm extension info <id>' for detailed information
Use 'spm extension search <query>' to search extensions

Filter by Category:

spm extension browse --category WebPart

Available Categories:

FieldRenderer - Custom field rendering components
WebPart - Page components and widgets
Extension - General extensibility plugins
Theme - Visual themes and styles
Workflow - Workflow activities and triggers
Authentication - Authentication providers
Storage - Storage providers
Other - Miscellaneous extensions

Searching Extensions¶

Search for extensions by keywords:

spm extension search chart

Example Output:

Search results for 'chart':
═════════════════════════════════════════════════════════════
• Advanced Charts v1.2.0
  ID: advanced-charts
  [WebPart] by SPM Community
  Create interactive charts using Chart.js and D3.js
  Downloads: 1250

• Chart WebPart v1.0.0
  ID: chart-webpart
  [WebPart] by Core Team
  Simple chart rendering for lists
  Downloads: 340

Found 2 extension(s)

Search with Category Filter:

spm extension search authentication --category Extension

Search matches against:

Extension name
Description
Author
Tags

Extension Package Structure¶

NuGet Package (.nupkg) Format¶

Extensions are distributed as standard NuGet packages with the following structure:

MyCustomExtension.1.0.0.nupkg
├── MyCustomExtension.nuspec          # Package metadata
├── lib/
│   └── net10.0/
│       ├── MyCustomExtension.dll     # Extension assembly
│       └── Dependencies.dll          # (if any)
├── content/
│   └── wwwroot/
│       ├── css/
│       │   └── custom-styles.css     # Static CSS files
│       ├── js/
│       │   └── custom-scripts.js     # Static JavaScript files
│       └── images/
│           └── logo.png              # Images and assets
└── README.md                         # (optional)

Extension Metadata (extension.json)¶

After installation, each extension has a metadata file:

{
  "packageId": "MyCustomExtension",
  "version": "1.0.0",
  "installedDate": "2026-01-17T10:30:00Z",
  "enabled": true
}

.nuspec File Example¶

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
  <metadata>
    <id>MyCustomExtension</id>
    <version>1.0.0</version>
    <authors>Your Name</authors>
    <description>Custom field renderers and WebParts for SPM</description>
    <tags>spm extension field-renderer webpart</tags>
    <dependencies>
      <group targetFramework="net10.0">
        <dependency id="Cesivi.WebUI" version="1.0.0" />
      </group>
    </dependencies>
  </metadata>
</package>

Creating Your Own Extension Package¶

1. Build Your Extension Project¶

cd MyCustomExtension
dotnet build --configuration Release

2. Create NuGet Package¶

dotnet pack --configuration Release

This creates bin/Release/MyCustomExtension.1.0.0.nupkg

3. Install Locally for Testing¶

spm extension install bin/Release/MyCustomExtension.1.0.0.nupkg

4. Verify Installation¶

spm extension list --verbose

Troubleshooting¶

Extension Not Loading¶

Problem: Extension installed but not appearing in WebUI

Solutions:

Restart Server - Extensions are loaded at startup
```
spm restart
```
Check Extension Path - Verify files are in Extensions/ directory
```
spm extension list --verbose
```
Check Logs - Look for extension loading errors
```
tail -f logs/cesivi.log
```

Installation Failed¶

Problem: spm extension install fails with extraction error

Solutions:

Verify Package - Ensure .nupkg file is valid:

# Extract manually to inspect contents
unzip MyExtension.nupkg -d temp/

Check Permissions - Ensure write access to Extensions/ directory
Check Disk Space - Ensure sufficient disk space

Uninstall Failed¶

Problem: Extension directory not deleted

Solutions:

Close Applications - Ensure no processes are using extension files
Manual Deletion - Delete extension directory manually:
```
rm -rf Extensions/MyCustomExtension
```

Best Practices¶

Extension Installation¶

Review Source - Only install extensions from trusted sources
Test in Development - Test extensions in dev environment first
Read Documentation - Check extension documentation before installing
Backup Configuration - Backup appsettings.json before installing

Extension Development¶

Follow Naming Conventions - Use clear, descriptive package IDs
Version Properly - Follow semantic versioning (SemVer)
Include Documentation - Provide README and usage examples
Test Thoroughly - Test installation, operation, and uninstallation
Declare Dependencies - Specify all required dependencies in .nuspec

Extension Management¶

Keep Extensions Updated - Regularly check for updates
Monitor Performance - Watch for performance impacts
Limit Extensions - Only install needed extensions
Regular Cleanup - Uninstall unused extensions

Extensibility Guide - Developing custom extensions
Extension Templates Guide - Using dotnet templates
Extension Registry - Publishing to the registry
CLI Reference - Complete CLI command reference

Last Updated: 2026-01-17 Created for: PLAN-149 Phase 3.3 (Extension CLI Install/Package)

CLI Extension Management Guide¶

Table of Contents¶

Overview¶

Installing Extensions¶

From Local Package File¶

From NuGet.org (Future Enhancement)¶

Listing Installed Extensions¶

Basic List¶

Verbose Mode¶

Uninstalling Extensions¶

Browsing Available Extensions¶

Searching Extensions¶

Extension Package Structure¶

NuGet Package (.nupkg) Format¶

Extension Metadata (extension.json)¶

.nuspec File Example¶

Creating Your Own Extension Package¶

1. Build Your Extension Project¶

2. Create NuGet Package¶

3. Install Locally for Testing¶

4. Verify Installation¶

Troubleshooting¶

Extension Not Loading¶

Installation Failed¶

Uninstall Failed¶

Best Practices¶

Extension Installation¶

Extension Development¶

Extension Management¶

Related Documentation¶